On this page
TLDR
Plan Mode forces Claude Code to draft and approve a multi-step plan before executing. Use it for non-trivial changes (3+ steps); skip for trivial edits. The exam pattern: when do you require Plan Mode vs. direct execution. Claude Code feature
What it is
Plan mode is a Claude Code feature that separates exploration from execution. The workflow: enter plan mode, issue a research or design request, Claude analyzes the codebase and produces a structured plan, then you approve or refine the plan before execution. Only after approval does Claude write or modify files. This makes the reasoning visible and gated.
What distinguishes plan mode from direct execution is the approval gate. Direct execution starts modifying files immediately on a clear request. Plan mode is for ambiguous or multi-faceted requests where there are 3+ viable architectures with tradeoffs. Without upfront analysis, rework is inevitable. Plan mode prevents rework by validating the architecture before the first file edit.
The trigger threshold is 3+ steps involving architectural or design decisions. A single-file bugfix with a clear stack trace does not need plan mode. A 30-file refactor, domain model rewrite, or library migration always needs it. The test: "Can I confidently describe the change without exploring the codebase first?" If no, plan mode.
Plan mode works in locked phases. Phase 1: Claude explores files, identifies interdependencies. Phase 2: Claude proposes 2-3 architectural options with tradeoffs. Phase 3: you choose or refine. Phase 4: Claude executes. Each phase is fully visible; you can exit, iterate, or reject without partial damage. This is why plan mode prevents the over-confident bad decision class of bugs.
How it works
The plan-mode loop has four decision points. Explore: Claude reads the codebase, writes a diagnosis. Propose: Claude offers 2-3 options with explicit tradeoffs (performance, complexity, testing burden). Decide: you approve, request changes, or reject. Execute: only after approval, Claude modifies files and runs tests.
Blast radius assessment is plan mode's critical step. Before modifying any file, Claude must answer: "Which files change? What breaks if done wrong? What tests validate?" For architectural changes, the answer spans dozens of files. Plan mode forces this estimation before the first edit, not after a broken test reveals the gap.
Plan mode is not a separate conversation. Same session, same message history, same context window. Claude explains the codebase aloud; you ask clarifying questions; Claude refines. Then you issue an approval ("Implement option A") and execution proceeds. One coherent thread, unlike fork or subagent which isolate context.
Rejection and iteration are zero-cost. Read the plan, dislike it, reply "No, fewer services". Claude re-analyzes (same session) and produces a new plan. No rework of partial code, no discarded PRs. Iteration cost is milliseconds of token budget, not hours of human rework.
Where you'll see it
Monolith-to-microservices refactor
50K-line e-commerce platform splitting. Direct execution risks boundary mistakes that cascade through 6 months of work. Plan mode: explore, propose 3-service boundary, you question whether payments should be separate. Claude revises. Approval before refactoring.
Major dependency upgrade (React 18 → 19)
120 components. Not a mechanical find-replace. Plan mode: scan, propose codemods for 80% + manual review for 20%, identify components at risk, recommend test-first sequence. You approve, then execute.
Multi-service CI/CD pipeline redesign
Brittle workflows. No single right redesign. Plan mode: map current pipeline, identify bottlenecks, propose 2 architectures with tradeoffs. You pick one. Prevents locking into wrong architecture mid-build.
Unfamiliar codebase from a different framework
Unfamiliar code = hidden interdependencies. Plan mode is mandatory. Claude explores, explains the architecture, proposes a feature-add strategy. Without plan mode, an unfamiliar framework is a minefield.
Code examples
# Step 1: Enter plan mode for architecture exploration
claude --plan-mode
# In session: ask an architectural question
# "Refactor this monolith into 3-4 microservices.
# Analyze dependencies first."
# Claude explores the codebase, reads key files, identifies domains,
# proposes a service boundary. NO files are edited yet.
# Step 2: Review the plan in the conversation. Ask clarifying questions:
# "Can the payment service be separate from fulfillment?"
# Claude revises the plan based on your feedback (still no file changes).
# Step 3: Approve execution
# "Looks good. Implement this plan."
# Claude now executes: creates files, modifies existing, runs tests.
# All changes logged and visible.
# Step 4 (optional): Exit plan mode for follow-up tweaks
# Quick edits after the plan can use direct execution.Looks right, isn't
Each row pairs a plausible-looking pattern with the failure it actually creates. These are the shapes exam distractors are built from.
Use plan mode for every request, including simple bugfixes.
Plan mode has overhead. Reserve for 3+ step architectural decisions. A single-file null-check should use direct execution.
Plan mode is for understanding code; skip it once you know the codebase.
Plan mode is for decision validation, not just learning. Even in familiar codebases, complex multi-file refactors benefit from blast-radius estimation.
Plan mode prevents all mistakes; use it for everything.
Plan mode is an approval gate on architecture, not a guarantee against all bugs. Its strength is catching bad-decision types; it doesn't replace testing.
If the plan is bad, execute it anyway and fix later.
Reject and iterate (zero cost). Executing a bad plan and reworking is expensive. Plan mode's value is iteration cost (milliseconds), not execution cost (hours).
Direct execution can switch to plan mode mid-work.
Plan mode is a mode, not a patch. Switching mid-work commits to prior decisions made in direct mode. Start in plan mode for complex tasks.
Side-by-side
| Aspect | Plan Mode | Direct Execution | fork_session | Subagent |
|---|---|---|---|---|
| Approval gate | Yes, explicit | None, immediate | None | None |
| Visibility of reasoning | Full plan shown | Implicit | Parallel threads | Hidden in subagent |
| Iteration cost | Milliseconds | Hours (rework) | Minutes (merge) | Hours (restart) |
| Best for | Multi-step architectural | Single-file, clear scope | Comparing approaches | Parallel research |
| Context retention | Single session, full history | Single session | Two branches | Isolated, discarded |
| File changes before approval | None | Immediate | None until merge | Only in subagent context |
Decision tree
Can you describe the desired change without exploring the codebase?
Does the change span 30+ files or involve architectural decisions?
Are there 3+ valid approaches with different tradeoffs?
Will failing mid-work be expensive?
Are you familiar with this codebase?
Question patterns
13 V2 questions wired to this concept. Tap an answer to check it instantly — you'll see whether it's right and why — then expand the full breakdown for the mental model and all four rationales.
Tap your answer to check it.
Tap your answer to check it.
Tap your answer to check it.
Tap your answer to check it.
Tap your answer to check it.
Tap your answer to check it.
7 additional questions for this concept live in the practice pillar. Take a mock exam ↗
Frequently asked
How long does plan mode take?
Can I iterate on a plan without starting over?
What if the plan is wrong and I execute anyway?
Does plan mode work for new features or only refactoring?
Is plan mode the same as code review?
Can I run plan mode locally or only in Claude Code?
What if my codebase is too large for plan mode?
Does plan mode work across git branches?
Can I use plan mode in CI/CD pipelines?
Difference between plan mode and the -p (print) flag?
-p for headless automation.Work this with your AI
Work this concept hands-on with Claude Code, Codex, or claude.ai. Copy a prompt, paste it into your assistant, and practise in tandem. Each one keeps you active (explain it back, get drilled, or build) rather than just reading.
- Drill it like the exam (scenario MCQs)Practice in the exam's scenario-MCQ format with trap awareness.
- Explain it back (Feynman)Build durable, transferable understanding of a concept you can half-state.
- Test me, adapting the difficultyActive recall practice on a concept you think you know.
- Check my prerequisites firstBefore studying a concept that keeps not sticking.
- Find the high-leverage 20%When a domain feels too big and you are short on time.