What is spec-driven development?

Published 18 October 2026 · updated 23 October 2026

Spec-driven development (SDD) is a way of building software with AI coding agents in which the specification is written first and the agent builds from it — so the spec, not the chat, says what the software must do. In simple terms: agree in writing on what you are building before any code is generated, and keep that writing as the reference while the work goes on.

Spec-driven development means writing a “spec” before writing code with AI (“documentation first”). The spec becomes the source of truth for the human and the AI.

— Birgitta Böckeler, martinfowler.com, October 2025

What is spec-driven development?

GitHub’s Spec Kit puts it in one line: “Define what and why before deciding how to build it” (Spec Kit). The spec says what the software must do and why; the plan and the code say how.

A spec is not a long prompt. Böckeler’s definition: “a structured, behavior-oriented artifact - or a set of related artifacts - written in natural language that expresses software functionality and serves as guidance to AI coding agents.” Someone who vibe coded for months before switching put the test more bluntly: “A spec is not a prompt. It’s an actual definition of how to tell if something is behaving as intended or not” (Hacker News, November 2025).

A spec usually holds:

• Why the change is being made, and for whom.
• Requirements: what the software must do, one statement each.
• Acceptance criteria: how to tell that each requirement is met.
• What must not change, and what is out of scope.
• Boundaries for the agent: what it may and may not touch.

The spec template has all of these, with an example.

Why now. Coding agents write code faster than anyone can explain what they want in a chat. OpenSpec’s README names the problem: “AI coding assistants are powerful but unpredictable when requirements live only in chat history.” GitHub open-sourced Spec Kit in September 2025. Hacker News comments mentioning “spec-driven” went from 4 in 2024 to 398 in 2026 up to 17 October, and new GitHub repositories built around the idea from 10 a quarter to 2,504 (our count).

Not a new name. In 2004, Jonathan Ostroff, David Makalsky and Richard Paige described “an agile approach to Specification-Driven Development, which combines features of Test-Driven Development and the plan-based approach of Design-by-Contract” (XP 2004). Their specifications were tests and contracts. What changed in 2025 is who builds from the spec: an AI coding agent.

How spec-driven development works

The tools name the steps differently, but the loop is the same:

1. Specify. Describe the feature; the agent helps turn it into requirements and acceptance criteria. A person reviews the spec before anything else happens.
2. Plan. The technical approach — stack, architecture, data, interfaces — derived from the spec.
3. Tasks. The plan cut into small, ordered pieces, each one checkable.
4. Implement. The agent works through the tasks, with tests that check the acceptance criteria.
5. Verify and update. Check the result against the spec. When the work finds something the spec got wrong, the spec changes too.

Most tools add project-wide rules written once: Spec Kit’s “constitution”, Kiro’s steering files.

Three levels of spec-driven development

Not everyone keeps the spec after the code is written. Böckeler describes three levels:

Most teams start spec-first. The questions start at spec-anchored: who keeps the spec current, and who has to agree when it changes. Spec Kit leaves that open — it “does not prescribe how teams preserve or mutate spec.md, plan.md, and tasks.md after requirements change” (Spec Kit documentation).

A spec-driven development example

A small feature, from spec to tasks. The spec, as the client or product owner would review it:

SPEC: Export invoices to CSV (version 1)

Why: accountants re-type invoices into their own
tools every month.

R1  A user can export the invoices shown in the
    list, with the list's filters applied, as CSV.

Acceptance criteria
- Given 3 invoices match the filters, when the
  user exports, then the file has a header row
  and 3 invoice rows.
- Amounts use a dot as the decimal separator and
  no thousands separator.
- Given no invoice matches, the export button is
  disabled.

Must not change: the list's existing filters.
Out of scope: PDF export, scheduled exports.

The plan and tasks, derived from it for the agent:

PLAN
- Reuse the invoice list's query; stream
  the rows.
- New endpoint: GET /invoices/export.csv
- One function formats amounts;
  unit-tested.

TASKS
1. Amount formatter and its tests (R1,
   criterion 2)
2. Export endpoint using the list query
   (R1)
3. Export button, disabled when empty
   (criterion 3)
4. End-to-end test: 3 invoices, 3 rows
   (criterion 1)

Every task names the requirement it comes from, so when R1 changes, you can see which tasks and tests are affected. Without that link, the spec and the code start to part ways after the first build. A longer example, followed through a change request to the spec’s second version: spec-driven development example.

Spec-driven development tools

How they differ, what users say about each, and where Superpowers and GSD fit — more about how the agent works than about the spec: Spec Kit vs OpenSpec vs BMAD.

