What is spec-driven development and when does it help?

What is spec-driven development?

When you give a coding agent a task, you usually explain what you want in the chat. If what you want lives only in the chat, it is gone when the session closes. Spec-driven development (SDD) writes that intent into a file before the code. A spec, short for specification, is the document that says what the agent will do and why. The agent writes the spec first, then a technical plan that says how, then a task list. It writes the code last, working from these documents.

In the September 2025 post that announced Spec Kit, GitHub sums up the idea in one sentence: “We’re moving from “code is the source of truth” to “intent is the source of truth.”” In other words, what is correct is decided by the written intent, not by the code. The same post also says what is left to the developer: “Crucially, your role isn’t just to steer. It’s to verify.” This post is about that second sentence.

What happens to the spec once the work is done depends on the approach. The three levels in the October 2025 article in which Birgitta Böckeler of Thoughtworks tried three SDD tools now also appear in Spec Kit’s own documentation:

• Spec-first. The spec is written before the code; it can be thrown away when the work is done.
• Spec-anchored. The spec is kept after the work is done and used for later changes.
• Spec-as-source. People edit only the spec; the code is generated from it and never changed by hand.

According to Böckeler, every approach she found is spec-first, and how the spec is to be kept up over time is often left vague. As we will see below, it is this vagueness that makes code review hardest.

Our main source on how the method is used in practice is Spec-Driven Development as Prescribed and as Practiced, a study by researchers at Carnegie Mellon University and Google. Its latest version on arXiv is dated 15 October 2026. The study draws on Reddit discussions, interviews with 21 practitioners (8 of whom build tools) and 266 repositories on GitHub. The two percentages above also come from this study.

We covered coding agents’ rules files in our post on AGENTS.md and CLAUDE.md, and how to review a pull request written by AI in a separate post. This post puts the spec between the two.

What steps take you from the spec to the code?

The tools give the steps different names, but the order is the same: first what is to be built, then how, then the tasks, and the code last. At the end of each step you read the document and correct it; the agent moves on to the next step with that version.

In Spec Kit, you run /speckit.constitution once per project, then, for each feature, specify, plan, tasks, implement and converge, in that order. The constitution holds the project’s principles, and every later step is evaluated against them; it is similar to a coding agent’s rules file. clarify, checklist and analyze are optional quality checks, which you add for work where something is unclear.

In Kiro, every spec consists of three files: requirements.md, design.md and tasks.md. Requirements are written in a pattern called EARS: “WHEN [condition/event] THE SYSTEM SHALL [expected behavior]”. The order is requirements, design, tasks; if you already have an architecture in hand, you can also start with the design. Kiro’s rules files live in the .kiro/steering/ folder, and Kiro also reads the AGENTS.md at the root of the repository.

OpenSpec keeps each change in a folder of its own: under openspec/changes/<change>/ sit the rationale (proposal.md), the requirements (specs/), a design when one is needed (design.md) and the tasks (tasks.md). The loop is explore, propose, review, apply and archive. A change’s spec records only the difference: which requirement was added, changed, removed or renamed. On archiving, these differences are merged into the main specs under openspec/specs/; the main specs describe the system as it is today. Here is an example delta spec from OpenSpec’s README:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

This delta file is the part that helps most in review: in a pull request it shows at a glance where the intent changed. We will come back to it below.

How do Spec Kit, Kiro and OpenSpec differ?

We read the three tools’ documentation on 18 October 2026. The table shows which files each tool writes, what it checks when the work is done and what it suggests for small tasks:

Source: each tool’s own documentation, 18 October 2026. How the commands are written depends on the coding agent you use (for example /speckit.plan or /speckit-plan). According to Kiro’s documentation, property-based tests run only in the IDE. In Kiro, you can also have the requirements analysed for inconsistencies and gaps before the design.

The three run in different places. Spec Kit is an open source toolkit that is added to your coding agent as commands or skills. OpenSpec is also added to the tools you already use; its README says it supports 30+ tools. Kiro, on the other hand, is a coding agent with its own IDE, CLI and web interface. OpenSpec’s README says Kiro is “limited to Claude models”; Kiro’s models page, as of 18 October 2026, also lists GPT-5.6 and open-weight models. When a tool says something about a rival, it is worth checking against the rival’s own documentation.

