Spec-driven development is the practice of agreeing on a written specification before an AI agent writes any code, and judging the result against that spec instead of against a one-line prompt. It sounds like a return to waterfall. In practice the spec is a page, it takes minutes to produce, and it moves the most expensive conversation in software, "that is not what I meant", to the moment it is cheapest.
Why agents need it more than people do
A developer who does not understand a ticket asks. An AI agent fills the gap with the most plausible reading and keeps going, quickly and confidently. The result looks finished, passes the tests it wrote for itself, and is wrong in a way you only find in review. The faster the agent, the more wrong code you review.
What goes in the spec
After a few thousand runs, these are the sections that earn their place:
- Functional interpretation: what the request means, in the words of the person who asked.
- Technical approach: how it will be built, and what will be reused rather than written again.
- Affected components: real file paths and their dependents, not "the backend".
- Data model and API impact: migrations and contract changes, because those are hard to undo.
- Risks: what could go wrong, security first.
- Test strategy: which tests prove it works.
- Open questions: everything the request leaves unclear, asked rather than guessed.
An example
The request: "Customers should be able to download their invoices as PDF." A spec drafted against the codebase turns that into a button per invoice for organization admins, an endpoint that reuses the template the invoice email already renders, an ownership check named as the main risk, two tests, and one open question: do credit notes get the button too? The person who asked answers that in a sentence. Without the spec, the answer would have arrived as a review comment on finished code.
Who approves, and when
Whoever owns the outcome: a tech lead for a structural change, the product owner for behaviour, the developer who asked for a small fix. What matters is that no run starts before an approval, and that the approval is tied to a specific version of the spec, so the pull request can point back to exactly what was agreed.
Mistakes to avoid
- Specs written without reading the code. "Affected components" that are guesses make the whole spec a guess.
- Approving without reading. A spec nobody reads is a slower prompt.
- Specs as long as the code. If a spec needs pages, the task needs splitting.
- Throwing the spec away after merge. It is the best record of why the change exists.
This is how CodeLynq works on every task: the spec is drafted against your repositories, open questions go to a validation chat, and the run is held to the approved version. More on the spec-driven development page, or see how it compares to agents that skip the spec in CodeLynq vs Devin.