PRD to plan to tasks in Claude Code: a reviewable path from requirements to code

The PRD-to-plan workflow in Claude Code turns a product requirements document into three reviewable artifacts: numbered acceptance criteria, a file-level plan written in plan mode, and a task list that Claude works through one verified step at a time. Plan mode blocks edits until the plan is approved, and the plansDirectory setting keeps plan files in the repository.

Your product manager drops a two-page PRD for a notification system into Slack: email digests, in-app alerts, per-type unsubscribe. If you paste it into Claude Code and say “build this”, you get 40 changed files, a schema you did not choose, and no way to tell which requirement each change serves. This page is for developers who are new to Claude Code and want a repeatable way to go from a PRD to merged code, and for tech leads who want those plans reviewed in pull requests before implementation starts.

What you’ll walk away with from the PRD workflow

• A three-phase routine (analyse, plan, execute) that you can run on any feature with a written spec.
• Three copy-paste prompts: PRD analysis with numbered acceptance criteria, a plan in which every step names the check that proves it, and task-by-task execution with a test gate.
• A project setting that saves plan files in the repo, so a teammate reviews the plan in a pull request.
• A traceability table that lets you sign off on the feature by checking acceptance criteria against passing tests instead of reading every line of the diff.
• Recovery steps for the ways this workflow goes wrong.

What do you need before you start?

• Claude Code installed and signed in, and a CLAUDE.md that describes your stack and conventions. If you have not written one, start with project initialization. The plan can only follow the architecture rules that Claude can read.
• The PRD as a file in the repository, for example docs/prd/notifications.md. A file can be referenced, versioned, and diffed; a pasted Slack message cannot.
• A test command that runs in under a few minutes, such as npm test. The per-task gate in phase 3 depends on it.

This page is the quick-start version. For features that begin as a one-line request with no written spec, use the requirements interview and fresh-session plan audit in feature planning in Claude Code.

How do you set up Claude Code for a PRD-driven feature?

1. Keep plans in the repository. By default, Claude Code writes plan files to ~/.claude/plans/, outside your project, where nobody else can review them. Add plansDirectory to the project settings file .claude/settings.json:

   {
     "plansDirectory": "docs/plans",
     "showClearContextOnPlanAccept": true
   }

   The second key adds a “clear context” option to the plan-approval dialog (see Phase 2). The path is relative to the project root and must stay inside it. Claude Code 2.1.283 rejects a path outside the root, logs an error, and falls back to ~/.claude/plans/.

2. Start the session in plan mode. In plan mode Claude reads files and explores the codebase, but it does not edit your project files until you approve a plan. From v2.1.283 (the latest release channel), interactive sessions start in auto mode, so plan mode is something you ask for. Run this in your terminal:

   claude --permission-mode plan

   In a session that is already running, type /plan, or press Shift+Tab until the footer shows plan mode on.

3. For a large PRD, raise effort before planning, for example with /effort high. Start on the default model and tune effort before you switch model; deep reasoning in Claude Code explains the levels.

Phase 1: How do you get Claude to analyse a PRD before it writes code?

Ask for analysis and nothing else. The most useful output of this phase is the list of questions the PRD does not answer, because each unanswered question becomes a guess in the code. The second most useful output is a numbered list of acceptance criteria, because later phases hang everything off those numbers.

Copy-paste prompt: PRD analysis with numbered acceptance criteria

Read @docs/prd/notifications.md and the code it touches. Do not propose
an implementation yet.

1. Summarise the feature in five sentences or fewer.
2. Rewrite every requirement as a numbered, testable acceptance criterion
   (AC-1, AC-2, ...) in Given/When/Then form. Mark any criterion you had to
   infer rather than read in the PRD with (inferred).
3. List the questions the PRD does not answer, ordered by how much of the
   design depends on the answer. For each one, give the default you would
   choose and why.
4. List the existing modules, tables, and APIs this feature will touch,
   with file paths you have actually opened.

