Spec-driven development with Claude Code

Published 23 October 2026

You do not need a framework to do spec-driven development in Claude Code. Anthropic’s own guidance describes the whole loop: let Claude interview you, have it write the spec to a file, edit that file until you would sign it, then start a fresh session, plan in plan mode, and build against checks Claude can run. Frameworks — Spec Kit, OpenSpec, Superpowers, BMAD, GSD — add a fixed pipeline, a folder layout and, for some, state that survives across sessions; they also add tokens and their own upkeep. Below are the workflow without a framework, with the files; each framework’s setup in Claude Code, checked against its repository on 23 October 2026; how to choose; and what to do with the spec when the work is merged.

Once the spec is complete, start a fresh session to execute it. The new session has clean context focused entirely on implementation, and you have a written spec to reference.

— Claude Code documentation, Anthropic

Spec-driven development in Claude Code without a framework

Five steps, all with features Claude Code already has.

1. Keep the standing rules in CLAUDE.md. Claude reads it at the start of every session. Run /init for a starter, then cut it down: Anthropic’s test for every line is “Would removing this cause Claude to make mistakes?”, and its warning: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions!” Add one rule that points to the specs.
2. Let Claude interview you, and write the spec. Ask for questions, not code. Anthropic’s prompt is below.
3. Edit the spec until you would sign it. Short, one change, acceptance as cases that pass or fail, out of scope and must-not-change written down — the twelve rules. If someone else has to agree, they read it now.
4. Start a fresh session and plan. Press Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan. Ask Claude to read the spec and the code it touches and propose a plan. Read the plan; Ctrl+G opens it in your editor. Then approve it.
5. Build against checks Claude can run. Every acceptance case becomes a test, and Claude runs them. Anthropic’s advice is to “Give Claude a way to verify its work”; for a check that must pass every time, a hook can block Claude from finishing until it does.

The files

A layout that works for a small team — one spec per change, next to the code:

CLAUDE.md
specs/
  payment-reminder.md
  invoice-export.md
src/
tests/

The part of CLAUDE.md that ties it together, as an example:

## Specs
- One spec per change, in specs/.
- Before planning, read the spec named in
  the task, and the code it touches.
- Every acceptance case becomes a test.
- If the work shows the spec is wrong,
  stop and say so. Do not change the
  spec yourself.

The interview prompt from Anthropic’s documentation, with your feature in place of the brackets:

I want to build [brief description].
Interview me in detail using the
AskUserQuestion tool.

Ask about technical implementation,
UI/UX, edge cases, concerns, and
tradeoffs. Don't ask obvious questions,
dig into the hard parts I might not
have considered.

Keep interviewing until we've covered
everything, then write a complete spec
to SPEC.md.

What the spec should end up containing is in the spec template; its section on spec.md vs CLAUDE.md explains which rule goes where. In short, CLAUDE.md holds what is true for every change; the spec holds this change.

Plan mode or a spec?

Plan mode on its own is enough more often than the frameworks suggest. Anthropic’s threshold: “If you could describe the diff in one sentence, skip the plan.” Above that, a plan in plan mode serves one person in one session. A spec file earns its place when the work outlives the session, when several sessions or agents build against it, or when someone other than you has to agree with it — because a plan disappears with the session and a file does not. Where each tool keeps its plans, and what the research says, is in plan mode vs spec-driven development.

Practitioners often stop there. One commenter’s setup: “Even OpenSpec is too heavy for me. I do similar things but in one file, which I generate with a skill after a planning session. The important thing is to have a file reviewers can audit the code against” (Hacker News, 2026).

With a framework: Spec Kit, OpenSpec, Superpowers, BMAD, GSD

Each installs into Claude Code as slash commands or skills. Setup as each repository’s README gave it on 23 October 2026; these change often, so check the README before you run them.

Spec Kit (GitHub)

