Write a spec by interview

When to use this template

• You have a feature idea that is bigger than a single change, and the requirements still live mostly in your head.
• You want the hard questions, such as edge cases, failure states and tradeoffs, raised before any code exists, while they are still cheap to answer.
• You plan to hand the implementation to a fresh Claude Code session, a teammate or a future you, and need a written spec to work from.

When not to use it

• The task is small and already clear. An interview adds turns without adding much; ask for the change directly or use the planning template.
• The decisions belong to someone else, such as a product owner or a client. Collect their answers first, or run the interview with them in the room.
• You want a polished document for readers outside the team. The spec this produces is a working document for building the feature, not a proposal.

Why this structure

• The prompt starts from a minimal description on purpose. The interview, not your first paragraph, is where the detail comes from, so you do not need to know everything up front.
• It names the AskUserQuestion tool, which Claude Code can use to ask structured questions, and falls back to plain chat questions where that tool is not available.
• The four question areas, implementation, UX, edge cases and tradeoffs, steer the interview toward topics that tend to surface late and cause rework.
• Listing what is already decided keeps the interview from relitigating settled choices, while still allowing Claude to flag a real conflict.
• The closing paragraph defines what the spec must contain: the files and interfaces that change, what is left out, and a final check that confirms the whole feature. With those three parts, someone who was not in the interview can build the feature and verify it.
• Ending with "do not start implementing" keeps the spec session separate. Start a new session to build from the spec, so it begins with clean context.

Example input (fictional)

The feature, in a sentence or two

Per-workspace rate limits for the public API

What you have already decided

Limits are set per plan. Admins can raise them for a single workspace.

Questions per turn

A few questions at a time

Follow-ups to send Claude

• Before you write the spec, list the three decisions you think I am most likely to regret, and why.
• Read SPEC.md back and mark every sentence that a developer could interpret in two ways.
• Split the spec into changes that can each be built, tested and merged on their own, in order.

Common mistakes

• Writing a long feature description first. It front-loads your assumptions and gives the interview less to question.
• Answering "whatever you think is best" to most questions. The spec then records Claude's defaults, not your requirements.
• Implementing in the same long session. The context is full of discarded options; a fresh session working from the written spec stays focused.

Related templates

• Plan a code change before editing: Have Claude Code read the relevant code and propose a file-by-file plan for a multi-file change, without editing anything until you approve it.
• Write tests first, then implement: Have Claude Code write tests that describe a feature before any implementation, confirm they fail, then write code until they all pass.
• Compare options and recommend one: Weigh two or more options against your criteria and hard limits, see the trade-offs side by side, and get a recommendation when the facts support one.

See all templates

Sources

• Claude Code docs: Prompt library (Anthropic documentation)
• Claude Code best practices: Let Claude interview you (Anthropic documentation)