Spec-driven development

What is spec-driven development?

Spec-driven development is building software by writing a specification first and letting coding agents derive the plan, the task list and the code from it. The spec states what you want, the constraints it has to respect and the criteria that prove it is done. It lives in the repository, under version control, next to the code it describes.

The point is where the intent lives. When you build with an agent through chat, the reasons behind every decision sit in a conversation that nobody reads back and that is gone the moment the context is cleared. With a spec, the intent is in a file. A new session starts from the file, a colleague reviews the file, and a second agent checks the code against the file.

GitHub put it this way when it released its Spec Kit toolkit in September 2025: the spec is a living contract for how the code should behave, and it becomes the shared source of truth that guides implementation, testing and validation. Amazon's Kiro, released two months earlier, was built around the same idea, and lighter alternatives such as OpenSpec followed. Agreeing what to build before building it is an old idea. What changed is that a written spec is now something a machine can act on directly.

Think of the plan you sign with a builder before the crew arrives. It says how many rooms, which walls carry weight and what the inspection at the end has to confirm. It does not say which brand of screws to use. That is the level a spec works at.

The four phases

Most tools split the work into the same four phases, whatever they call them.

1. Specify. You describe what you want and why. The agent turns that into a spec: user stories, the rules that apply and acceptance criteria you can test. In Spec Kit this is spec.md; in Kiro it is requirements.md. GitHub's rule for this file: what users need and why, with no tech stack, no API design and no code structure.

2. Plan. Now you add the technical constraints: the stack you already run, the systems it has to talk to, the security rules. The agent writes an implementation plan (plan.md in Spec Kit, design.md in Kiro). A developer reviews this file; an owner does not need to read it.

3. Tasks. The plan is cut into small, checkable pieces in tasks.md, each small enough that the diff it produces can be reviewed in one sitting.

4. Implement. The agent works through the tasks, runs the checks the spec asked for, and hands back reviewable changes instead of one large dump of code.

Spec Kit adds optional steps, such as a constitution with rules that apply to every feature and a clarify step that hunts for gaps before planning. OpenSpec organises the same work per change rather than per feature, which fits an existing codebase better. All of them keep the files in the repository; Kiro stores them under .kiro/specs/ and can regenerate the task list when the requirements change. That is what makes the spec survive: a chat history is gone after the session, a file in git has a diff and a reviewer.

What a good spec contains, and what it leaves out

Anthropic's guidance for Claude Code describes the most useful specs as self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works. It adds that time spent making the spec precise pays off more than time spent watching the implementation.

A spec you can hand to an agent has four parts.

Intent. One or two sentences on the business outcome. Fewer return e-mails to the sales desk.

Constraints. The rules that must hold whatever the implementation does. Only invoiced orders. Nothing leaves the EU region.

Acceptance criteria. Statements that are either true or false once the feature exists. Kiro writes these in EARS notation, a format Rolls-Royce engineers first published in 2009 for jet engine control software: "WHEN a customer submits a valid return request THE SYSTEM SHALL create a return with a reference number." Every criterion has a trigger and an observable response, so it turns into a test without interpretation.

Out of scope. What the agent must not touch. This is the part people forget, and the part that stops the agent from helpfully rebuilding your invoicing module on the way.

What the spec leaves out is the how. Stack, libraries, database tables, class names: those belong in the plan, where they can change without changing what was agreed. Screen layouts and button positions usually belong in neither file. A mock-up attached to the plan does that job better, and prose about the UI is the fastest way to write a spec nobody can verify.

A worked example

A wholesaler wants customers to request returns through the customer portal instead of by e-mail. The owner and the supplier sit down with the spec before anyone opens the code.

