Spec-driven development is a way of building software with AI in which a written specification of the intended behavior comes first and stays the source of truth. AI agents generate plans, tasks and code from the spec, and people change the system by changing the spec instead of editing the generated code directly.
- The spec says what the software must do and why; code becomes an output that can be regenerated.
- Practitioners distinguish three levels: spec-first, spec-anchored and spec-as-source.
- Review moves from line-by-line code diffs to changes in intended behavior.
- Regeneration isn't deterministic, so tests that bind code to the spec carry the trust.
- Specs build up their own debt: contradictions, bolted-on exceptions and files nobody reads.
- For small projects, a one-page brief often beats a heavyweight process.
What is spec-driven development?
Spec-driven development (SDD) treats the specification as the primary artifact a team owns. The spec describes behavior: who the users are, what they need to do, what must always be true and how success is checked. Code is generated from it as a downstream product. GitHub put the shift in one line when it launched its open source Spec Kit in September 2025: "We're moving from 'code is the source of truth' to 'intent is the source of truth.'"
Spec Kit's workflow shows what this looks like in practice. In the specify phase you describe what you are building and why, and the agent drafts a detailed spec focused on user journeys and success criteria. In the plan phase you add the stack, architecture and constraints. The agent then breaks the work into small tasks that can each be implemented and tested on their own, and implements them while you review focused changes instead of large code dumps.
The idea has ancestors. Behavior-driven development has long used structured examples as specifications; the Cucumber documentation says of its Gherkin format that, taken together, "your examples are an executable specification of the system." Model-driven development tried to generate code from models decades ago. What is new is that a language model can turn prose and examples into working code, which makes the spec far cheaper to act on.
Spec-first, spec-anchored and spec-as-source
Not every team using the label means the same thing. Birgitta Böckeler of Thoughtworks, reviewing SDD tools on martinfowler.com in October 2025, separated three levels of commitment:
| Level | What happens to the spec | Who edits the code | Best suited to |
|---|---|---|---|
| Spec-first | Written before the task and used to guide it, then often set aside | Agent and developers | Individual features and changes |
| Spec-anchored | Kept after the task and updated as the feature evolves | Agent and developers | Long-lived features that many people touch |
| Spec-as-source | The main file people maintain; code is regenerated from it | Only the generator | Systems where behavior can be fully described |
In her review, every approach she found was spec-first, while fewer aimed for spec-anchored or spec-as-source. That gap is worth noticing. Writing a good spec before a task is a well-understood discipline. Keeping a spec true for the life of a system, so that it can regenerate the code at any time, is a much stronger claim, and the rest of this article is about what it takes.
Why the spec, not the code, becomes the source of truth
For decades the code was the artifact that survived. Design documents, tickets and comments decayed around it, and the running program was the only honest record of what a system did. Spec-driven development reverses that. When intent is written precisely enough for a machine to build from, the spec stops being documentation and becomes the asset. The implementation at any moment is one valid projection of it.
A concrete clause shows the difference. "Users can book appointments" is a wish. "A slot can be booked by one customer only; a second request for the same slot is refused with a message suggesting the next free slot; cancellations made more than 24 hours ahead free the slot immediately" is a spec. A generator can build from it, a test can check it, and a reviewer can argue with it.
This reorganizes ownership. The thing a person defends in review is the statement of behavior, not the lines that satisfy it. Teams that absorb this stop polishing generated functions by hand, because any polish that isn't reflected in the spec is one regeneration away from being erased.
What changes when review moves from code to intent
When the spec is the source of truth, reviewers read changes to the spec (new behavior, tightened constraints, removed assumptions) and spot-check the generated code instead of reading every line. That is a different skill. A one-sentence change to a clause can ripple through hundreds of generated lines, and reviewers have to reason about that blast radius without reading all of it.
Defects get traced differently too. The question becomes "which clause produced this?" and then "was the clause wrong, or did the generator misread a correct clause?". The second case is a fidelity failure, a category of bug with no equivalent in hand-written code. Our essay on the gap between what you describe and what is produced looks at it in detail.
Review can also get heavier rather than lighter. Böckeler found that one tool produced many repetitive, verbose markdown files and wrote: "I'd rather review code than all these markdown files." A spec only helps review if it is shorter and clearer than the code it replaces.
Can you trust regeneration?
A spec can only be the source of truth if regenerating from it is predictable. If the same spec produces materially different implementations each time, the generator is the real source of truth. Böckeler saw exactly this: generating code repeatedly from the same spec produced different results, and the spec had to become more and more specific. Variation between runs is a property of today's models, as our piece on reproducibility in production explains.
The practical answer is to bind the output to the spec with tests derived from it: every acceptance criterion becomes a check that any regenerated version must pass. Teams then choose how much to regenerate at once.
| Property | Eager regeneration | Lazy regeneration |
|---|---|---|
| What is rebuilt | The whole implementation on each meaningful change | Only the parts a change touches |
| Drift risk | Low; output always tracks the spec | Higher; untouched regions can go stale |
| Cost per change | More compute, less reasoning | Less compute, more reasoning |
| Typical failure | Surprises across the whole system | Local inconsistencies |
Small systems can afford eager regeneration and its guarantee. Large systems usually drift toward lazy strategies, which reintroduces some of the divergence the approach was meant to remove.
Where specifications build up their own debt
Specification debt is the gap that opens when the written intent no longer matches what the system needs. Clauses contradict each other, edge cases are bolted on as exceptions, and the spec grows until nobody holds its whole shape. It is harder to see than tangled code, because a spec can read cleanly while encoding contradictory intent, and a generator never objects the way a compiler rejects a type error.
- Specification drift
- The slow divergence between stated intent and what the system actually needs.
- Projection fidelity
- How faithfully generated code realizes the spec, without adding or dropping behavior.
- Semantic diffusion
- A term losing its meaning through loose use, as when any detailed prompt gets called a spec.
Agents can also ignore a spec. Böckeler describes an agent that disregarded notes about existing classes and regenerated them as duplicates. Paying down spec debt looks like refactoring: merge overlapping clauses, delete dead constraints, split specs along clear boundaries, and keep each one small enough for one person to read. Left alone, it produces the same comprehension gap our essay on intent debt describes, one level up.
A spec-first change, step by step
Whatever the tool, a disciplined change follows the same direction: it enters through intent and flows outward to code, never the reverse.
- State the change as an amendment to the spec, not as a code edit.
- Express the new behavior as acceptance criteria and examples that both the generator and the tests can read.
- Regenerate the affected part and let the tests confirm that it matches.
- Review the change in behavior against the stated intent, not the line diff.
- When the result surprises you, fix the spec, not the output.
- Prune the spec periodically so it stays small enough to read.
Step five is where discipline is tested. Patching a surprising output by hand is tempting, but every patch that doesn't return to the spec reopens the gap the approach was meant to close. The patched line works today and disappears at the next regeneration.
When does spec-driven development pay off?
Fit matters as much as discipline. Böckeler watched one tool turn a small bug fix into four user stories with sixteen acceptance criteria, and found another workflow overkill for a mid-sized feature. She also questioned whether heavy up-front specs sit well with the small, iterative steps most teams prefer. Those are fair warnings, and they point to a simple sorting rule.
- Good fit: features whose behavior can be stated clearly, work shared by several people or agents, systems expected to live for years, and rules that carry money, access or legal weight.
- Poor fit: one-line fixes, throwaway experiments, visual polish that is easier to judge than to describe, and early exploration where nobody yet knows what the product should do.
- Middle ground: a one-page brief that names the users, the main journeys and the rules that must always hold, kept current and used as the starting point for every change.
The middle ground is where most small teams and solo builders should start. It captures the main benefit, a durable statement of intent that outlives any single chat or code change, without the review burden of a full toolkit. If the brief keeps growing and several people depend on it, that is the signal to adopt a more formal process.
Spec-driven building without the tooling, with WisyLink
You don't need a developer toolkit to work this way. WisyLink builds a hosted web app from a chat. There is no code editor and no code export, so the only way to change an app is to describe the change and let a new build run. In Böckeler's terms that is close to spec-as-source by design. Your description is what you maintain; the code is the platform's output. A failed build never replaces the live version, so a change that doesn't work leaves the last good app in place.
That makes a written brief the most valuable thing you own. Keep a one-page spec outside the chat: who the app is for, the main journeys, the rules that must always hold and what is out of scope. Use it for your first message (our AI website builder prompt templates give a structure), update it whenever you ask for a change, and test the live app against it. Our guide to building an MVP with AI shows how small that first spec can be.
If you want to drive builds from code instead, the API reference shows how to create a link from a message and continue it later. When your brief is ready, start free and turn it into a working app.
F.A.Q.