Answer the open questions in the chat, then ask Claude to update the criteria. Send any criterion marked (inferred) back to the product manager: that is the conversation the PRD should have forced, and it takes minutes now instead of a rewrite later. For a deeper treatment of turning criteria into failing tests, see executable acceptance criteria.

Phase 2: How do you turn the analysis into a plan you can review?

A reviewable plan names files, orders the steps by dependency, and says how each step is checked. A plan without a check per step can only be reviewed by reading the code it produces, which is the work you are trying to avoid.

Copy-paste prompt: a plan where every step names its proof

Using the agreed acceptance criteria, write the implementation plan.

For each numbered step, give:
- the files to create or change (existing paths must be ones you opened)
- what changes, in two or three lines
- which acceptance criteria (AC-n) the step satisfies
- the steps it depends on
- the exact command that proves the step is done, such as a named test file
  run with `npm test -- <file>`, a type check, or a migration dry run
- size: small, medium or large; split anything large

End with a table mapping every AC to the step and the test that covers it.
Any AC without a test is a gap: flag it rather than hiding it.

Claude presents the plan in an approval dialog. Read it against three questions: does every acceptance criterion map to a test, does any step touch a file Claude never opened, and is any step large enough to hide a design decision? If any check fails, type your feedback and Claude revises the plan while staying in plan mode.

When you approve, the dialog in Claude Code 2.1.283 offers two ways to continue by default: keep the context and continue in auto mode (auto-accept edits where auto mode is unavailable), or keep the context and approve each edit manually. Choose manual approval for your first few runs so you see what Claude does with the plan. Because step 1 set showClearContextOnPlanAccept, the dialog also offers a clear-context option that shows how much of the context window is used (default false, checked on Claude Code 2.1.283). Clearing the context is useful after a long analysis phase, because execution then starts from the plan file instead of a full context window, and the usage readout tells you whether clearing is worth it.

For team review, commit the plan file from docs/plans/ on the feature branch and open a draft pull request before implementation. The reviewer comments on the approach and the acceptance criteria table, not on code that does not exist yet.

Phase 3: How do you execute the plan as a tracked task list?

Claude Code keeps a task list for multi-step work. Press Ctrl+T to show or hide it while Claude works. Ask for one task per plan step, and make the task’s proof command the condition for marking it complete.

Copy-paste prompt: task-by-task execution with a test gate

Execute the approved plan in docs/plans/. Create one task per plan step,
in dependency order.

For each task, in order:
a) Write or update the test named in the plan first and run it; it should fail.
b) Implement the step.
c) Run the step's proof command, then the type check and the linter.
d) Mark the task complete only when all three pass. If a check fails twice,
   stop and tell me what failed instead of weakening the test.
e) Commit with a message that names the step number and the ACs it covers.

Stop after you complete plan step 3 so I can check direction before you continue.

The instruction “instead of weakening the test” matters. Without it, an agent under pressure to finish a task sometimes edits the assertion rather than the code. The pause after plan step 3 gives you a cheap checkpoint while the schema and service layer exist but nothing depends on them yet.

How do you verify the feature without reading every line?

Sign-off rests on evidence you can check in minutes, not on reading the diff. Ask Claude to produce it at the end:

Copy-paste prompt: acceptance criteria traceability report

Produce a traceability report for this feature. For every acceptance
criterion AC-n: the test file and test name that covers it, whether it
passes right now (run the tests, do not assume), and any AC that is only
partly covered. Then list every file changed that no plan step mentions.

Check	What it proves	Who signs off
Acceptance criteria and plan in a draft PR	The right thing is being built, in an order that makes sense	Product manager and tech lead, before implementation
Every AC mapped to a passing test	Each requirement behaves as agreed	Developer, from the traceability report
Type check, linter, and full test suite in CI	Nothing else broke	CI, on every push
Files changed outside the plan	Scope did not creep	Developer; each one is explained or reverted
/code-review in a fresh session	A second pass for bugs the tests do not encode	Developer reads the findings, not the whole diff

