Spec-Driven Development: The Practice the Category Converged On
Every serious AI coding tool shipped the same feature within about a year of each other — which almost never happens by accident.
In 2025 the interesting question was how good the models were getting. In 2026 the interesting question is what you hand them.
GitHub shipped Spec Kit. AWS shipped Kiro, an IDE built around the idea. BMAD-METHOD, OpenSpec and Tessl each took a run at it. Cursor got there through rules files. Martin Fowler has published a comparison of the implementations. When six independent teams converge on the same answer inside twelve months, they are not copying each other. They are all hitting the same wall.
The wall has a name now. So does the fix.
What Spec-Driven Development Actually Is
Write the requirements, the constraints and the success criteria before any code is generated. Treat that document as the source of truth. Let the agent build against it.
That’s it. It is not a new idea — it is requirements engineering, which the industry spent thirty years doing badly and then largely abandoned as too slow. What changed is not the concept. It is the economics.
Specifications used to be expensive to write and expensive to keep current, which meant most teams wrote the broad strokes and discovered everything else in code review. That was a rational trade when a developer took three weeks to build the feature anyway. It stopped being rational when generation got fast, because now the specification is the slow part — and the slow part is where all the judgment lives.
The Failure Mode It Was Invented Against
Prompt-first tools skip the specification entirely. You describe an outcome, the tool produces something that resembles it, and every decision the description didn’t cover gets made silently by the generator.
Which decisions? The ones that turn out to matter. Whether an email address is unique, and unique across what. What a cancelled account can still see. What happens when two people edit the same record. Whether that list needs pagination before it has ten thousand rows in it.
Nobody asked those questions, so nobody answered them — but the application has an answer to every one, chosen by inference from context that never included your business.
The same dynamic shows up in every tool that skips the definition step. It is the mechanism behind the 70% problem: progress stalls not because the remaining work is hard, but because it is blocked by an architectural decision made implicitly, hundreds of generations ago, that can no longer be changed without pulling the system apart.
The Data on What Happens Without It
DORA’s 2025 State of AI-assisted Software Development is the clearest read available. 90% of technology professionals now use AI at work and more than 80% believe it has increased their productivity. And higher AI adoption is associated with an increase in software delivery throughput and an increase in software delivery instability, at the same time.
Faster at shipping. Worse at keeping things working. Both, together.
GitClear’s 2026 analysis of 623 million code changes shows the shape of the damage. Against a 2023 baseline: duplicated code blocks up 81%, within-commit copy/paste climbing from 9.4% in 2022 to 15.7% in the first half of 2026, error-masking constructs up 47%. Meanwhile cross-file function calls — the best available proxy for code reuse — down 35%, and refactoring activity collapsed from 21% of changes in 2022 to 3.8% in 2026.
Developers are now roughly five times more likely to copy and paste than to refactor. In 2022 that ratio ran the other way.
None of that is a model quality problem. It is what happens when generation is cheap and structure is nobody’s explicit job.
The Three Degrees of Commitment
Not everyone means the same thing by this, and the differences matter in practice. Martin Fowler’s framing is the cleanest I’ve seen.
Spec-first. You write the specification, generate from it, then maintain the code by hand. The spec drives the initial build and then gradually becomes historical. Easiest to adopt, weakest guarantees — six months on, the document describes a system that no longer exists.
Spec-anchored. The specification and the code evolve together. Change the spec, regenerate the affected parts, keep both current. More discipline, and the payoff is that the document stays trustworthy.
Spec-as-source. The specification is the only artifact you edit. Code is output, the way a compiled binary is output — you don’t hand-patch it. Strongest guarantees, and the biggest leap in how a team works.
Most teams calling themselves spec-driven are doing spec-first. That is a real improvement over prompting blind, and it is also the version that quietly decays.
What Belongs in the Spec
The useful test: if the generator would have to guess, it belongs in the document.
- The data model. Entities, relationships, cardinality, what makes a record unique, what happens on delete. This is the highest-value section and the one most often skipped.
- User types and permissions. Who exists, what each can see and do, what happens at the boundaries.
- The invariants. Rules that must never be violated, stated flatly. Not “handle errors gracefully” — that is a wish, not a constraint.
- Success criteria. How you will know the thing works, in terms specific enough that a disagreement about whether it works is resolvable.
What does not belong: implementation detail the generator is better at choosing than you are. A specification that names variables is not a specification, it is code with worse tooling.
The Part Everyone Gets Wrong
A specification only helps if it is enforceable somewhere other than in prose.
If a constraint lives only in the document, it is a suggestion. The generator read it once and may or may not have honored it in the fourteenth file it touched. Constraints need to end up somewhere the system checks: not-null and unique in the database rather than in a form handler, types at boundaries rather than in a comment, authorization as a policy the system evaluates rather than a condition somebody remembered to write.
This is the difference between spec-driven development as a practice and spec-driven development as a genre of document. The document is how you decide. The enforcement is how you keep the decision.
How to Tell Whether You Are Actually Doing It
Four questions, and they are uncomfortable on purpose.
- When something breaks, do you fix the code or the spec? If the answer is always the code, you are spec-first at best and the document is already stale.
- Could a new person read the spec and predict how the system behaves? If they’d have to read the code to know, the spec is a summary rather than a source.
- Is there anything in the spec the system cannot violate? If every rule is prose, none of them are guaranteed.
- Do you review the specification or the diff? Reviewing thousands of lines of generated code is theater. Argue about the document while arguing is still cheap.
Where This Leaves the Tools
Most current implementations are spec-driven for code generation specifically. They produce a specification and generate an implementation against it, and the artifact they operate on is a codebase.
The harder version extends the same logic to the whole application — the data model, the API surface, the authentication boundary, the interface — so the spec covers not just what the code does but what the system is. That is what Archie’s blueprint phase is, and it is why I describe it as spec-driven development applied to the full stack rather than to a repository. Different scope, same principle: define before generating.
Reasonable people disagree about how far to take it. Nobody serious is arguing for going back.
What It Costs
Front-loading judgment is slower for the first week of a project and faster for every week after. That cost is real and it is paid at exactly the moment momentum feels most valuable, while a competitor ships something visible. There will be sprints where the team that skipped this looks like it is winning.
The discipline also decays. Writing constraints down is less enjoyable than watching an interface appear, and reviewing a document is less satisfying than reviewing code. These habits erode under deadline pressure, which is the same pressure that makes them matter.
And it genuinely does not apply to everything. If you are validating an idea this weekend and intend to throw the result away, throw it away. None of this is worth doing for software with a two-day lifespan.
The Reason This Stuck
Every previous attempt to make teams write specifications first failed, and it failed for a good reason: the specification was overhead on top of the real work. You wrote the document and then you still had to build the thing.
That is no longer the trade. Now the document is most of the work, and the build is the cheap part. Six independent teams noticed this within a year of each other because it was the obvious consequence of the model getting good.
The practice didn’t win an argument. The economics moved underneath it.
Related Reading
The original diagnosis: vibe coding broke its promise. Where the category went next: what comes after vibe coding. The same argument applied to whole systems: AI-first software design from first principles. And the older framing of the same idea: stop writing software twice.
Frequently Asked Questions
What is spec-driven development? Writing the requirements, constraints and success criteria before any code is generated, and treating that specification as the source of truth the AI agent builds against. It emerged in 2025 and 2026 as a direct response to prompt-first workflows that skip the definition step.
How is it different from traditional requirements documents? The concept is the same; the economics are not. Traditional specs were expensive enough that teams wrote the broad strokes and discovered the rest during implementation. When drafting one takes hours instead of months and can be revised cheaply, it becomes worth finishing and worth keeping current.
Which tools support spec-driven development? GitHub Spec Kit, AWS Kiro, BMAD-METHOD, OpenSpec and Tessl are the named implementations, and Cursor supports a lighter version through rules files. They differ mainly in how tightly the spec binds to the code — whether it drives generation once, evolves alongside it, or is the only artifact you edit.
What are the three degrees of spec-driven development? Spec-first, where the spec drives the initial build and you maintain the code by hand. Spec-anchored, where spec and code evolve together. Spec-as-source, where the specification is the only thing you edit and code is treated as output. Most teams practicing it are doing spec-first.
Does spec-driven development slow teams down? It relocates the work rather than adding it. The decisions in a specification get made either deliberately up front or implicitly by a generator guessing later, and the second path is where rework comes from. It is slower for the first week and faster after that.
What should go in a specification? Anything the generator would otherwise have to guess: the data model with relationships and uniqueness rules, user types and permissions, invariants that must never be violated, and success criteria specific enough to settle a disagreement. Leave out implementation detail the generator chooses better than you do.
Is spec-driven development the same as AI-first design? Spec-driven development is the practice of defining before generating. AI-first design is the broader set of architectural consequences, which also covers where constraints are enforced, the order in which you make decisions, and designing for agent consumers alongside human ones.
