Spec-driven development means you write down what to build, and how you will know it works, before a coding agent writes any code. The spec is a short Markdown file with requirements, acceptance criteria, a design sketch and a task list. The agent builds from it, and you review the result against it instead of against your memory of a chat.
It beats plain prompting for any feature that takes more than one sitting. It turns into slow, paperwork-heavy waterfall if you let the spec grow bigger than the change.
- A spec answers four questions: what to build, how to tell it works, how it fits the code, and in what order to build it.
- Acceptance criteria are the heart of it. Write each one so a test can check it.
- GitHub Spec Kit, Kiro and OpenSpec made the workflow popular, but one Markdown file is enough to start.
- Use a spec for features that span files or sessions. Skip it for one-line fixes.
- Keep specs short and alive: one change per spec, updated in the same commit as the code.
What is spec-driven development?
Writing requirements first is an old idea. What changed is the reader. A human developer fills gaps in a vague request with judgment and a quick question. An agent fills them with confident guesses. A spec closes those gaps before they turn into code you have to unpick.
Birgitta Böckeler of Thoughtworks describes three levels of commitment:
Spec-first. You write a spec for one change, build from it, and move on.
Spec-anchored. The spec stays in the repository and changes along with the feature.
Spec-as-source. People edit only the spec, and the code is generated from it.
Start with spec-first. Move to spec-anchored for features you will keep changing. Spec-as-source is the most ambitious level and the least proven.
The tools that made specs popular
Three tools did most to spread the idea. As of September 2026:
A command-line kit that installs spec skills into your coding agent. You set project rules once in a “constitution”, then run specify, plan, tasks, implement and converge for each feature. Version 1.0.10 shipped on September 22, 2026, and the repository has about 138,000 GitHub stars.
Specs are built into the editor. Each feature spec produces requirements.md, design.md and tasks.md, and requirements follow a structured format called EARS. Kiro works out which tasks depend on each other and runs the independent ones at the same time.
A lighter workflow built for existing codebases. Each change gets its own folder with a proposal, spec updates, a design and tasks. You propose, apply, then archive, and archiving merges the change into the project’s living specs.
You can try Spec Kit in two commands. It needs Python 3.11 or newer and uv, a Python package manager. The second command adds the spec skills to a new project for Claude Code:
uv tool install specify-cli
specify init my-project --integration claudeNone of these is required. A Markdown file in your repository and a clear prompt get you most of the benefit.
What goes in a good spec
Four parts do the real work. Everything else is optional.
| Part | The question it answers | Example line |
|---|---|---|
| Requirements | What should exist, and for whom? | As a shop owner, I want to export last month’s orders as CSV so that I can do my accounts. |
| Acceptance criteria | How will we know it works? | WHEN the month has no orders THE SYSTEM SHALL download a CSV with only the header row. |
| Design | How does it fit the code? | Add GET /orders/export?month=YYYY-MM. Reuse the existing order query. No new dependencies. |
| Tasks | In what order, and how big? | T2: add the endpoint with a test for the empty month. Done when npm test passes. |
Spend most of your time on acceptance criteria. Each one should describe something a person or a test can observe. Kiro writes them in EARS form (“WHEN [condition] THE SYSTEM SHALL [behavior]”), and Spec Kit’s template uses Given, When, Then scenarios. Either works, as long as every line can fail.
Two more sections pay for themselves. Out of scope curbs the agent’s urge to help beyond what you asked. Open questions give it a place to park doubts instead of guessing. Spec Kit’s template does the same with a “NEEDS CLARIFICATION” marker.
A spec template you can copy
Save this in a specs/ folder, fill in the brackets and delete what you do not need. It is short on purpose.
# Spec: [feature name]
Status: draft
Owner: [name]
Last updated: [date]
## Goal
[One or two sentences: the problem this solves, and for whom.]
## Requirements
- As a [kind of user], I want [capability] so that [benefit].
- As a [kind of user], I want [capability] so that [benefit].
## Acceptance criteria
Each line must be checkable by a test or a person.
- AC1: WHEN [event or condition] THE SYSTEM SHALL [observable result].
- AC2: WHEN [error case] THE SYSTEM SHALL [what the user sees].
- AC3: [a limit that must hold, such as a response time or file size]
## Out of scope
- [What this change must not do, touch or add.]
## Design
- Data: [new or changed tables, fields and types]
- Interfaces: [endpoints, functions or screens, with inputs and outputs]
- Constraints: [libraries to use or avoid, security, performance]
- Decisions: [each choice made, with a one-line reason]
## Open questions
- [ ] [Question] (who answers it, and by when)
## Tasks
Small and ordered, one reviewable diff each.
- [ ] T1: [task]. Covers AC1. Done when: [test or command passes].
- [ ] T2: [task]. Covers AC2. Done when: [test or command passes].
## Verification
- Run: [test, lint and type-check commands]
- By hand: [the path a user would click through]Rules that apply to the whole project, such as your test command and code style, belong in one standing file rather than in every spec. Our AGENTS.md guide covers what to put there.
How to build from a spec with an agent
Let the agent interview you
Describe the feature in a paragraph. Ask the agent to draft the spec and to list every question it would otherwise guess at. Answer them, then have it revise the draft.
Review the spec like code
Read the acceptance criteria line by line. Cut anything you do not need now. A requirement you delete today is code you never have to review.
Turn the criteria into tests first
Ask for failing tests that map to the acceptance criteria, at least one per line. Review them before any code exists. Our guide to test-driven development with AI shows how to stop an agent from editing them.
Build one task at a time
Ask for one task only, with its tests run and the output shown. If the spec turns out wrong, the agent should stop and say so, not improvise. Review and commit before the next task.
Close the loop against the spec
When the tasks are done, ask the agent to go through each acceptance criterion and show the evidence that it passes. If reality changed the plan, update the spec in the same commit.
I want to build: [one paragraph describing the feature]. Before writing any code, draft a spec in Markdown with these sections: Goal, Requirements, Acceptance criteria, Out of scope, Design, Open questions, Tasks. Write every acceptance criterion so that a test could check it. Ask me up to eight questions about anything you would otherwise have to guess, then wait for my answers. Do not write code until I say the spec is approved.
For more prompts that plan before they code, see our prompts for coding agents.
When does a spec beat plain prompting?
A spec costs time up front. It pays off when the work is big enough that the agent would drift, or risky enough that you want a record of what was agreed.
| Plain prompt | Spec first | |
|---|---|---|
| Best for | One-file fixes, small tweaks, exploring an idea | Features across several files or sessions, risky changes, team work |
| Time before code | Seconds | Minutes to an hour |
| What you review against | Your memory of what you asked | Written acceptance criteria |
| When the agent drifts | You notice late, or not at all | A criterion fails or a task does not match |
| After it ships | The reasoning lives in a chat log | The spec stays next to the code |
A simple rule: if you cannot say what “done” means in one sentence, write a spec. If the change fits in one commit you could describe in a line, just prompt.
How to avoid the waterfall trap
Waterfall means writing every requirement up front, then building for months against a document nobody updates. Specs can slide into it quietly.
Böckeler’s review of Kiro, Spec Kit and Tessl names the symptoms. She found the generated Markdown tiring to review and the fixed workflow too heavy for small changes. Agents also still skipped some instructions. In Spec Kit 1.0.10, the bundled spec, plan and tasks templates alone come to about 2,500 words.
- One spec per change, not one per product
- Short enough to review in ten minutes
- Tasks small enough to check in one diff
- Updated in the same commit as the code
- Open questions answered before tasks start
- Specs written for work months away
- Reviewing the documents takes longer than reviewing the code would
- Nobody updates the spec when the code changes
- Every tiny fix goes through the full ceremony
- The agent follows the plan after the plan proved wrong
Treat the spec as a working tool, not a contract. Write it for the next change, not the next quarter. When the build teaches you something, change the spec and keep going. OpenSpec’s README puts the goal in three words: “iterative not waterfall.”
FAQ
Is spec-driven development just waterfall again?
It can be, if specs grow large and stop changing. Done well, each spec covers one change, stays short and changes whenever the code teaches you something. That is closer to a well-written ticket than to a months-long requirements phase.
Do I need a special tool for spec-driven development?
No. A Markdown file in your repository and an agent that reads it are enough to start. Spec Kit, Kiro and OpenSpec add templates, commands and task tracking, which help once you use the workflow often.
How long should a spec be?
Long enough that the agent does not have to guess, and short enough that you will actually review it. For most features, a page of acceptance criteria and a short task list is plenty.
Where should specs live?
In the repository, next to the code, usually in a specs/ folder. That way they are versioned, reviewed in pull requests and visible to every agent and teammate.
Read next: how to refactor legacy code with AI without breaking it, or how to migrate a codebase with an agent.
- Spec Kit, GitHub, September 2026
- Integrations, Spec Kit documentation, accessed September 2026
- Kiro, Kiro, accessed September 2026
- Specs, Kiro documentation, August 2026
- Feature specs, Kiro documentation, accessed September 2026
- OpenSpec, Fission AI on GitHub, September 2026
- Understanding spec-driven development: Kiro, spec-kit, and Tessl, Birgitta Böckeler on martinfowler.com, October 2025
