Spec-driven development: how to build with a spec instead of a chat

What is spec-driven development?

Spec-driven development (often shortened to SDD) puts a written specification between your idea and the code. You describe the behavior you want in a file. An AI coding agent turns that file into a technical plan, the plan into a list of small tasks, and the tasks into code. You read and correct each step before the next one starts.

The contrast is with prompting your way forward in one long chat. In a chat, the requirements live in a scroll of messages, some of them contradicted three messages later. The agent has to guess which version you meant. In SDD the requirements live in one file that the agent reads again at every step, and that you can fix in one place.

It is also not a return to heavyweight documents. A useful spec for one feature fits on a page or two. The point is not paperwork. The point is that you decide what "done" means while the decision is cheap, instead of discovering it from what the agent happened to build.

If you are new to the idea of building by describing, start with what vibe coding is. SDD is what many people move to when a vibe-coded project gets too large to hold in one chat.

What is the spec, plan, tasks, implement loop?

Almost every SDD tool uses the same four stages. They differ in file names and commands, not in the idea. Each stage answers a different question, and each produces something a human can check.

Two rules keep the loop honest. First, the spec says what and why, never the tech stack. The stack belongs in the plan. Mixing them is the commonest mistake, and it makes the spec unreadable to the non-technical person who is supposed to approve it. Second, you review before moving on. An agent that runs all four stages without a pause is only a longer prompt.

What should a spec contain?

A good spec is short, specific and checkable. These are the parts that earn their place, in the order they are worth writing.

• Goal in one sentence. Who the user is, what they get, why it matters. If you cannot say it in one sentence, the feature is two features.
• User stories or scenarios. Two to five concrete situations. "A developer pastes a cron expression and reads what it means" beats "users can understand schedules".
• Acceptance criteria. The tests in plain words, with real example inputs and exact expected outputs.
• Out of scope. What the agent must not build. This line prevents more wasted work than any other, because agents add features.
• Constraints. Things that are decided before planning: must run offline, must work on a phone, no login, must not store personal data.
• Open questions. What you do not know yet. Leave them visible so the agent asks instead of guessing.

Leave out the tech stack, file names and database tables. If you already know you want, say, Next.js and Postgres, that goes in the plan step or in a project-level principles file. Leave out long background too. Every line in the spec is context the agent will read each time, so a spec padded with history makes the work worse. The same logic is behind context engineering.

What does a spec template look like?

Copy this into a file such as specs/cron-explainer/spec.md and fill it in. The worked example under it is a small developer tool, the kind that fits in one sitting. A tool with a similar job was posted on the board, where the title is "Explain this cron expression in plain English, and the reverse".

# Spec: <feature name>

## Goal
For <who>, <one thing the feature does>, so that <why it matters>.

## Scenarios
1. <Situation 1: who does what, and what they see>
2. <Situation 2>
3. <Situation 3: the unhappy path, e.g. invalid input>

## Acceptance criteria
- Given <input>, the result is <exact output>.
- Given <input>, the result is <exact output>.
- Given <bad input>, the user sees <exact message> and nothing is saved.

## Out of scope
- <Thing the agent must not build>
- <Another thing>

## Constraints
- <Decided in advance: platform, privacy, accounts, performance>

## Open questions
- <Anything not decided yet. The agent must ask, not guess.>

## Definition of done
- All acceptance criteria pass by hand and by automated test.
- Nothing outside this spec was added.

# Spec: Cron expression explainer

## Goal
For a developer reading a crontab, show what a five-field cron expression means in plain English, so they stop guessing before a deploy.

## Scenarios
1. A developer pastes `*/15 * * * *` and reads the meaning.
2. A developer types a sentence like "every weekday at 9am" and gets the expression.
3. A developer pastes `61 * * * *` and is told which field is invalid.

## Acceptance criteria
- `*/15 * * * *` shows "Every 15 minutes".
- `0 9 * * 1-5` shows "At 09:00, Monday through Friday".
- "every weekday at 9am" shows `0 9 * * 1-5`.
- `61 * * * *` shows "Minute must be between 0 and 59" and no result.
- The next five run times are listed, in the visitor's time zone.

## Out of scope
- Six-field or seven-field expressions, Quartz syntax, seconds.
- Accounts, saving expressions, sharing links.
- Any server: the page works offline.

## Constraints
- One page. No data leaves the browser.

## Open questions
- Which words does the English-to-cron direction need to understand beyond weekdays and times?