A fixed pipeline per feature, with a constitution written once per project. Needs Python 3.11+ and uv:

uv tool install specify-cli
specify init my-project \
  --integration claude

For an existing project, specify integration install claude. The steps install as skills in .claude/skills/ and run in Claude’s chat, one at a time, reviewing each result:

/speckit-constitution
/speckit-specify  (what and why)
/speckit-plan     (the stack)
/speckit-tasks
/speckit-implement
/speckit-converge

Each feature gets its own folder with a spec, a plan and tasks (Spec Kit; release 1.2.3).

OpenSpec

One set of current specs for the system, changed by proposals that are merged in when the work is archived. Needs Node.js 20.19 or later:

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

Then, in Claude Code: /opsx:explore to think a change through, /opsx:propose with a name for the change, /opsx:apply to build it, and /opsx:archive to merge its spec changes into the current specs (OpenSpec; release 1.14.3).

Superpowers

A library of skills that shape how Claude works more than what it writes down: brainstorming before building, a written plan of small tasks, test-first implementation, review between tasks. In its own words: “Small changes get agreed in chat; projects get a written design document a builder could plan from.” Install it from Anthropic’s official plugin marketplace: run /plugin install with superpowers@claude-plugins-official (Superpowers; release 7.0.1).

BMAD Method

Agent roles — product, architecture, development, testing — sized to the change. The stable line installs into the project with Node.js and Python:

npx bmad-method install

Then invoke bmad-build with what you want to change, and bmad-help for what comes next. A version 7 is in preview, installed as a Claude Code plugin (BMAD Method; release 6.12.4).

GSD

A discuss, plan, execute, verify loop in which each executor starts with a fresh context. The original repository is archived; the project continues as GSD Core:

npx @opengsd/gsd-core@latest

The installer asks for your agent. Then /gsd-new-project for a new project or /gsd-onboard for an existing codebase (GSD Core; release 1.18.0).

How the tools differ in depth, and what their users ask for, is in Spec Kit vs OpenSpec vs BMAD.

Which one, if any

Two findings temper the choice. Nobody uses these tools as shipped: in interviews with 21 practitioners, “Almost no participant used an SDD tool as published” (Agarwal et al., 2026, preprint). And in one study of Spec Kit’s workflow, the spec, plan and task files alone barely changed the judged quality of the result; what helped was letting the agent read the repository at each step (Spec Kit Agents, preprint). Whatever you choose, let Claude read the code before it plans.

One commenter’s summary of where frameworks still help: “The frameworks still earn their keep on multi-session projects where you need persistent task state that survives context resets” (r/ClaudeCode, 2026).

What it costs

Planning is paid for in tokens and time. One team quoted in the practice study found “the spec-driven runs typically consume two to three times as many tokens and take about twice as long” (Agarwal et al.). A framework adds its own steps and documents on top, and each document is only as useful as the part someone reads. What the research says about the payback is in does spec-driven development work?

When the spec turns out wrong mid-build

It will. Stop the build, change the spec, and plan again from the changed spec — not from a long conversation about what changed. Anthropic’s rule of thumb for any session applies here too: “If you’ve corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned.”

After the merge: keep the spec or archive it

Decide this before the first spec, because left alone the spec drifts. In public repositories, 81.5% of spec files are committed once and never changed again (Agarwal et al.). Two workable choices:

• Keep current specs, one per area of the system, and change them with every change that alters behaviour — OpenSpec’s model. The spec stays a description of what the software does now.
• Archive change specs once merged, and keep what the system does in tests and the code. The spec stays a record of what was agreed for that change, and nobody reads it as current.

Either way, say which in CLAUDE.md. Why specs and code part ways, and how to tell, is in what spec drift is; what git records and what it does not, in requirements in git.

Where Specroot fits

This is the problem Specroot works on: specs that the people who have to agree can read without opening Claude Code or git, and that stay current after the merge. Specroot for teams using AI coding agents.