What does spec-driven development mean?#
In spec-driven development, a specification written before implementation becomes the reference people and agents work from. Birgitta Böckeler of Thoughtworks describes it as writing a spec before writing code with AI, the spec becoming the source of truth for both. GitHub's Spec Kit team calls it a contract for how the code should behave.
A spec here is a structured, behaviour-oriented document in natural language, usually Markdown, stored in the repository next to the code. It says what the system should do and why, which constraints apply and how anyone will know the work is done. It differs from a prompt because it persists and is reviewed, and from a traditional requirements document because an agent acts on it directly.
Requirements engineering, BDD and model-driven development all tried to make intent explicit before implementation, and model-driven development struggled under its own overhead. What changed is the executor: when an agent turns a spec into working code in minutes, the spec decides what gets built, which makes it much harder to let go stale.
The three levels of spec-driven development
Böckeler distinguishes three levels, a taxonomy widely used in later writing on the subject. The difference between them is what happens to the spec after the first implementation.
| Level | What happens to the spec | Who edits the code | Where it fits |
|---|---|---|---|
| Spec-first | Written for a task, then set aside once the task is done | People and agents | Prototypes and one-off features |
| Spec-anchored | Kept and updated as the feature evolves | People and agents, with the spec updated alongside | Long-lived systems maintained by several teams |
| Spec-as-source | The only artefact people edit; code is regenerated from it | Agents only | Experimental: generation is still non-deterministic |
Most enterprise teams should aim for spec-anchored: spec-first loses the benefit once the task closes, because the next change starts from code again. Spec-as-source remains experimental — in Böckeler's trials, Tessl generated different code from the same spec across runs.
How does spec-driven development work?#
Tools name the steps differently, but most spec-driven workflows follow the same loop.
| Step | What happens | Who decides |
|---|---|---|
| Constitution | Architecture rules, security policies, testing standards and approved libraries, written once and inherited by every spec | Architects, security, platform team |
| Specify | Intent, users, scope, non-goals and acceptance criteria for one change | Product owner, reviewed by the team |
| Clarify | The agent looks for gaps and ambiguities and asks questions; answers are recorded in the spec | Whoever owns the missing decision |
| Plan | The technical approach: services touched, data changes, dependencies and risks | Tech lead or architect |
| Tasks | Small, independently reviewable units, often mirrored as issues | Engineers |
| Implement | The agent works through tasks, ideally in isolated environments | Agent, supervised by engineers |
| Validate | Acceptance criteria checked with protected tests and scenarios the agent did not write | Engineers and QA |
| Reconcile | When code and spec diverge, one of them is updated and the change is recorded | Spec owner |
Spec Kit, Kiro and OpenSpec each name the phases differently; the questions each phase answers are the same.
| Question | GitHub Spec Kit | Kiro | OpenSpec |
|---|---|---|---|
| Standing rules | /speckit.constitution | Steering files | Project context and existing specs |
| What to build | /speckit.specify, /speckit.clarify | requirements.md in EARS notation | Proposal and delta specs |
| How to build it | /speckit.plan | design.md | design.md |
| Work breakdown | /speckit.tasks | Implementation task list | tasks.md |
| Build and check | /speckit.implement, /speckit.analyze, /speckit.converge | Task-by-task execution | Apply, optionally verify, then archive |
Sources: Spec Kit repository, Kiro documentation, OpenSpec concepts, checked September 2026.
What should a good spec contain?#
A spec is useful to an agent when it removes decisions the agent would otherwise make alone. Mike Gehard described an experiment on our podcast: the spec said TypeScript, the repository still held shell scripts, and the agent's reasoning trace said it could not decide, so it would pick one. Seven elements close those gaps:
| Element | What it answers |
|---|---|
| Outcome and users | Who needs this, what problem it solves and what success looks like for them |
| Scope and non-goals | What is included, and what the agent must not touch or build |
| Constraints | Architecture boundaries, data ownership, security, compliance and performance limits that apply to this change |
| Decisions already made | Choices the agent should not revisit, with a pointer to the decision record |
| Acceptance criteria | Observable, testable conditions, often written in EARS ("WHEN … THE SYSTEM SHALL …") or Given/When/Then form |
| Verification | How each criterion will be checked, and which evidence the implementing agent may not modify |
| Open questions | What is still unknown, and who owns each answer |
## Intent
Finance admins need to export all invoices for a period in one step for the
monthly close. Today they download invoices one at a time.
## Scope
In: CSV export of invoices for one legal entity and one date range.
Out: PDF bundles, scheduled exports, changes to invoice data.
## Constraints
- The billing service owns invoice data; read from the reporting replica only.
- Exports stay in the EU region. Every export is written to the audit log.
- Maximum 10,000 invoices per export; larger requests are rejected.
## Acceptance criteria
- WHEN a finance admin requests an export for a valid range
THE SYSTEM SHALL deliver a CSV within 60 seconds for up to 10,000 invoices.
- WHEN a user without the finance-admin role requests an export
THE SYSTEM SHALL refuse the request and record the attempt.
- WHEN the range contains more than 10,000 invoices
THE SYSTEM SHALL reject the request with a message stating the limit.
## Decisions
Reuse the existing job queue (ADR-017). No new storage.
## Open questions
Currency formatting for multi-currency entities: owner, Finance PO.
Keep each spec short enough to review in one sitting: model performance drops when relevant information sits in the middle of a long input (Liu et al., 2023). Split specs by feature or epic, and move rules that apply everywhere into the constitution. At Odevo, one team's shared rules include an 80% test-coverage requirement for every pull request, which no individual story has to repeat.
Agents draft specs well and find gaps in them well, and are poor owners of intent. Tomasz Maj, head of product operations at Odevo, told our podcast that anyone who thinks writing a spec means asking Claude to write one is in for a surprise.
Spec-driven development vs vibe coding, TDD and BDD#
What separates these four is what each treats as the source of truth, and where each tends to fail.
| Approach | Source of truth | Good for | Where it tends to fail |
|---|---|---|---|
| Vibe coding | The conversation | Prototypes, spikes, exploring an idea quickly | Context is lost between sessions, decisions are inconsistent, and nobody can review the intent |
| Test-driven development (TDD) | Tests, written before the implementation they drive | Correctness of units, fast feedback, safe refactoring | "Unit" is loosely defined; and when one agent writes both the tests and the code, the pair can encode the same misunderstanding |
| Behaviour-driven development (BDD) | Shared scenarios | Aligning business and engineering on behaviour | Turns into another documentation layer when one role writes scenarios alone |
| Spec-driven development | Versioned spec plus constitution | Multi-file agent work, cross-team features, regulated change | Over-specification, heavy review load and drift between spec and code |
The three operate at different levels, which is why they combine rather than compete. TDD drives units, and what counts as a unit is left to the team. Acceptance criteria sit above that and map onto BDD scenarios in Gherkin's Given/When/Then form, the format SDD borrows for a spec's acceptance criteria. Kiro's own team describes running a red-green-refactor cycle inside each spec task. The condition is independence: acceptance tests come from the spec, and whoever writes the implementation cannot rewrite them, which a separate testing agent achieves as well as a person. BDD's lesson carries over, that scenarios fail when one role writes them alone.
Is spec-driven development just waterfall?
The objection comes up in almost every conversation we have about SDD. Waterfall's problem was fixing the requirements for a whole system up front and learning late whether they were right; spec-driven development done well specifies one slice at a time and learns from each before writing the next spec. As we put it in our training, how much you specify is your choice.
Dominic, a lead engineer at Odevo, put it on our podcast: the outline "looks a lot like waterfall, but it's absolutely not". What keeps it iterative is small batches: plan one epic at a time, as our own CFO agent build taught us, and treat anything further out as rough notes.
The approach has a real limit: specs help most when a team knows what it wants and least when the domain is unclear, and as one practitioner essay argues, you often learn what you are building by trying to make a computer understand it. Spikes and prototypes remain the right tool for that discovery, and the spec comes afterwards.
Spec-driven development tools: Spec Kit, Kiro, OpenSpec, Tessl and BMAD#
Frameworks such as Spec Kit and OpenSpec are commands and templates that run inside the coding agent a team already uses; applications such as Kiro build the workflow into an IDE. As our training puts it, most are essentially very large prompts, so the spec format and the review discipline matter more than the choice of tool.
| Tool | Type | Workflow and artefacts | Strengths | Watch-outs |
|---|---|---|---|---|
| GitHub Spec Kit | Open-source toolkit (MIT), works with 30+ agents | Constitution, specify, clarify, plan, tasks, implement; analyse, checklist and converge commands check consistency | The most complete command set; a constitution for organisation-wide rules | Generates many Markdown files to review; by default, sequential spec numbers collide when several people add specs in parallel |
| Kiro (AWS) | Agentic IDE | requirements.md in EARS notation, design.md, task list; requirements-first or design-first; separate bugfix specs | Lightweight, well-structured requirements | The full flow can be heavy for small changes; tied to Kiro's own IDE and CLI, which some teams reject over vendor lock-in |
| OpenSpec | Open-source CLI | specs/ describes current behaviour; changes/ holds proposals, designs, tasks and delta specs; archiving merges deltas | Designed for existing codebases; parallel changes without conflict; clear history | Teams need to learn the split between current specs and proposed changes |
Two others are worth knowing: Tessl, a commercial spec-per-file platform with a registry of library specs, and the multi-agent BMAD Method, which can run heavy — in one trial its persona-based version spent three hours producing 312 spec files for a simple retro-board app.
Tool choice matters less than teams expect. At Odevo, engineers using Spec Kit and engineers using a simple agent loop take the same standardised stories as input, and as Dominic put it, that input is where the effort pays off.
Spec-driven development with Claude Code
Claude Code ships no spec workflow of its own. Plan mode covers a light version of the planning step, and
Spec Kit and OpenSpec install the full workflow as slash commands, as they do in Copilot, Cursor and Gemini
CLI. CLAUDE.md holds project rules much as a constitution does, and subagents can take a verification
role separate from the implementing agent. Our open-source Wave goes
further, running spec-driven work as deterministic pipelines where each step must satisfy a contract before
the next starts; it was built spec-first, with the model writing
roughly 95% of the implementation.
When is spec-driven development worth it, and when is it not?#
Writing and reviewing specs takes time, the tooling consumes tokens, and a workflow built for features turns small fixes into ceremonies: Böckeler's Kiro trial turned one small bug into four user stories with sixteen acceptance criteria. The benefits are uneven too: in the controlled data in the next section, the gains concentrated on hard, multi-constraint work.
The practical answer is to choose the amount of specification per change. Hidde de Smet's three-lane model is a good starting point, and we use a version of it:
| Lane | Use it for | Artefacts (each lane adds to the one below) |
|---|---|---|
| Full spec | Cross-team contracts, security- or compliance-sensitive changes, long-lived core services and large multi-file changes made by agents | Everything below, plus a constitution check, a reviewed spec, a plan, tasks and drift checks |
| Light spec | Medium-risk features that stay within one team and one service | Everything below, plus a one-page spec with acceptance criteria and a task checklist |
| No spec | Reversible fixes, small bugs, spikes and throwaway prototypes | The ordinary ones: a ticket, a pull request and tests |
Drift checks are the least mature item on that list; the governance section below covers what they can and cannot do today.
If time to first commit keeps rising while escaped defects stay flat, the team is over-paying for process. If defects keep tracing back to requirements nobody wrote down, it is under-specifying.
Does spec-driven development actually work?#
Most published evidence is anecdotal, and most statistics quoted in vendor guides measure the risks of AI-generated code without measuring what specs do about them. The most useful controlled data so far is a small pilot published by Nitin Garg on InfoQ in September 2026. It cuts both ways, which is why it is worth reading closely:
- Specs did not help reviewers find more defects. Five experienced reviewers checked two banking services for deviations from their requirements. With the spec as a baseline, they found about as many as without it (recall of 0.525 against 0.518). How much a spec helps here depends on how it is written, and the pilot tested one spec style on two services.
- Specs made the defects they found accountable. With the spec, reviewers traced 81% of their findings to a specific requirement; without it, none. Review took longer: 48 minutes against 27.
- Specs helped weaker models most. On a banking task with twenty invariants, a staged spec-then-generate approach raised a weaker model's pass rate from 23.8% to 45%. A strong model gained about two points.
- On easy tasks, reasoning did most of the work. For simple single-function tasks, asking the model to reason first scored 95% and writing a spec first scored 92%, against 59% for generating code directly.
The author presents this as a pilot signal needing confirmation, and the sample is small. Prezi's engineering team ran a workshop with four teams using Spec Kit: one colleague built a working app in four hours, another completed a UI library migration in minutes, but participants hit token limits and doubted the process would hold beyond prototypes.
The most striking practitioner figure we know of comes from Odevo. Introducing his conversation with Dominic on our podcast, host Daniel Jones put the change at 72 times faster. The claim underneath that number is about eight years' work delivered in 11 months with a third of the people, while engineers still read the code — which works out at roughly 26 times the output per engineer, not 72. Either way it is the team's own before-and-after estimate rather than a controlled measurement, from greenfield work built for agentic development with standardised, spec-style stories.
In our own work the first benefits are consistency and accountability. Agents follow the same constraints across sessions, work restarts from files after a context window fills, and a defect that does trace cleanly to either a missing requirement or an implementation that ignored one tells a team whether to fix its specs or its validation. Plenty of defects refuse to sort into either box, and the ones that do are the dividend rather than the rule. Speed gains at organisational level are unproven: Faros AI's 2025 study of more than 10,000 developers found review time up 91% in teams with high AI adoption, so faster generation can simply move the queue to review. Measure before and after, using the metrics below.
Who writes the spec? Roles and ownership#
Most SDD tools assume one developer does all the requirements analysis, and at enterprise scale that assumption breaks first. Krishnan warns that adopting spec-driven workflows without changing how product, architecture, engineering and QA work together produces a "markdown monster": layers of documentation nobody keeps current. The spec needs owners the way code does.
| Role | Owns | Reviews or approves |
|---|---|---|
| Product owner | Intent: the problem, users, outcomes and acceptance criteria | The spec, at the review gate |
| Architect or tech lead | The constitution, technical plans and cross-service decisions | Plans, and any change that breaks a contract |
| Engineers | Tasks, implementation and reconciling specs when code reveals something new | Agent output, task by task |
| QA or quality engineering | The validation harness and scenarios kept out of the implementing agent's reach | Acceptance evidence |
| Security and compliance | Policies encoded once in the constitution | Changes that touch sensitive areas |
| Coding agent | Drafting, clarifying questions and implementation | Responsible for its output; a named person stays accountable |
The last row follows Garg's model: the agent is responsible for generation, accountability stays with a person. Ownership also exposes a shift that surprises organisations: our AI Adoption Ladder whitepaper describes development becoming fast enough that product turns into the slowest stage, because specifications detailed enough for human-speed work do not carry enough information for agents. Writing specs is a skill, and product owners need training in it as much as engineers do.
Keeping specs and code in sync: drift, versioning and review#
Drift is the main long-term risk. A spec that no longer matches the code is worse than no spec, because agents and reviewers will trust it. Most of the controls are ordinary engineering discipline applied to a new artefact. Building our CFO agent with two engineers in parallel taught us several the hard way:
- Version specs with the code. Keep specs in the repository, change them through pull requests and protect the constitution with code owners, in the same way you protect CI configuration.
- Commit draft specs early. Spec Kit numbers specs sequentially. When two people created specs at the same time, the numbers collided and cross-references became ambiguous. Pushing drafts to the shared repository immediately fixed it.
- Freeze a spec once implementation starts. Editing a spec while implementing it created what we called the devil's loop: the spec changed, the plan no longer matched, the implementation surfaced something else. The way out was to open a new spec for the change and keep the original as a record.
- Reconcile at a fixed point. Reconciling at the end of each epic beats catching up continuously.
- Detect drift automatically, within limits. In Wave, a drift check gives two options, block the change or update the documentation to match reality, and a person approves either one. The agent never silently rewrites a governance document.
That check is narrower than it sounds, and this is the least mature part of the workflow. We know of no tool that reliably finds semantic divergence between a spec and the code claiming to implement it. What works today is structural: flagging specs whose referenced files, endpoints or schemas have gone, or specs untouched while the code around them moved. Both miss the case where the code still runs and no longer does what the spec says. Scheduled reconciliation by people is the control that holds; the automated checks are a prompt for it, not a substitute.
Regulated teams need those controls to leave evidence. Garg's model defines five control points, each producing a record an auditor can follow:
| Control point | Record it produces |
|---|---|
| Spec authoring | Draft baseline |
| Spec review gate | Approved baseline, with approver and timestamp |
| Guided generation | Generation record: which spec version and which model produced the code |
| Drift detection | Drift log: divergences and the clauses they violate |
| Reconciliation | Reconciliation record: what changed, who changed it and why |
Specs and constitutions are instructions agents follow, which makes them an attack surface for prompt injection, examined in The Spec Is the Attack Surface. And an agent that grades its own work tends to pass it: one fintech team told us their agents reported building features they had not built. The implementer never judges its own work, so acceptance evidence comes from protected tests, independent scenarios or a separate reviewer agent.
How do you apply spec-driven development to an existing codebase?#
Most enterprise work changes systems that already exist, and most SDD tools were designed for new projects. Three approaches work in practice:
- Specify around the area of change. Krishnan recommends covering the existing behaviour near each change, the same way teams add characterisation tests before refactoring legacy code, and letting specs grow with every fix and feature.
- Record changes as deltas. OpenSpec keeps a description of current behaviour separate from proposed changes, which it records as added, modified and removed requirements. Its documentation describes the approach as brownfield-first, and it avoids rewriting a whole specification for every change.
- Reverse-engineer specs with agents, then review them. Dominic described, second-hand, Odevo having agents analyse around fifteen codebases into spec documents, roughly two weeks of heavy token use, before people reviewed the output. Feed the agent more than the source: one team we work with added documentation, tickets, user stories and meeting notes, and got better specs than from code alone.
Some systems cannot be fully specified. An engineering leader at a European healthcare software group told us that for products with decades of history the full specification will never be recovered, so the practical scope is new behaviour only. The same leader raised the opposite problem: every greenfield project becomes a brownfield project, so plan for spec-anchored maintenance from the first commit.
How do you roll out spec-driven development across an organisation?#
Spec-driven development spreads team by team; mandating one tool across an organisation produces the ceremony without the discipline. A staged path, combining Garg's adoption sequence with how we run enablement programmes:
| # | Stage | What it involves |
|---|---|---|
| 1 | Pick the corner | One high-stakes, multi-constraint service owned by the team with the best backlog discipline |
| 2 | Train the people | Engineers and product owners practise writing, reviewing and validating specs on real backlog work, in weekly sessions over several weeks |
| 3 | Stand up the gates | A shared constitution, a spec review gate before generation and independent acceptance evidence |
| 4 | Make drift visible | Versioned baselines, automated drift checks and a routine for reconciliation |
| 5 | Centralise and automate | Shared specs and context across teams, model tiering by step and agent pre-screening of drift |
Training carries more weight than tooling. SDD was one module of the programme that moved around 100 Odevo developers to agentic coding in about six weeks, and we teach it by starting with where agents fail.
The healthcare group above reported specifications running to three or four times the volume of the code, and token spend peaking at €10,000 per team per week; our CTO Michael Müller's view was that the ratio is normal for spec-driven work. Operating at scale means centralising shared specs so teams do not re-specify the same foundations, tiering models by step, and checking that the value produced each week matches the spend. Current practice puts the strongest model on the spec and the plan, a mid-tier model on routine implementation, and escalates back for multi-file or security-sensitive changes. Saving money on planning is the expensive mistake, because a weak plan produces work no downstream agent can correct. The pilot above points the same way: a staged spec lifted a weak model from 23.8% to 45%, a strong one by about two points.
Measure the effect with a small set of numbers taken before the pilot starts:
| Metric | What it tells you |
|---|---|
| Lead time from approved spec to production | Whether the workflow speeds up delivery, including review and rework |
| Defects by origin: intent-to-spec or spec-to-implementation | Whether to invest in better specs or in better validation |
| Drift findings per change, and time to reconcile | Whether specs stay trustworthy |
| Review time for specs and for code | Whether the review bottleneck has moved or grown |
| Token and model cost per accepted change | Whether the economics hold as usage grows |
From spec-driven development to software factories#
On the AI Adoption Ladder, re:cinq's model of nine stages of AI coding adoption, spec-driven development usually takes hold in the Discipline phase: the move from individuals prompting agents to structured, repeatable work with context kept as code. In our experience most organisations sit around stage 2, before that shift has happened.
In the Factory phase the relationship reverses. The whitepaper describes stage 7 as the point where humans specify, agents implement and validation carries the weight code review used to, which makes the quality of specifications decide whether the factory works. Some teams keep acceptance scenarios outside the repository where the implementing agent never sees them, as StrongDM's software factory does. Our Software Factories at Enterprise Scale whitepaper covers that operating model in depth.