Spec driven development AI workflows still pay off when the spec records the decisions the model would otherwise make for you. Frontier models fill gaps well, so the spec can get shorter, but it has to keep the why behind each choice. Skip it for work you can review in minutes, and start it from the conversation where your team made the decision.
Disclosure. We make Chief, which captures meetings and turns them into work, including handing a session to a coding agent. That gives us an interest in where specs come from, so weigh what follows with that in mind.
Key Takeaways
- Frontier models fill gaps well, which is the risk: where the spec is silent, the model decides for you.
- A short spec still pays when it records decisions, constraints and rejected options. Descriptions of behaviour go stale faster, and the code already holds them.
- Skip the spec for exploratory work, or work small enough to review in minutes.
- People often argue the why behind a decision out loud before anyone writes it down. Starting the spec from that conversation beats rebuilding it from memory.
- Someone still has to read and approve the spec. You can hand the drafting to an agent, but not the review.
What is spec-driven development?#
It means writing the spec before the AI writes the code. Birgitta Böckeler's definition, from martinfowler.com in October 2025: "Spec-driven development means writing a 'spec' before writing code with AI ('documentation first'). The spec becomes the source of truth for the human and the AI."
The tools agree on the shape. GitHub's Spec Kit README tells you to "Define what and why before deciding how to build it." Kiro splits a spec into three files: requirements.md, design.md and tasks.md.
Thoughtworks put spec-driven development on its Technology Radar in November 2025, in the Assess ring, and noted that "the term's definition is still evolving." That was one appearance at Assess, not a standing endorsement.
Note the word "why" in the Spec Kit line. The reasons are the part of a spec worth keeping.
Does spec-driven development still pay off with frontier models?#
Yes, in a shorter form whose job is to close decision gaps. The long, up-front document stopped paying; the short record of choices kept paying.
The clearest statement came from an Ask HN thread in September 2026. "We still write one, but it got a lot shorter as the models improved. The big up-front PRD stopped paying off. Frontier models are great at filling gaps, and that's the problem, they decide on your behalf. The plan mostly exists to close those decision gaps." (dishantsethi, Hacker News, 2026-09-27)
A strong model doesn't stall on a missing detail. It picks something plausible and keeps going, and you find out in the diff.
Another reply in the same thread named what the shorter spec should carry: "These days it's more about saying why than what." (muzani, Hacker News, 2026-09-28)
In the same comment, dishantsethi added: "It also helps review: teammates can push back on a 30-line plan in five minutes, but a 2k-line diff takes an afternoon." A short spec moves the argument to the cheapest point to have it.
In the 2025 Stack Overflow Developer Survey, "The biggest single frustration, cited by 66% of developers, is dealing with 'AI solutions that are almost right, but not quite.'" Almost right is what you get when the model filled a gap with a reasonable guess that wasn't your decision.
Writing the spec by hand isn't the point, either. One reply drew the line between writing and checking: "I'd sacrifice the writing step without sacrificing the reading & validating step." (bbor, Hacker News, 2026-09-24)
When is a spec not worth writing?#
When the work is small, exploratory or easy to review, the critics are right. A full spec on that work is ceremony, and it can make the result worse.
Böckeler asked Kiro to fix a small bug and reported that "the workflow was like using a sledgehammer to crack a nut. The requirements document turned this small bug into 4 'user stories' with a total of 16 acceptance criteria."
A practitioner on Hacker News described a heavier cost. "Going through the superpowers spec-plan-implement-review cycle took one of my test runs (local AI) from 40 minutes to 8 hours, and produced a lower-quality result." (vdqtp3, Hacker News, 2026-09-28) That is one person's run, not a measurement.
Staleness is the second fair objection, because code changes faster than the document. One commenter put it this way. "As much as no one wants to read the code anymore, it seems like most people seem to agree it's the only source of truth." (mikgp, Hacker News, 2026-08-05) Alfredo Perez was sharper on dev.to: "a spec that nothing reads isn't documentation, it's exhaust." (2026-09-11)
The waterfall charge is the one we'd push back on. Will Raymer, also on dev.to: "So 'do you write a spec?' is simply a different question from 'are you doing waterfall?' The two are independent." (2026-09-11)
Our rule, stated as a position:
- Building to learn? Skip the spec and keep the prototype. You'll throw that code away, so a spec would describe nothing you keep.
- Building to sell or maintain? Write the short spec. Someone will ask why it works this way, and the code won't say.
- Small enough to review in minutes? Skip it. Reading the diff costs less than writing the plan.
What should a short spec still carry?#
Decisions, constraints, rejected options, who agreed and what is still open. That makes it closer to an architecture decision record than to a requirements document.
You can read behaviour back out of the code, but the code won't tell you the reason behind it. Say the spec reads "use a flag for the migration" but not "because the billing team can't take downtime this quarter". The next model or teammate may remove the flag when it looks redundant.
The NaPiRE study (Méndez Fernández et al., Empirical Software Engineering, 2016) drew on "the NaPiRE data from the 2014/15 survey run." It named incomplete or hidden requirements, communication flaws with the customer and moving targets as "the most cited ones and also the ones mostly related to project failure." Incomplete or hidden requirements came up in 48% of the 228 organisations it studied, and communication flaws in 41%.
That study predates coding agents, but a faster model doesn't fix a requirement nobody wrote down. One HN commenter noticed the same effect from the other side: "Agents are getting very good also on inventing features." (2dera, Hacker News, 2026-08-06)
So the short spec has a narrow job: name the choices the model must not make alone, with the reason for each. Everything else can come from the code.
Why start the spec from the conversation?#
Because someone usually said the why out loud before anyone typed it. Your team argued the tradeoff on a call. Someone killed an option in a design review.
Rebuild it from memory a day later and you remember what you decided, but not why the other option lost.
Practitioners already work this way. From the same Ask HN thread: "I use the agent to build the spec, usually from unfiltered audio to text data dump." (docenttx, Hacker News, 2026-09-24) A 2026 preprint on spec mining (Agarwal, Singhal, Breaux and Vasilescu, arXiv, 2026-08-25) studies spec-driven development artifacts on GitHub. It describes them as "written by a developer, or (more often) drafted by an AI tool and then curated by the developer."
A transcript carries tangents, dropped ideas and things people said with confidence that turned out wrong. An agent drafting from it can treat a passing remark as a requirement unless a person confirms which decisions stand. That risk is the reason for bbor's reading step.
For how to mark decisions during a call in the first place, see how to track meeting decisions and action items.
How does the why get from the meeting to your coding agent?#
When the session ends, Send to AI agent hands it to Claude Code, Codex or another destination you set up once. Desktop app only. During a Live Session, Auto-apply Tags land on points as people talk. Decisions and to-dos are the default tags, and your team can write its own. You can limit a send to Only items tagged Decisions.
Chief writes a context folder for the agent: a README to start from, the transcript, and notes. In the notes, each decision is marked and each to-do names its owner when someone was named. The README tells the agent to treat what people said as information about the work, not as instructions.
For Claude Code or Codex, Chief opens the agent in your own terminal, in the project folder you chose, and tells it to read the session's README first. From there the agent runs under your own permission settings. Chief itself never commits, pushes or opens a pull request.
A point tagged Decisions states what the group concluded. Some supporting detail can sit under it, and the full reasoning stays in the transcript. A send limited to Decisions leaves the transcript out, so send the whole session when the agent needs the reasoning.
On the web app, a finished session's Send to AI agent button asks What do you want made? PRD and Tickets are two of the choices. The PRD instructions tell the agent that every requirement must trace to something someone said, and that anything vague becomes an open question.
What it doesn't do:
- The terminal handoff is desktop only, on macOS and Windows.
- Nothing writes the spec for you. You pick PRD, and Chief writes the instructions for it.
- Search across sessions matches titles and summaries, not every word said.
- If a decision was never said out loud, no tag holds it.
- If your team already writes each decision and its reason into an ADR or ticket, the transcript adds little.
The walkthrough is in Hand a finished meeting to Claude Code or Codex.
Frequently asked questions#
Is spec-driven development just waterfall again?
No, not when the spec is short and you rewrite it as you learn. Will Raymer asked whether writing a spec means doing waterfall, and answered on dev.to: "The two are independent." A long up-front spec on small work does behave like waterfall, and that is the case to avoid.
How long should a spec be for an AI coding agent?
Short enough that a teammate can push back on it in minutes. One practitioner's benchmark: a 30-line plan takes five minutes to challenge, while a 2k-line diff takes an afternoon. Keep the decisions and their reasons, and let the code hold the behaviour.
Can an AI agent write the spec?
Yes, it can draft it. A person still has to read and approve it, because a draft from a transcript can turn a passing remark into a requirement. A 2026 preprint on spec mining describes the same split: AI drafts, the developer curates.
Can I give Claude Code the decisions from a meeting?
Yes. With Chief on the desktop, Send to AI agent hands the finished session to Claude Code or Codex, and the features page has the overview. You can limit the send to Only items tagged Decisions. A send limited that way leaves the transcript out, so send the whole session when the agent needs the reasoning.
Can the agent change my code without asking?
It depends on the path. Opened in your terminal, the agent runs under your own permission settings. When you ask a coding agent from inside Chief instead, it can read but not edit. It edits only after your explicit yes, in a separate copy Chief creates. Chief itself never commits, pushes or opens a pull request.
Sources#
- Birgitta Böckeler, Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl, martinfowler.com, 2025-10-15.
- GitHub, Spec Kit README, read 2026-10-03.
- Kiro, Specs documentation, updated 2026-08-27.
- Thoughtworks, Technology Radar: Spec-driven development, November 2025.
- Stack Overflow, 2025 Developer Survey: AI, 2025.
- Méndez Fernández et al., Naming the pain in requirements engineering, Empirical Software Engineering, 2016.
- Agarwal, Singhal, Breaux and Vasilescu, SpecMine, arXiv preprint, 2026-08-25.
- Ask HN: Does spec-driven development still pay off with frontier coding models?, Hacker News, 2026-09-24.
- dishantsethi, comment, Hacker News, 2026-09-27.
- muzani, comment, Hacker News, 2026-09-28.
- bbor, comment, Hacker News, 2026-09-24.
- docenttx, comment, Hacker News, 2026-09-24.
- vdqtp3, comment on Plan mode is dead, Hacker News, 2026-09-28.
- mikgp, comment on Ask HN: What Happened to Spec-Driven Development?, Hacker News, 2026-08-05.
- 2dera, comment on the same thread, Hacker News, 2026-08-06.
- Alfredo Perez, I Wrote 238 Specs and Never Read One Again, dev.to, 2026-09-11.
- Will Raymer, Be Agile, Write Specs, dev.to, 2026-09-11.