In 2025 there was one more name on this list: Tessl. Böckeler had tried it alongside Kiro and Spec Kit. In September 2025, Tessl announced its first products as built on spec-driven development: a Spec Registry in open beta and the Tessl Framework in closed beta. Its documentation today describes Tessl as “an open platform for managing agentic development across your organization” and does not mention spec-driven development. The method now lives in Tessl’s registry as a public plugin. We could not find a current page that says where the Tessl Framework stands today.

Two more open source methods work with specs. In Superpowers, the agent first draws out what you want by asking questions; small changes are agreed in chat, and projects get a written design document. In implementation, which runs on subagents, each task is reviewed in two stages: first compliance with the spec, then code quality. BMAD Method says its process sizes itself to the work: small changes go straight to build.

Why do critics call it “the new waterfall”?

Waterfall is the approach that designs the work up front and runs its phases in a strict sequence: no design until the requirements are written and approved, no code until the design is finished. Critics say spec-driven development brings that sequence back with markdown files. Two articles say so in their titles: “The Waterfall Strikes Back” and “Reinvented Waterfall?”. What the criticisms have in common, though, is less the sequence than the review burden.

Thoughtworks, October 2025. Böckeler asked Kiro to fix a small bug. The requirements document turned this small bug into 4 user stories with a total of 16 acceptance criteria. When she tried Spec Kit on a larger feature, she also found the markdown files she had to read too many for the size of the work: “To be honest, I’d rather review code than all these markdown files.” Despite all these files, she writes, she also often saw the agent not follow all the instructions.

Scott Logic, November 2025. Colin Eberhardt deleted a feature from his hobby app, had Spec Kit build it again and noted the time each step took. He built the feature in two steps: first the screens that manage the circuits, then GPS. The first step produced 2,577 lines of markdown and 689 lines of code, and reading and reviewing them took 3.5 hours; in the second, 2,262 lines of markdown and about 300 lines of code took about 2 hours. When he built the same feature without a spec, the way he usually works, he spent 24 minutes in total: 15 minutes of code review and 9 minutes of testing. This is Eberhardt’s own measurement: one developer, one hobby app, Spec Kit as it was in November 2025; the converge step does not appear in that article.

The difference is not in the code: without a spec, the code for the two steps came to about 1,000 lines in total. The markdown took the time. Eberhardt writes that he was about 10 times faster without a spec, and concludes: “For now, the fastest path is still iterative prompting and review, not industrialised specification pipelines.” This is one developer’s experience on one app, not a general measurement.

Marmelab, November 2025. According to François Zaninotto, the technical spec already contains code. The developer reads that code before running it and, since there will still be bugs, reads the final code too: “As a result, review time doubles.” In the example he shows, the agent marked the “verify implementation” task as done without writing a single unit test.

Thoughtworks Technology Radar, November 2025. The Radar placed the method in the “Assess” ring and wrote that some tools produce “lengthy spec files that are hard to review”. Its note ends with this sentence: “We may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn’t scale.” The note is not in the current edition of the Radar.

All these criticisms are about the review burden: more markdown to read than code, the same thing read twice, an agent that doesn’t follow what was written. All of them were also written in autumn 2025, about the tools as they were then; Böckeler herself notes that the tools change very fast.

What do its defenders see differently?

Meg Kretz of Atomic Object says in her May 2026 article that the similarity is in the documents and the difference in behaviour: “The difference comes down to four behaviors, which are observable, not philosophical.” In her view, waterfall uses documents as a gate: written, approved, frozen, handed off. In spec-driven development, the document is a working tool, written and rewritten along with the code. The four behaviours she lists are:

• When does the spec change? The day new information arrives, often within the same hour.
• How do design and spec move forward? Neither waits for the other; they move forward together, each reshaping the other.
• When is the work done? The Must/Should/May requirements in the spec are the acceptance criteria; when they are met, the work is done.
• Who edits the spec? The developer who runs into an ambiguity fixes the spec there and then; the fix is committed with the code.