You do not need a tool to start. With Claude Code, Cursor or Copilot alone, a spec.md in the repository that the agent reads before it plans does the same job on a small scale — step by step for Claude Code in spec-driven development with Claude Code.

Spec-driven development vs vibe coding, TDD and BDD

Vibe coding is the opposite end: nothing lasting is written down, which is fine for a prototype you will throw away.

TDD and BDD combine with it. A spec holds what a test cannot — why, what is out of scope, who agreed — and its acceptance criteria become the tests. Some spec tools write criteria in a BDD shape: OpenSpec’s scenarios use WHEN and THEN. BDD’s own format is Gherkin.

Is spec-driven development just waterfall?

That is the most common criticism. Marmelab titled theirs “The Waterfall Strikes Back”:

Big Design Up Front has proven to fail most of the time because it piles up hypotheses.

— Marmelab, November 2025

A developer who tried Spec Kit on a CLI tool: “As would be the case with Waterfall today, the lack of iterative end-to-end feedback is foreign and frustrating to me” (Hacker News, November 2025).

In the same thread, others disagreed. One: “the problem with waterfall wasn’t the detailed spec” — it was the years between starting the spec and seeing the product, and “no (cheap) way to iterate or deliver outside the spec”. Neither, the commenter wrote, “are a problem with SDD” (Hacker News). Another:

My process is I spend 2-3 hours writing a “spec” focusing on acceptance criteria and then by the end of the day I have a working, tested next version of a feature that I push to production.

I don’t see how using a spec has made me less agile. My iteration takes 8 hours.

— Hacker News, November 2025

The difference is size. A waterfall spec covers a whole project, and months pass before anything is built; a spec in spec-driven development covers one feature or one change, and the code can follow the same day. It turns into waterfall when the spec tries to cover everything before anything is built.

Pros and cons of spec-driven development

What it gives you:

• The agent builds from written intent, not from a long chat it may lose track of.
• Mistakes are caught in the spec review, before code exists to throw away.
• Acceptance criteria turn straight into tests.
• The reasons outlive the session: the next developer, or the next agent, can read why.

What it costs:

• More to review. With spec-driven development, “review time doubles” (Marmelab). A commenter who reviews the code anyway: “having spec AND code is now double the text to read” (Hacker News).
• Writing specs is hard. “I find writing specs much harder than writing code, especially when trying to express the finer points of a project” (Hacker News).
• Specs drift. Once the work is merged, specs and code part ways — one of the three complaints we found most often about these tools. See what spec drift is.
• Existing code is harder. Most guides start from an empty folder. See spec-driven development on an existing codebase.
• The reviewer is the developer. In the popular tools, the person who approves the spec is the one running the agent. See who reviews the spec.

What the research says

Most studies of spec-driven development with AI agents date from 2026, and many are preprints, posted before peer review. So far:

• Practice differs from the tools. In a study of 470,795 spec files on GitHub, 98.3% of those with a recorded history had a single author, and 81.5% were committed once (Agarwal et al., preprint).
• Fewer defects is unproven. The one peer-reviewed test, on 88,052 pull requests, found those with a spec no less likely to introduce defects — and it could not include the tools’ own specs (Hill, ESEM 2026).
• Specs the agent can run help most. Tests and concrete cases in the prompt improve the code; longer prose does not.
• It costs more up front. At Google, an agent that wrote a spec before writing tests used 38% more tokens than one that wrote tests directly — and its tests caught more bugs.

The studies, their limits and the numbers to stop repeating: does spec-driven development work?

When spec-driven development is worth it

It earns its cost when:

• the work outlives the session that produced it;
• more than one person, or more than one agent, works on it;
• someone outside the development team has to agree with what is built;
• you can say, in advance, how to tell that it works.

For a one-off change by one developer, it may not: “Most coding agents already have a plan mode and a task list” (Marmelab).

How to start spec-driven development

1. Pick one feature, not the whole system.
2. Write the spec — or let the agent draft it and edit it yourself: why, requirements, acceptance criteria, what must not change, what is out of scope. Start from the spec template.
3. Have it reviewed before the plan, by the people who have to agree with it, not only by you.
4. Generate the plan and tasks; make each task name the requirement it comes from.
5. Implement task by task, with the acceptance criteria as tests.
6. When the work finds something, change the spec first, then the code.
7. Decide what happens to the spec after the merge: kept and maintained, or archived on purpose. Left alone, it drifts.

On an existing codebase, specify the change, not the system — the rule every tool’s guide now gives.

Where Specroot fits

This is the problem Specroot works on: specs that stay true after the first build, and a review by everyone who has to agree, not only by the developer running the agent. Specroot for teams using AI coding agents.