How to write a PRD for Claude Code

Who is this document actually written for?

A reader who never asks a clarifying question, never infers the thing you forgot to say, and never pauses to check whether your intent matches your wording. Every ambiguity you leave becomes a decision made without you.

That single property changes what a spec has to contain. A human engineer reading a PRD fills the gaps from context: they know which service owns this route, they know the team never touches that directory, they know "one click" means the existing pattern used on three other screens. An agent fills those same gaps with a plausible guess. The document's job stops being alignment and becomes elimination of ambiguity. The named pattern for this is the Product Requirement Prompt; what follows is how to write one against a real repository.

What replaces the parts a human reader would have filled in?

Four things, and they are concrete rather than conceptual.

The files in scope. Name them. If you know the change lives in two components and one hook, say so. Anthropic's own best-practice guidance frames most of these patterns around a single constraint: the context window fills fast and performance degrades as it fills. An exploration pass to find files you already knew about spends that budget for nothing.

The verification command. One command the agent can run whose output it can read: a test file, a build, a lint, a script that diffs output against a fixture. The guidance is blunt about why this matters, because Claude stops when the work looks done, and without a runnable check "looks done" is the only signal available.

The fence. What must not change. Generated files, a migration directory, a vendored component library, anything with its own review process. An agent fixing one thing will happily restructure something adjacent unless told not to.

The done condition. A sentence that resolves to true or false without your judgement. "The new test passes and the existing suite still passes" resolves. "The feature works well" does not.

Where does the shared context live, the spec or CLAUDE.md?

Split it by lifespan. CLAUDE.md is the repository's standing memory, loaded at the start of a session, and it holds what stays true across every task: the commands to run tests and builds, the directory map, naming conventions, and the list of things nobody edits by hand. The spec holds what is true for this task only.

The working rule is repetition. A line you would write into three consecutive specs has already earned its place in CLAUDE.md, and leaving it in the specs means you will eventually update two of them and forget the third. A line that only makes sense for this feature stays in the spec, because putting it in the shared file makes every unrelated session carry it. Context architecture is the wider version of this decision, and it is the difference between a setup that compounds and one that gets re-explained every week.

What does a worked section look like?

Take a requirement a normal PRD would state as an outcome: a user reaches their current invoice from the dashboard in one action. Written for a human, that is correct and deliberately open. Written for execution, it needs four more lines.

The files: the dashboard container, the navigation component, and the existing invoice query hook. The behaviour, including the empty case, because an account with no invoices is where an unspecified spec produces a blank page. The verification: the name of the test to add and the command that runs it. The fence: the shared design-system package is not in scope for this change, even if the quickest fix would be to edit it.

None of that is product thinking. All of it is the thinking a human would have done silently, written down so an agent does not have to invent it.

The empty case deserves a note of its own, because it is the most reliable source of surprise in an agent-built change. A spec that describes only the happy path gets a happy path, and the state where the list is empty, the request times out, or the user lacks permission gets whatever the agent considered reasonable at the time. None of those states are hard to specify. They are just easy to forget, and they are exactly the states a reviewer notices last.

How do you keep it from becoming a novel?

By writing only the ambiguities you can actually predict.

The temptation with a literal-minded reader is to specify everything, which produces a document that restates the codebase back to a system already able to read it, and spends the context budget doing it. The useful test before adding a line: would a competent new engineer, on their first week, get this wrong? If yes, write it. If it is something anyone would infer from the code in front of them, leave it out and let the agent read the code.

Two other habits keep specs short. Explore first, then plan, then code is the ordering Anthropic recommends, and it means the spec does not have to predict what an exploration pass will surface. And course-correcting early costs far less than a long spec written to prevent every possible drift, because a wrong direction caught in the first minute is a sentence, where the same drift caught at the end is a rewrite.

What still needs a person?

The judgement the agent is not positioned to make, and there is more of it than the workflow suggests.

Reviewing the diff for changes outside the fence, because an agent that respected the fence and one that quietly stepped over it both report success. Deciding whether the verification command actually tested the thing you cared about, since a passing test written by the same pass that wrote the code is a weaker signal than it looks. And owning the product decision itself, which the execution spec deliberately does not contain: why this feature, for whom, and what gets cut. That conversation belongs in a document written for people.

The honest limitation is that precision has a ceiling. A well-fenced spec with a real verification command raises the odds of a correct first pass considerably. It does not make review optional, and treating it as though it does is how teams ship a change that passed its own test and broke something the test never covered.

Where this workflow is taught

Builders Camp's Building with Claude Code bootcamp, taught by Guilherme Salgueiro, covers this as one module inside a larger system: CLAUDE.md and context architecture, custom skills and agents, MCP tool integrations, Product Requirement Prompts against traditional PRDs, multi-agent orchestration across worktrees, then hooks and quality gates so the pipeline checks its own output. It runs across 2 live sessions and 9 self-paced microlessons.

If you are earlier in this and want the product-manager entry point rather than the full system, Claude Code for Product Managers covers setup, spec-to-implementation prompts, reviewing diffs, and the team safety standards that keep an agentic workflow from producing a mess nobody can review. The AI Agentic Builders Expert Track bundles both with the agent design skills that sit above them. Reusable agent skills are the next step once you notice you are writing the same spec section repeatedly.

See the Building with Claude Code bootcamp

Keep the specs you write. After a dozen of them the recurring sections stop looking like prose and start looking like a template, and at that point the right move is to promote them into a repeatable command rather than retyping them from memory each time.