What Kretz calls the “operational test” is this post’s main point about review: spec and code are committed in the same pull request. “If specs lag code, the spec is documentation, not source of truth.”

Practitioners also report gains, but cautiously. Most participants in the Carnegie Mellon study say specs make the agent’s work more reliable, but they cannot separate that gain from the models improving over the same period. One team that used the method for months wrote that it could not prove it improved the code. According to the study, SDD does not remove the cost: it moves tokens, time and mental effort from implementation to planning.

The tools have changed since those articles, too. In June 2026 Spec Kit added an optional bug-fix extension, and also in June 2026 it documented how specs are kept once the work is done. Kiro’s documentation today has Quick Spec, with no approval step, and Plan mode, which writes no files. Kiro describes one of the cases in which it suggests Quick Spec like this: “You've been defaulting to Vibe mode because the standard Spec flow felt too heavy”.

When does it help, and when does it get in the way?

The Carnegie Mellon study’s finding is clear: most practitioners use SDD not for every task but according to the size of the task. They skip it for small tasks, bugs and one-off scripts. For an urgent production fix, one participant says, “there is no time for spec-driven development and the whole flow”. Some decide by risk instead: if a mistake would be costly and the intent is clear, they write a spec.

The trail in the repositories points the same way. The researchers had a language model label a sample of 1,000 specs; by their estimate, 82.0% of specs describe a new feature. The tools’ documentation draws the same line:

The middle step matters. Kiro suggests Plan mode for tasks of 15–60 minutes, where a formal spec would be too much. The plan stays in the chat and no spec file enters the repository; so there is no document to review the code against later, either. For a small task that is fine: you review that pull request the way you always have, from the diff and the description.

For bug fixes, Spec Kit suggests a separate path: diagnosis, fix and verification are kept apart, and an unverified fix does not count as a success. Kiro, for its part, finds a quick fix in chat enough for typos or well-understood one-line changes.

How do code and spec drift apart over time?

Most participants in the Carnegie Mellon study described code and spec drifting apart. The researchers separate two ways this happens and name them: implementation drift (the code departs from the spec) and spec decay (the spec goes stale). Their example is how long a session stays open:

In both cases the code says 60 minutes and the spec 30 minutes; a tool that compares code and spec sees the two cases as the same. What makes the difference is which one is wrong. The study says so plainly: scheduled agent reviews or end-to-end tests in CI can show that code and spec disagree, but not which one is wrong. That decision belongs to whoever owns the intent.

Implementation drift happens in the pull request where the code is written. The study’s advice to tool makers is to turn acceptance criteria into tests the agent must pass; Kiro generating property-based tests from its EARS requirements is one example. Spec decay happens later, in another pull request: a change that alters a behaviour does not touch the spec that describes it. The study sees this most in living specs, when a change also affects behaviour that other specs describe.

The tools’ built-in checks run at the end of the work. Spec Kit’s converge step compares the code with that feature’s spec, plan and tasks, and only adds missing tasks; after a “Converged” result, the documentation points you to review or to opening a pull request. OpenSpec’s verify step compares the code with the change’s documents before archiving and only reports. In Kiro, you can ask in chat with #spec whether the work meets its acceptance criteria, and have completed tasks marked with Sync Files.

All these checks are run by the coding agent that did the work; the documentation we read does not say whether the check should be done by another model or in a separate session. The study also writes that it could not establish whether any of these tools checks, once the work is done, that spec and code still agree. Spec Kit’s documentation names the risk: “The main risk is silent divergence.”

How do you review code against its spec?

We covered the general steps for reviewing a pull request written by AI in a separate post: does it do what the description says, what did it change that it shouldn’t have, do the tests really test anything. In a team that works with specs, a few questions specific to the spec are added:

Spec and code should be in the same pull request. Spec Kit says to review code and document changes together, and OpenSpec to commit the change folder with the code. If the spec comes in a separate pull request, or not at all, you cannot see whether the intent changed.

Read the spec’s diff first. OpenSpec says the most valuable thing to read when reviewing the plan is specs/, and asks one question: “Would you accept these requirements as done?” In a pull request you put that question to the diff: which acceptance criterion was added, which changed, which was deleted. The study also recommends that tools show changes to acceptance criteria as a diff. You read the code against the new spec the pull request brings, and the change to the spec against its old version on the target branch. Tests and tools can ask whether the code matches the spec; only the owner of the intent can say whether the change to the spec is right.

