The most common objection to Spec-Driven Development (SDD), building software from a written specification, is that it is paperwork: writing a document before every change slows the team down. A recent study looked at how teams that already use it actually practise it, and the answer is more useful than a yes or a no.
The idea this insight defends: you do not defend SDD by saying it works for everything, but by choosing where to use it. New or risky features, yes; a trivial change, no. The spec says what and why, not how. And it is checked against the code on every change, not at the end. A spec that nobody checks is documentation that decays.
The first study of how SDD is practised
Shyam Agarwal, Anmol Singhal, Andrew Macvean, Bogdan Vasilescu and Travis Breaux (Carnegie Mellon University and Google) compared what SDD tools prescribe with what the people who use them actually do. The latest version of the paper is dated 15 October 2026. They combine three sources: an analysis of Reddit discussions, interviews with 21 practitioners (8 of them tool makers) and SpecMine, a corpus of 470,795 spec files from 73,030 public GitHub repositories, from which they analyse in depth a sample of 266 active, popular repositories (36,890 files). Three figures from that sample:
Risk It is a preprint without peer review. The repositories are public and popular, and one tool dominates the sample (OpenSpec, 78.4%): they may not look like your company's. The figures are shares of files, not of teams. Interviewees are probably more engaged with SDD than average, the study finds associations rather than causes, and participants themselves could not separate what they gained from SDD from what the models improved.
What teams that already use it do
Four findings from the study, told separately because each one changes a different decision:
- They use it selectively. Mostly for new and larger features. For bugs, hotfixes and small tasks, interviewees did not write a spec.
- The agent is more reliable, but it costs more. Participants reported more reliable agent behaviour and clearer intent, in exchange for more planning and more review. One team said that SDD runs used two to three times as many tokens and took about twice as long as prompting the agent directly: that is one reported case, not a statistic.
- The spec ends up carrying the how. Everyone agrees it should say what to build, but most tool users also write how to build it, especially for complex tasks or when the agent lacks the knowledge. Tool makers, by contrast, keep the how in separate design or task documents.
- The check comes at the end. Participants checked that spec and code agreed mainly when a change was completed, not over time. Those who wanted to catch later drift built their own checks.
The authors give a name to what happens next: spec decay, where the spec goes stale as the code changes, mostly when a change alters behaviour that other specs describe. It is the same loss we discuss in comprehension debt: what nobody maintains stops explaining the code.
Where a spec pays off and where it is overkill
If the cost is real (more planning and more review), the question is not whether to use SDD, but for which changes. The table is our proposal based on what the teams in the study do, not a finding of the study.
| Type of change | Spec? | Why |
|---|---|---|
| New feature | Yes | You need to settle what gets built before the agent decides on its own |
| Risky change (payments, permissions, personal data) | Yes | The acceptance criteria are what the machine later checks and a person signs off |
| Change that passes through several people or roles | Yes | The spec is what everyone understands the same way; the study sees the shared benefit there |
| Contained bug | No, a test | A test that reproduces the failure already says what should happen |
| Hotfix | Afterwards, if behaviour changes | Fix it first; if it alters what another spec describes, update that spec |
| Text, styling or trivial change | No | Writing it costs more than it clarifies |
onext analysis based on Agarwal et al. (2026)
The underlying criterion is the same as in an issue is not a spec: you need a spec when, if you do not write it, the agent fills the gaps with whatever it assumes. And it does not replace what tests already do well: how SDD, TDD and BDD split the work is in what each adds when an agent writes the code.
What goes in the spec and what does not
Our reading of the finding about the how: implementation detail helps the agent today and decays tomorrow. The spec that lasts says what to build, for whom, why and with which acceptance criteria. The how (which library, which structure, which steps) goes elsewhere, in a design document or in the tasks, as the tool makers in the study do. That way, when the how changes, the spec is still true.
There is one reasonable exception, which the study itself records: what the agent cannot know. Decisions the team has already made that are not in the code should be written down, as we explain in architecture decisions, but in their own place, not repeated in every spec.
Check it on every change, not at the end
If the spec is only compared with the code once the change is finished, drift shows up in the next one. The way to avoid it is not to reread it more often, but to make it check itself: turn the acceptance criteria into tests that run on every integration, as we explain in your spec is already an eval. The study points the same way: scheduled agent reviews or end-to-end tests in continuous integration can show that code and spec no longer agree.
DORA puts it more generally in its AI Capabilities Model (September 2025): working in small batches, a long-standing principle, is especially powerful when working with AI. A small change with its spec and its check is easy to review; a large one, checked at the end, is not.
A spec that nobody checks is documentation that decays. If no test fails when the code drifts away from it, it is not guiding development.
The honest answer to "SDD is bureaucracy"
It is if you apply it to everything and nobody maintains what is written. The cost is real: the study finds it in planning and review effort, and one team also reported it in tokens and time. What changes the maths is where you spend it.
The study sums it up on two levels: the individual benefit may come from clarifying intent before delegating to the agent, and the team benefit depends on SDD becoming a shared process. A conceptual framework published in August 2026 (Díaz, Gayoso, Cimminio and Pérez) frames it the same way from theory: specs are the contract between people and agents, and it separates the technical machinery around the agent from the team's practices. It is an analysis based on the literature, not an empirical study, but it agrees on what matters: a template does not make the process. That is what we cover in SDD templates are free now.
What we take away for a team that is starting: decide in writing which types of change get a spec, what goes in it and which automated check comes with it. With those three decisions, SDD stops being one more document and becomes the way the team works.
If you want to see, with someone from outside, where it pays off in your team, the diagnostic is free, and if the diagnostic shows no difference, there is no Quick-start. The rest of the path is at AI-Accelerated Development. The full method is in Spec-Driven Development with AI. If you would rather see it live, this is how our SDD workshop at TRGCON 2026 went.
Frequently asked questions
Do you need to write a spec for every change with Spec-Driven Development?
No, and the teams that practise it do not do that either. In the Carnegie Mellon and Google study of how SDD is practised, interviewees used it selectively, mostly for new features, and skipped it for bugs, hotfixes and small tasks. In the analysed sample, an estimated 82.0% of specs describe new features.
When does it pay off to write a spec before handing work to a coding agent?
Our proposal: when the change is a new feature, when it touches something risky (payments, permissions, personal data) or when it passes through several people or roles who need to understand the same thing. A contained bug is usually covered by a test that reproduces it, and a text or styling change does not need a spec.
What should a spec contain and what should it leave out?
What to build and why, with acceptance criteria that can be checked. The how (design, tasks, implementation detail) is better kept in a separate document. In the study, 77.6% of spec files contain implementation detail, and the authors note that this may help the agent but makes the spec more likely to decay.
Why does a spec decay?
Because the code changes and the spec does not. The authors call it spec decay: the spec goes stale as the code changes. It happens mostly when a change alters behaviour that other specs describe. In the sample, 81.5% of spec files have a single recorded commit.
When should you check that the spec and the code still agree?
On every change, not at the end. Study participants checked spec against code mainly when a change was completed, not over time, and those who wanted to catch later drift had to build their own checks. If acceptance criteria become tests that run on every integration, the check happens by itself.
Is SDD bureaucracy?
It is if you apply it to everything and nobody maintains what is written. The study finds that agent behaviour is more reliable in exchange for more planning and review effort. That cost pays off where the change justifies it and stops paying off when you specify a trivial change or when nobody looks at the spec again.
Sources
- Shyam Agarwal, Anmol Singhal, Andrew Macvean, Bogdan Vasilescu and Travis Breaux (Carnegie Mellon University and Google), "Spec-Driven Development as Prescribed and as Practiced", arXiv:2608.25202, version 4 of 15 October 2026 (preprint).
- Jessica Díaz, Joaquín Gayoso, Andrea Cimminio and Jorge Pérez, "Spec-Driven Development for Agentic Software Engineering: Harnessing Human-Agent Teamwork", arXiv:2609.00252, 31 August 2026 (preprint).
- Kevin M. Storer and Derek DeBellis, "Introducing DORA's inaugural AI Capabilities Model", Google Cloud Blog, 23 September 2025.
- The table of where a spec pays off, the split between what and how, and the reading of the findings are onext's own analysis.
Bernat López is founder and CEO of onext, an AI boutique. He helps development and product teams work with AI with method —specification before building, a person who decides where there is risk and Spec-Driven Development— and applies to his own company what he proposes: onext runs on its own agentic system.
LinkedIn →