What is spec-driven development?

The name and most of the tooling arrived in 2025: AWS launched Kiro in July, GitHub released Spec Kit in September, and open-source frameworks such as OpenSpec and BMAD matured alongside them. All of them answer a problem most teams meet soon after adopting coding agents: prompts are ephemeral, context disappears between sessions, and an agent will confidently build something plausible that nobody asked for. Writing intent down in files that live in the repository gives every agent session, reviewer and future maintainer the same reference.

Mike Gehard, a guest on our Waves of Innovation podcast, described the constraint moving in two directions once generating code stops being the hard part: upstream to specification and downstream to validation. Spec-driven development addresses the upstream half. In our experience it pays off only when the downstream half gets the same attention.

Thoughtworks placed spec-driven development in the Assess ring of its November 2025 Technology Radar and suggested the industry may be relearning a bitter lesson about handcrafted rules for AI. This guide is for engineering leaders deciding whether and how to adopt SDD across teams, and it covers both sides.

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.

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.

Spec Kit, Kiro and OpenSpec each name the phases differently; the questions each phase answers are the same.

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:

## 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.

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.

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:

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 described the team as delivering code 72 times faster than before: about eight years' work in 11 months with a third of the people, while engineers still read the code. That 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.

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:

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:

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:

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.