Claude Code Spec Workflow: Spec-Driven Development

The claude code spec workflow is a way of building software where you agree on requirements, design, and a task list before Claude writes any code. Instead of one big vague prompt, you produce a small spec, review each phase, and let Claude implement task by task. The result: fewer surprises, cleaner diffs, and far less rework.

Phase mapping and plan mode behaviour verified 31 July 2026 against Claude Code common workflows

If you have ever handed Claude Code a one-line request like "add billing to the app" and watched it confidently build the wrong thing, you already understand the problem the spec workflow solves. Autonomous agents are fast, but speed pointed in the wrong direction just means you rewrite more code. Spec-driven development slows down the thinking so the building can go fast and stay correct. We set this up on our own machine first, which is why the prompts and outputs here match what you will see.

This guide covers both sides of the topic. First, the method — which works with plain Claude Code and no extra installs. Then the community tooling that automates it, clearly labeled as unofficial. Claude currently spans models like Opus 5 ($5/$25 per million tokens) and Sonnet 5 ($3/$15, per Anthropic's pricing), and the workflow below is model-agnostic: it is reviewed regularly so the phases stay accurate as the lineup changes. If you are brand new to the tool itself, start with what Claude Code is and come back.

Why spec-driven development beats "just prompting"

A bare prompt forces the agent to guess at Stripe versus Paddle, cents versus dollars, refund timing. Writing those decisions down first means Claude implements your choices instead of inventing its own, and you review a page instead of 800 diff lines.

When you prompt an agent directly, it fills every gap you left open with a guess. Ask for billing and the unstated questions pile up fast:

• Should billing use Stripe or Paddle?
• Are prices stored in cents or dollars?
• Does canceling refund immediately or at period end?

A human engineer would ask. An agent, optimized to be helpful, will simply decide — and you find out only when you read 800 lines of diff.

The claude code spec workflow front-loads those decisions into a short document you can read in two minutes. That document becomes the shared source of truth for you and the model. Every ambiguity you pin down in the spec is one the agent no longer has to invent.

There is a second, subtler benefit: reviewability. A 40-line requirements doc is easy to critique. A 2,000-line pull request is not. By reviewing the plan before the code, you catch scope creep and wrong assumptions when they cost one sentence to fix instead of a full rewrite.

The five phases of the claude code spec workflow

Five reviewed phases: requirements (behaviour plus acceptance criteria), design (files, data shapes, error handling, best done in plan mode), tasks (an ordered atomic checklist), implement (one task per commit), and verify (check the finished feature against phase one's criteria).

The workflow is a pipeline of small artifacts, each reviewed before the next begins. You can run every phase with nothing but built-in Claude Code features.

1. Requirements — what and why

Write down what the feature must do and why, in plain language, plus acceptance criteria. "As a user I can cancel my subscription; the cancellation takes effect at the end of the current billing period; the UI shows the end date." No code yet — just the behavior you will test against. Ask Claude to draft it, then correct it. This is the cheapest place to be wrong.

2. Design — how

Now decide the how: which files change, what the data shape is, which API you call, where new modules live, and how errors are handled. This is exactly what plan mode is built for. In plan mode Claude explores your codebase read-only and proposes an approach without touching a single file, so you can argue about architecture safely.

3. Tasks — the ordered checklist

Break the design into an ordered list of small, atomic tasks: "1. Add cancelAt field to the subscription model. 2. Write the cancel endpoint. 3. Wire the UI button." Each task should be something Claude can complete and you can review in one sitting. A good task list is the difference between a smooth build and an agent that wanders.

4. Implement — task by task

Have Claude work one task at a time, committing after each. You review the diff, run the tests, and only then move on. Working in small commits keeps the context focused and gives you clean rollback points. This is where the up-front effort pays off: because the what and how are settled, implementation is mostly mechanical.

5. Verify

Check the finished feature against the acceptance criteria you wrote in phase one. Because those criteria were concrete, verification is a checklist, not a debate. Anything that fails becomes a new, tiny task — not a rewrite.

Mapping phases to built-in Claude Code features

No plugin required. Requirements live in a specs/ file or CLAUDE.md, design runs in read-only plan mode, tasks become a Markdown checklist Claude maintains, implementation uses normal edit mode one commit at a time, and verification is test runs plus diff review.

You do not need any plugin to run the claude code spec workflow. Here is how each phase maps to features that ship with the tool.

The key idea: keep the spec in files, not just in the chat. A specs/ folder (or a section of CLAUDE.md) means the requirements survive across sessions, and Claude re-reads them every time it needs context. Chat history is fragile; a committed spec is durable.

For non-trivial work, Anthropic's own guidance echoes this rhythm — plan, then act, then verify. Their Claude Code best practices write-up is a good companion read on giving the agent enough structure to succeed. If you want a broader end-to-end system around this, our get shit done with Claude Code guide folds the spec workflow into a full daily loop.

Where a spec tool helps — and a caveat

Community packages such as Pimzino's open-source project scaffold the three documents and enforce the review gates for you. They are not Anthropic products, so read the source and take install commands from the project's own README before running anything.

Once you have run the claude code spec workflow by hand a few times, you may want the phases scaffolded for you. Community projects do exactly that.

The best-known is the open-source claude-code-spec-workflow project by Pimzino. It is community-built and not an official Anthropic product. It adds slash commands that generate the requirements, design, and tasks documents for you and then drive implementation phase by phase — for example a command to create a full spec, another to execute a specific task, and a status command to track progress. It also ships an optional set of validator subagents that check each document before you move on, plus a parallel bug-fix flow (report → analyze → fix → verify).

A few honest caveats. First, the project's author has noted that active development has shifted toward an MCP-based version, so the Claude Code-specific package receives limited updates — check its README for the current recommendation before you install. Second, because it is third-party, vet it before running: read the source, confirm what the slash commands do, and treat the install command in its docs as the authority rather than anything you read secondhand. I am deliberately not reproducing exact install strings here, because package names and commands change — get them from the official project page.

Functionally, though, the value is clear: a tool like this removes the boilerplate of writing the same three document templates every time and enforces the review gates so you cannot accidentally skip straight to code. If you would rather build your own lightweight version, our guide on how to make Claude Code do anything shows how custom commands and reusable skills let you script your preferred flow and package a spec template you use across projects.

Best practices for a spec workflow that sticks

Keep specs to one page and update them when the design changes, review every phase, run one task at a time, let plan mode handle design, and match spec size to risk. A CSS tweak needs no spec at all.

The claude code spec workflow fails in predictable ways when people treat it as bureaucracy. Keep it lean.

Keep specs small and current. A spec is a tool, not a contract. If the design changes mid-build, update the file — a stale spec is worse than none because the agent will trust it. One page per feature is plenty.

Review every phase. The whole point is the review gates. Skimming the requirements to "save time" defeats the workflow; that two-minute read is where you catch the expensive mistakes.

One task at a time. Resist the urge to say "do tasks 1 through 5." Small, reviewed steps keep Claude's context tight and your diffs legible. This is one of the most repeated lessons in our Claude Code tips and tricks roundup.

Let plan mode do the design phase. Don't design in your head and dictate — let Claude explore the codebase in plan mode and propose an approach. It often surfaces files and edge cases you forgot, and it costs nothing because no code is written until you approve.

Match the spec size to the risk. A one-line CSS tweak does not need a spec. Reserve the full claude code spec workflow for features with real ambiguity, multiple files, or anything you would be nervous to merge unreviewed.

We run a stripped-down claude code spec workflow on our own build, and the phase that earns its keep every single time is design in plan mode. Left to a one-shot prompt, Claude cheerfully rewrites files we never meant it to touch; asked to plan read-only first, it surfaces the two or three edge cases we had forgotten and we settle them in a sentence. We keep the spec itself in a plain Markdown file in the repo rather than in the chat, because on a native Windows setup where we clear sessions constantly, the committed file is the only version that reliably survives to the next morning.

Method versus tool: which should you use?

Learn it by hand first, because plain Markdown plus plan mode teaches you what a good spec looks like. Reach for a community tool only once repeating the same templates becomes real friction, and vet it before you run it.

If you are learning, run the claude code spec workflow by hand first. Writing the requirements, design, and task files yourself teaches you what a good spec looks like, and the whole thing is just Markdown plus plan mode. Once the rhythm is second nature and you feel the friction of repeating the same templates, reach for a community spec tool to automate the scaffolding — with the vetting caveats above.

Either way, the underlying discipline is the same and it is the part that actually improves your output: decide what and how before when, keep it in files, and review at every gate. That is the whole idea, and it is why spec-driven development consistently beats one-shot prompting for anything non-trivial.