A person should write or approve the acceptance criteria. The study recommends this directly: “Practitioners should write or approve acceptance criteria even when agents produce the rest.” You don’t need to read the whole spec with the same care; according to the study, the problem statement, the key decisions and the acceptance criteria state the intent, and the rest is context for the agent. Participants who set the acceptance criteria or went over the agent’s tests did not mention verification as a problem; the researchers add that they cannot show this prevented defects.

Every criterion should have a test. A tick in the task list is not a test: in Zaninotto’s example, the agent closed the verification task without writing a test. Match every acceptance criterion with a test. A criterion with no test is a promise with nothing behind it in the code.

The agent that did the work should not do the check. According to the study, when one agent writes the spec, the code and the tests, one misunderstanding can pass into all three; this is why some participants say “an agent must not review its own implementation”. Spec Kit draws the same line for its own checklists: the implementation step must not approve them by itself. The study also states the price of leaving spec review entirely to an agent: “Delegating spec review to an agent removes the one point where a person decides what the system should do.”

Check whether another spec broke. Spec decay often starts here. According to the study, an agent changing a feature can add behaviour that does the task at hand and passes its tests but breaks a constraint in an older spec. If other specs describe the behaviour that changed, they should be updated in the same pull request too.

In the record of open source repositories, people hardly appear in these steps. In the study’s sample of 266 repositories, 98.3% of the 36,888 spec files with a recorded history have a single author, and bots wrote 68.5% of the 1,731 inline comments on specs. In the researchers’ words, a spec’s second reader, if there is one, is usually a bot. These numbers don’t show how closely people read specs, or whether review happens somewhere else; they only show that little human participation is on record.

What does a review tool see of the spec?

diffox is a code review tool made up of 17 specialist agents. It does not read spec folders (specs/, .kiro/specs/, openspec/); it brings two texts into the review. The first is the rules file at the root of the repository: it looks for AGENTS.md first and, if there is none, for CLAUDE.md. It reads the file not from the pull request’s own branch but from the branch it will merge into, as it stood where the branch split off; so a pull request that changes the rules file is reviewed under the old rules until it is merged.

diffox takes from the rules file only the sentences that state an obligation (such as “must”, “never”, “should”, “always”) and gives them to the agents in the review as the rules that decide what counts as a defect. One of the agents, House Rules Agent, looks among the changed lines for one that breaks one of these rules, and does not invent a rule that is not on the list. The second text is the pull request’s description: it too goes into the context the agents read.

For a team that works with specs, this means that the obligations you want checked in every pull request belong in the rules file. A sentence such as “Every database migration must include a rollback plan.”, from the constitution example Spec Kit gives for existing projects, is used as a rule in the review if it is in the rules file; Spec Kit’s constitution file under .specify/memory/, on the other hand, is not read by diffox. In the pull request description, also write which spec you implemented and which acceptance criteria changed; the person reviewing reads the same description.

Where should you start in your own project?

Rather than rolling the method out across the whole repository at once, start small:

1. Pick one large feature. A new feature where the intent is clear and a mistake is costly. Keep doing bug fixes and small tasks the way you are used to.
2. Write the acceptance criteria yourself, or approve them one by one. The agent can write the rest. A pattern such as EARS or WHEN/THEN makes it easier to turn a criterion into a test.
3. Decide up front how the spec will live. Spec Kit lists three models and makes none of them the default: flow-back, where every document can update the others; flow-forward, where each change opens a new folder; and living spec, where the spec is the single source. Write the model you choose into the constitution or into the team’s onboarding notes.
4. Send the spec and the code in the same pull request. Start the review with the spec’s diff.
5. Have another pair of eyes do the check. The converge or verify result from the agent that did the work is a start; a person should also look at the acceptance criteria and the spec’s diff.

After a while, look at two things: are the specs still changing along with the code, and where is review time going? Kretz’s test is simple: if the spec lags behind the code, it is no longer the source of truth, it is documentation.