How Do You Build a Whole Module From a Spec?
Have Claude interview you until the requirements are pinned down, save them to SPEC.md, then build from that file in a fresh session. Anthropic's Claude Code docs recommend this exact order. The spec gives Claude what it can't get from your repo: what you want, and what done means.
I want to add [feature] to [project], and I haven't thought it all through yet. Keep asking me questions until you have enough to write the spec, then save it as SPEC.md. The spec must cover: the public interface, inputs and outputs with types, error behavior, constraints such as allowed dependencies and performance, what's out of scope, and acceptance checks written as commands that pass or fail. Don't write any code yet. --- After /clear, send this second part --- Build what SPEC.md describes. Follow the existing patterns in [path to a similar module]. Add no libraries the spec doesn't list. Run [test command], and fix what fails until it passes. Finish by showing me the command you ran and its output, then list anything the spec left open and what you chose.
- 1Claude interviews you
- 2SPEC.md
- 3Fresh session builds
- 4Reviewer checks against SPEC.md
Try it now
- 1In Claude Code, send the first part of the prompt for a small real feature, and answer its questions.
- 2Open
SPEC.md, correct anything wrong, then run/clear. - 3Send the second part. Read the test output it shows you, not just its summary.
- 4Run a review:
use a subagent to compare the [feature] diff with SPEC.md. Report missing requirements and untested edge cases. Skip style.It worked if each gap it reports traces back to a line in the spec.
Use it when
A new API client, parser, validation layer or service where the requirements live in your head and the code doesn't exist yet. It suits Claude Code best, since Claude can write the file, run the checks and read the output. In the Claude app, run the same interview and keep the spec as a document, then paste it into a new chat when you build.
Skip it when
Skip it for a change you can describe in two sentences. Name the file, the symptom and what fixed looks like, and send that. Also skip it while you're still deciding the design, because a spec written too early locks in the wrong interface. Compare designs first.
Why it works
Claude reads code well but can't read your intent. Anthropic's docs say it tends to take a request narrowly and build the minimum, since it can't tell how far you wanted to go. In the interview, it comes back with multiple-choice questions on the parts you haven't pinned down, such as per-user or per-key limits. Starting a fresh session matters because every request resends the whole conversation, so the build begins with clean context and a written definition of done. The same file then gives a reviewer something concrete to check. The check commands matter too: the docs say Claude stops when the work looks done, unless it has something to run that comes back pass or fail.
Example
Say you're adding rate limiting to a public API. The interview might settle on limits per API key, 100 requests a minute, a 429 response with a Retry-After header, no new dependencies, and no admin screen for now. SPEC.md records those, plus an acceptance check such as pnpm vitest run tests/rate-limit.test.ts. In the new session, Claude builds against that file and has to get the check to pass.
Going further
Make the reviewer permanent. Save .claude/agents/reviewer.md with tools: Read, Grep, Glob in its frontmatter, and Claude Code itself stops that subagent from editing anything. Then watch scope in both directions. To get more, Anthropic's docs say be ambitious still helps, as in be ambitious: empty and error states, not just the layout. To get less, its Sonnet 5.5 guide says that model tends to add tests, docs and small supporting files you didn't ask for, and suggests a system prompt line limiting changes to what was requested. A version in your own words: Don't add anything I didn't ask for, including tests, docs or refactors. Mention ideas at the end instead.
Common mistakes
- Building in the same session as the interview. The docs recommend a fresh one, so the build starts from the written spec and not from the whole discussion.
- Writing
be thoroughorthink hardinto the prompt. Anthropic's docs call these ordinary text. Effort is the real control, so run/effort highif the work needs it. - Accepting "all tests pass" on its own. The docs say to ask for the command and its output, because the claim alone tells you very little.
- Dropping
skip stylefrom the review prompt. The docs warn that a reviewer told to look for problems always turns up some, and acting on all of them leaves you with needless layers and tests.
Sources
Checked 6 November 2026. Products change often, so confirm details with the vendor.