Plan with Claude Code: an approved plan before any code

The Claude Code planning section is four guides for developers and tech leads that turn a goal into an approved plan before any file changes: mapping an unfamiliar codebase, designing a feature, choosing an architecture, and starting a new project. Each guide uses plan mode, which blocks edits until you accept the plan.

You asked Claude Code for “OAuth login”, and 40 minutes later you have 900 changed lines built on a session model your team retired last quarter. The code is not the problem; nobody agreed on the shape before it was written. Planning moves your review to a one-page plan with testable acceptance criteria, so that the diff has to match a contract instead of your memory.

Prerequisite: Claude Code installed, signed in, and opened in your repository. If it is not, start with the Claude Code quick start.

Which planning guide do you need?

Your situation	Start with	What you leave with
You joined a repository and do not know where anything lives	Understand an unfamiliar codebase	A map with file citations, proved by a passing test
You have a feature request and no design yet	Plan a feature with deep reasoning	A spec with acceptance criteria and a task list
You must choose between designs, or plan a migration	Architecture analysis and system design	An ADR and a phased, reversible migration plan
You are starting from an empty directory	Start a new project from the terminal	A running service, passing CI, and a CLAUDE.md with its build and test commands

Start a planning session in plan mode

Plan mode is a permission mode: Claude reads files and, where auto mode is available, runs commands its classifier approves, but every edit stays blocked until you approve a plan. To start in plan mode, run:

claude --permission-mode plan --effort high

To switch a running session, type /plan and the goal, or press Shift+Tab until the mode indicator shows plan mode:

/plan add rate limiting to the public API

From v2.1.280 (both release channels on 2026-10-12), Claude Code starts on Claude Opus 5.5 at medium effort on every paid plan and the Anthropic API (Microsoft Foundry defaults to Sonnet 4.5, which Anthropic retires on 2026-11-30 on Anthropic-operated platforms). For planning, raise effort to high or xhigh before you change model; the models hub covers opusplan, Claude Fable 5.1, versions, and prices.

How do you check a plan without reading every line of the result?

A plan earns approval when every claim in it can be checked by a tool, not by your memory of the code. Before you accept a plan, confirm that it has these five parts:

1. Acceptance criteria that each map to a named test, written to fail before implementation. See executable acceptance criteria.
2. Citations as path:line for every claim about existing code, so a grep can confirm them.
3. Files in scope and out of scope. Tests and migrations the agent must not edit belong in the out-of-scope list.
4. Verification commands, exactly as CI runs them: test, typecheck, lint.
5. Rollback: how the change is reverted or switched off.

After implementation, you sign off on evidence: the new tests went from red to green, CI passes, and the diff touches only files in scope. The developer approves a feature plan; a tech lead approves anything that changes an architecture decision. The reasoning is in evidence, not diffs.

Copy-paste prompt: a plan you can verify

Plan this change; do not edit anything yet: add per-API-key rate limiting
(100 requests per minute) to the public REST endpoints.

Produce a plan with exactly these sections:
1. Current state: how requests reach the handlers today, with path:line
   citations for every claim.
2. Acceptance criteria: 3-6 Given/When/Then statements, each mapped to the
   name of a test that will fail before the change and pass after it.
3. Files to change, and files you must not touch (existing tests, migrations).
4. Steps in order, each small enough to review on its own.
5. Verification: the exact test, typecheck, and lint commands CI runs.
6. Rollback: how to switch the limit off without a deploy.
List open questions at the end instead of guessing.

Copy-paste prompt: challenge the plan before you approve it

Use a subagent to review the plan above against the codebase. It must:
- check every path:line citation and report any that are wrong;
- name any caller, job, or config the plan misses that reads the code it changes;
- say which acceptance criterion could pass while the feature is still broken.
Report findings only. Then revise the plan and mark each change.

After you approve, ask Claude to save the plan as docs/plans/<topic>.md before the first edit, so it survives /compact, a new session, and a handover.

What goes wrong when you plan with Claude Code?

Symptom	Likely cause	Recovery
The plan is a generic outline	The prompt named a goal, not constraints	Give the required sections, as in the first prompt, and point it at the files that matter
The plan cites files or functions that do not exist	Claims written from assumption	Run the review prompt; reject any plan with a wrong citation
Implementation drifts from the approved plan	The plan lived only in the conversation	Save it to docs/plans/, and in each new session say “Follow docs/plans/X.md; stop and ask before deviating”
Context fills up during exploration	The main session read the whole tree	Delegate exploration to the built-in Explore subagent; see codebase analysis
Edits happened before you approved	The session was not in plan mode; from v2.1.283 interactive sessions start in auto mode	Check the mode indicator under the prompt; undo with /rewind (or Esc Esc) and restart with --permission-mode plan
/ultraplan is not available	It was removed from the command reference in v2.1.222 and is off by default	Use /plan

Where to go after the plan is approved

• Spec-driven development: keep the spec, not the code, as the thing people review, across all three tools.
• Build with Claude Code: execute the approved plan.
• The method’s plan and build stages: how intent.md feeds this plan, and how the approved plan.md drives implementation and its evidence.
• The same stage in other tools: plan with Codex and plan with Cursor.

Understand an unfamiliar codebase Map the repository in plan mode before you plan any change