Spec-Driven Development With Claude Code

You can do spec-driven development with Claude Code using nothing but what it ships with. Have Claude interview you and write the answers to a spec file in the repository. Tell it in CLAUDE.md where specs live and that work starts from one. Use plan mode to turn the spec into a plan. Build each task in a fresh session with the acceptance criteria as tests. Before anything counts as done, have a subagent that cannot edit files review the diff against the spec. Keep one task per outcome on a board so the people who are not in the terminal can see where things stand. If you would rather have all of that as fixed commands, GitHub’s Spec Kit installs them as Claude Code skills.

Which tool covers which step

• The spec: an interview with Claude that ends in docs/specs/<feature>/spec.md, reviewed and edited by you.
• The standing rules: CLAUDE.md, which tells every session where specs live and how to use them.
• The plan: plan mode, working from the spec file rather than from a sentence typed from memory.
• The build: a fresh session per task, with tests written from the acceptance criteria first.
• The review: a subagent in its own context that compares the diff with the spec and reports gaps.
• The tasks: a board that the people deciding priorities can read without opening the repository.

Step 1: let Claude interview you into a spec

Anthropic’s Claude Code best practices↗ (opens in a new tab) recommend exactly this for larger features: start with a minimal prompt, have Claude interview you with its AskUserQuestion tool about implementation, interface, edge cases and trade-offs, and have it write a complete spec to a file. The same guide says the most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end check that proves the feature works.

I want to add team invitations: an owner invites someone by email and they
join the team when they accept. Interview me in detail using the
AskUserQuestion tool. Dig into the hard parts: expiry, repeat invites,
people who already have an account, permissions.
When we have covered everything, write the spec to
docs/specs/team-invites/spec.md with: problem, users, in scope, out of
scope, numbered acceptance criteria, constraints, open questions, and a
final end-to-end check.

Then read it properly. The interview gets you a draft; approving it is your job. Anything you are not sure about stays under open questions rather than being settled by the model’s best guess.

Step 2: keep specs in the repo, and point CLAUDE.md at them

Specs belong next to the code, reviewed in the same pull requests. A folder per feature keeps the spec and anything derived from it together.

docs/specs/
  README.md            one line per spec: name, status, board ref
  team-invites/
    spec.md            what and why, acceptance criteria
    plan.md            how, once approved

Resist importing every spec into CLAUDE.md. The memory documentation↗ (opens in a new tab) says imported files are expanded and loaded into context at launch, and suggests keeping each CLAUDE.md under about 200 lines, because longer files cost context and reduce how well instructions are followed. Tell Claude where specs live and how to use them, and let it read the one it needs.

## Specs
- Features are specified in docs/specs/<feature>/spec.md. Read the one for your task first.
- Acceptance criteria are numbered. Name the criterion each test or change satisfies.
- Do not change behaviour the spec does not mention. Anything new goes under open questions.
- An open question is for the owner. Stop and ask; do not pick an answer.
- If the work shows the spec is wrong, propose the change to spec.md before coding round it.

If only part of the codebase follows specs, the same rules can go in a .claude/rules/ file with a paths field, so they load only when Claude reads matching files.

Step 3: plan against the spec

Start plan mode with the spec as the prompt, for example /plan Read docs/specs/team-invites/spec.md and plan it, and ask for the plan to cite criterion numbers and to end with a list of tasks, each small enough to finish and check on its own. How plan mode works, what it blocks and where the plan is saved are covered in Claude Code plan mode. The one addition for spec-driven work: once approved, save the plan as plan.md beside the spec, so it outlives the session.

Step 4: build one task per session, tests first

The best-practices guide suggests that once the spec is complete you start a fresh session to execute it, so the implementation starts with clean context and a written spec rather than an hour of interview. Take the same approach per task: a new session, one task, the spec and plan as its references. Ask for the tests for that task’s criteria first, check they fail for the right reason, then ask for the code. Why tests-first fits inside a spec is in spec-driven development vs vibe coding vs TDD.

Step 5: review against the spec with a subagent

A reviewer that did not write the code is less inclined to excuse it. Subagents↗ (opens in a new tab) run in their own context with the tools you list, so a reviewer without the Edit and Write tools reports rather than fixes. Put this in .claude/agents/ and it is available to everyone who clones the repository.

---
name: spec-reviewer
description: Reviews a diff against the feature's spec.md and plan.md. Use before a task is marked done.
tools: Read, Grep, Glob, Bash
---
You review changes against a written spec. Read docs/specs/<feature>/spec.md
and plan.md, then the diff (git diff main...HEAD).
For each numbered acceptance criterion, say: met, not met, or not tested,
with the file and line. Then list anything the diff changes that the spec
does not mention. Report only gaps that affect correctness or the spec.
Do not suggest style changes. Do not modify any file.

The last two lines matter. The same guide warns that a reviewer asked to find gaps will usually find some even when the work is sound, and that chasing every finding leads to over-engineering. Ask for gaps against the spec, not opinions. Bash is there so it can run git diff and the tests; because a shell can still change files, the prompt says what the reviewer is for, and a permission rule↗ (opens in a new tab) can narrow it further if you want a hard limit.

Step 6: put the tasks where people can see them

The plan’s task list is right for Claude and invisible to anyone not in the repository. On a fenbs board, each outcome someone could check becomes one task: the note says what is missing and gives the spec path; the plan box holds that task’s share of plan.md and is rewritten when the approach changes; the testing status and notes say what was checked and what was not. Open questions from the spec go on the Decisions page, where only a person can be the decider. Claude reaches the board over MCP, and every change it makes is recorded in the history as made by Claude on your behalf.

A worked example: team invitations

1. Interview. Claude asks eleven questions. Two change the design: invites expire after seven days, and inviting an address that already has a pending invite resends it rather than creating a second one. One stays open: can a member, not only the owner, send invites?
2. Spec. spec.md has six numbered criteria, out of scope says “no bulk invites, no invite links without an email”, and the end-to-end check is “invite a new address, accept from the email, land on the team’s board”.
3. Board. Claude files three feature tasks, Send invite, Accept invite and Expire and resend, plus an open decision for the member question, linked to the first task. You order them in Next Up.
4. Plan. In plan mode Claude reads the spec and the existing membership code and proposes a plan with a new invitations table and one endpoint per task. You approve it and it becomes plan.md.
5. Build. A fresh session takes Send invite, writes tests for criteria 1 and 2, sees them fail, implements, sees them pass, and sets the task’s testing to Tested with the test names in the notes.
6. Review. The spec-reviewer subagent reports criterion 5, an expired invite shows a clear message, as not tested. The session adds the test, finds the page shows a generic error, fixes it, and the reviewer comes back clean.
7. Decide. The owner answers the member question on the Decisions page: owners only for now. The next session reads that before starting Accept invite.

Or use Spec Kit’s Claude integration

If you want the steps as fixed commands with templates, GitHub’s Spec Kit has a Claude Code integration. specify init --here --integration claude installs its commands as skills in .claude/skills, and you run /speckit-constitution, /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement and /speckit-converge in Claude Code. It writes each feature to a numbered folder under specs/. It is more structure than the hand-rolled version above and adds checks such as a consistency analysis and a converge step that appends missed work as tasks. Everything it does, and its limits, is in GitHub Spec Kit. The two approaches share the same weak spot, a task list in a file, and the same fix.