## Definition of done
- Every acceptance criterion above passes as an automated test.
- Nothing outside this spec was added.

Notice what the example does. The criteria carry real inputs and real outputs, the out-of-scope list rules out four things an agent would otherwise add, and the open question is left open on purpose. Handing this to an agent produces a plan you can compare against the file.

How do you turn the spec into a plan and tasks?

With a spec in a file, the next two stages are prompts. Run them one at a time and read each result before continuing. In a tool without SDD commands, these two prompts do the job.

Read specs/cron-explainer/spec.md. Do not write code yet.

Write specs/cron-explainer/plan.md with:
1. The approach in five sentences or fewer.
2. The files you would create or change, one line each.
3. Any library you propose adding, with the reason it is needed.
4. Risks and the parts of the spec that look ambiguous.

Stack: plain TypeScript and Vite, no backend. If the spec leaves something undecided, list it as a question instead of choosing.

Read spec.md and plan.md in specs/cron-explainer/.

Write tasks.md: a numbered list of small tasks, in build order. For each task give:
- What changes, in one sentence.
- The acceptance criterion from spec.md that it satisfies.
- How to check it (a test name or a manual step).

Each task must be small enough to review as one diff. Do not implement anything yet.

Implement task 3 from specs/cron-explainer/tasks.md only.
Write the failing test first, then the code, then run the tests.
Do not start task 4. Do not change spec.md or plan.md; if you think either is wrong, stop and tell me what and why.
When done, tick task 3 in tasks.md and show me the diff summary.

The line "do not change spec.md" matters. When an agent hits a snag, it will quietly rewrite its own requirements so the code passes. If the spec needs to change, you decide that, then regenerate the plan and tasks from the new spec.

Which tools support spec-driven development?

You need no tool for SDD, only files and discipline. Two tools are built around the loop, and both are documented by their makers. Details below come from their official pages as of October 2026.

GitHub Spec Kit. The Spec Kit repository describes SDD as defining what to build and why, then turning the specification into a plan, tasks and working code. You install it with uv tool install specify-cli, then run specify init my-project with the integration for your agent. Inside the agent you run commands in order: constitution (project principles, once), specify, plan, tasks, implement and converge. Its command reference says specify should focus on the what and why, not the tech stack, which belongs in plan, and that clarify asks up to five targeted questions about underspecified areas before planning. Converge assesses the implementation against the artifacts and appends remaining work.

Kiro. Amazon's Kiro documentation calls specs structured artifacts that formalize the process for features and bug fixes. Every spec generates three files: requirements.md (or bugfix.md), design.md and tasks.md. The feature specs page describes two workflows. Requirements-first goes requirements, then design, then tasks. Design-first starts from a technical design when you already know the architecture or have strict performance needs. There is also a Quick Spec that generates all three in one pass without approval gates, and when you run all tasks Kiro works out which are independent and runs them concurrently.

Plain files. In Claude Code or Cursor you can run the same loop with the templates above and a short rule in your instructions file. Claude Code's plan mode, covered in Claude Code plan mode, is a natural fit for the plan stage because the agent reads and proposes without editing. How instruction files work is covered in how to write a CLAUDE.md and what AGENTS.md is.

When is spec-driven development worth it?

SDD adds steps, and steps cost time. It pays off when a wrong assumption is expensive. It does not pay off when the whole job is a ten-minute experiment.

What goes wrong with spec-driven development?

• A spec that is a design in disguise. If it names frameworks and tables, the plan step has nothing left to decide, and a non-technical reviewer cannot approve it. Keep what and how apart.
• Criteria nobody can test. "Fast", "intuitive" and "clean" are not criteria. Give a number or an example.
• Approving without reading. The loop only works if a human reads the spec, plan and tasks. Skipping the reading turns it into slow vibe coding.
• Letting the agent edit the spec. Agents will patch their own requirements to fit the code. Tell them to stop and ask instead.
• Specs that grow forever. A 3,000-word spec for a small feature is a design document the agent will half-read. If a spec runs long, split the feature.
• Never closing the loop. After implementation, compare the result against the acceptance criteria one by one. Spec Kit's converge command exists for this step; with plain files, ask the agent to list each criterion and show how it was checked.

If you have ideas but no spec yet, the Idea Checker points out what a description is missing, and the guide to scoping an MVP helps you cut a feature down to something one spec can hold. Every idea on the board also comes with a generated build prompt, which works as a rough first spec you can tighten using the template above.