You still read code where the risk is concentrated: migrations, authentication, and anything that sends email to real users. For everything else, a failing check tells you where to look. To enforce the gate without relying on the prompt, run the test command from a hook; see hooks automation.

What does the workflow look like on an example feature?

In a worked example for the notification PRD, a Next.js app with Drizzle ORM and Resend, phase 1 produces 11 acceptance criteria and six open questions. The one that changes the design is “Does a daily digest respect the user’s time zone?” The PRD does not say, and the answer decides whether the digest job runs once a day or once an hour.

The approved plan has eight steps:

1. Schema: notifications and notification_preferences tables, with a migration. Proof: the migration applies and rolls back locally.
2. Preferences API: GET and PUT /api/notifications/preferences, with input validation. Proof: route tests for AC-1 to AC-3.
3. Notification service: create, deduplicate, and look up preferences. Proof: unit tests for AC-4 to AC-6.
4. Email templates for immediate and digest sends. Proof: snapshot tests for AC-7.
5. Digest job, run hourly and filtered by time zone. Proof: a test with a fake clock for AC-8 and AC-9.
6. Notification history UI. Proof: a component test for AC-10.
7. Per-type unsubscribe handler with a signed link. Proof: tests for AC-11, including a tampered link.
8. Traceability report and /code-review.

During review, the tech lead moves step 5 to a second pull request so that immediate notifications can ship first. That is a one-line plan change, and it costs nothing because no code exists yet.

How do you change the plan once work has started?

Plans change. Tell Claude what changed and ask it to update the plan file and the task list together, so they do not drift apart:

Move step 5 (digest job) out of this plan into a follow-up. Update the plan
file, the AC table, and the task list. List which ACs are now uncovered.

Step 3 is too big. Split it into one step per notification type (comments,
mentions, assignments), each with its own test. Update the plan file first.

When the PRD-to-plan workflow breaks

Claude starts writing code during analysis. You are not in plan mode, or the session left it after an approval. Check the footer for plan mode on, re-enter with /plan, and use claude --permission-mode plan for the next session.

The plan names files that do not exist. Claude guessed the structure instead of reading it. Reject the plan with: “Open every file you listed and confirm its path. Remove or correct any path you have not opened.” The “paths you have actually opened” line in the prompts prevents most of these.

The plan is too vague to review. Steps like “implement the service layer” hide the decisions. Ask for function signatures and the test that proves each step: “For step 3, list the functions you will add, their signatures, and the test cases for each.”

The plan file is not in the repo. plansDirectory is missing, set in the wrong settings file, or points outside the project root, so Claude Code fell back to ~/.claude/plans/. Put the key in .claude/settings.json with a path relative to the root, and restart the session.

Claude works out of order or skips a failing task. Press Ctrl+T to see the task list, then redirect: “Stop. Step 4 depends on step 2, which is not complete. Finish step 2 and show me its test run.”

The context runs out midway through a large plan. Long analysis plus execution fills the window. Because the plan and acceptance criteria are files, start a fresh session and say: “Read the plan in docs/plans/ and git log, then continue from the first step without a commit.” Error recovery covers rewinding a session that went wrong.

The plan ignores your architecture. The rules are not written where Claude reads them. Add them to CLAUDE.md, for example “all database access goes through src/db/repositories”, then ask Claude to re-plan. See the memory system for where each kind of rule belongs.

Where to go next with PRD-driven planning

The same routine exists in the other tools: Cursor users follow the PRD workflow in Cursor, and Codex users start with your first Codex task. For the method behind the artifacts, read the artifact chain and spec-driven development.

Feature planning in Claude Code Requirements interview, acceptance criteria, and a fresh-session plan audit

Deep reasoning Effort levels for hard design decisions inside a plan

Development workflow The day-to-day loop once the plan is approved

Executable acceptance criteria Turn each criterion into a failing test before implementation