Intent: return requests arrive in the ERP with the right lines attached, so the sales desk stops retyping them. Constraints: only lines from invoiced orders delivered less than 30 days ago; refunds and credit notes stay in the ERP exactly as today. Three acceptance criteria: WHEN a customer selects lines from an eligible order THE SYSTEM SHALL create a return request in the ERP with status "new" and e-mail the reference to the customer. IF the delivery is older than 30 days, THEN THE SYSTEM SHALL refuse the request and show the sales desk phone number. WHEN a return is created THE SYSTEM SHALL leave the invoice and the stock levels unchanged. Verification: create a test order delivered ten days ago, request a return for two lines, confirm the return exists in the ERP with those two lines and that the mail was sent.

The owner reads that page in five minutes and can say whether it is right. What she cannot judge, the choice of API or how the portal authenticates against the ERP, sits in the plan the developer reviews. The agent then generates the tasks, implements them and runs the verification. When the review finds a gap, the fix starts in the spec, not in the chat.

Spec-driven development versus vibe coding, requirements documents and BDD

Versus vibe coding

The two use the same agents. The difference is where the intent lives. In vibe coding it lives in the chat and in the head of the person typing; the code is accepted unread and judged on whether it runs. In spec-driven development it lives in a versioned file that a non-technical owner can approve and that the verification loop takes its criteria from. GitHub's blog post names the failure the practice was written against: describe what you want in a paragraph and the agent returns code that looks right but does not compile, misses the intent or clashes with the existing architecture. A spec fixes the second and the third.

Versus requirements documents, user stories and BDD

A requirements document from before the agents was written for people, read once, and left behind as the code moved on. Spec Kit's own design notes say it plainly: code was the source of truth, and specs rarely kept pace. A spec written for an agent has to be precise enough for a machine to act on, and it gets a diff every time the feature changes, which is the only reason it stays true.

User stories and the Given/When/Then of behaviour-driven development carry over almost unchanged; Thoughtworks' write-up of the practice says the BDD habits still apply. What is new is the reader. A BDD scenario was read by a developer who then wrote the test and the code. A spec is read by an agent that writes both, so the gaps a developer would fill from experience now have to be on the page.

How far you take it

Birgitta Böckeler of Thoughtworks separates three levels, and the word "spec-driven" gets used for all three.

Spec-first. You write the spec before the code for one task, use it to drive the agent, and stop maintaining it once the feature ships. This is what most teams do, and what Anthropic's workflow describes: let the agent interview you, write SPEC.md, start a fresh session.

Spec-anchored. The spec stays alive alongside the code and is updated when the feature changes. Kiro's sync between requirements and tasks is built for this.

Spec-as-source. The spec is the artefact you maintain and the code is generated from it; people stop editing the code by hand. Spec Kit's design notes lean this way, with code as "the last-mile approach". Thoughtworks' own position is more careful: the spec drives generation, the way a test drives code in TDD, but the code that runs remains what you maintain, because generation is not deterministic and drift between spec and code is, in their words, inherently difficult to avoid.

For most SMEs the value sits at spec-first for anything larger than a bug fix, and spec-anchored for the two or three features the business depends on.

What to watch out for with spec-driven development

Spec theatre. Böckeler's verdict after trying the tools was that she would rather review code than all those markdown files. When a two-line bug fix produces a spec, a plan and a task list, the process has become the product. Anthropic's rule of thumb for plan mode applies here too: if you could describe the diff in one sentence, skip it.

Specs that drift from the code. The moment someone fixes something in the code and not in the spec, the file is lying, and an agent that reads it later acts on the lie. Treat the spec like a test: it changes in the same pull request as the behaviour it describes, or it is deleted.

Over-specifying the UI. A spec that dictates every label and column width cannot be verified and ages fast. Specify the behaviour and the data; let the plan carry the mock-up.

The agent still ignores it. Böckeler also saw agents skip instructions in the spec or follow them too eagerly, duplicating code that already existed. The spec sets the criteria; the verification loop and a human review still have to check they were met.

Who writes it. The tools assume someone can turn a business wish into testable criteria. In a small company that is the owner and the supplier together, in one meeting, before any agent runs. Budget that meeting. It is the cheapest hour in the project.