# Plan Mode > 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. Full content in SCRUM-21 follow-up. **Domain:** D3 · Agent Operations (20% of CCA-F exam) **Canonical:** https://claudearchitectcertification.com/concepts/plan-mode **Last reviewed:** 2026-05-04 ## Quick stats - **Trigger threshold:** 3+ steps - **Exam domain:** D3 - **Decision factor:** blast radius - **Coverage tier:** B - **Skip case:** trivial edit ## 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 in production ### 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 ### Plan mode workflow (CLI + programmatic) **CLI:** ```bash # 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. ``` > CLI plan mode separates exploration (zero file changes) from execution (approval-gated modifications). **TypeScript (programmatic):** ```typescript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function generateArchitecturePlan(request: string, codebaseContext: string) { const resp = await client.messages.create({ model: "claude-opus-4-5", max_tokens: 4096, system: `Analyze a codebase. Do NOT modify files. Propose 2-3 approaches with tradeoffs. Format: ## Current State [summary] ## Proposed Options ### Option A: [name] - Tradeoffs, Risks ### Option B: [name] - Tradeoffs, Risks ## Recommendation [which and why]`, messages: [{ role: "user", content: `Request: ${request}\n\nCodebase:\n${codebaseContext}`, }], }); const plan = resp.content .filter((b): b is Anthropic.TextBlock => b.type === "text") .map(b => b.text).join(""); console.log("=== PLAN (NO CHANGES YET) ===\n", plan); console.log("\nReview above. Approve or request changes.\n"); return plan; } ``` > Programmatic plan: separate analysis from execution. Human approves before files are modified. ## Looks-right vs actually-wrong | Looks right | Actually wrong | |---|---| | 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. | ## Comparison | 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 1. **Can you describe the desired change without exploring the codebase?** - **Yes:** Direct execution. Save time; plan mode has overhead. - **No:** Plan mode. Exploration validates the approach before committing. 2. **Does the change span 30+ files or involve architectural decisions?** - **Yes:** Plan mode is mandatory. Blast radius too large to wing it. - **No:** Direct execution acceptable if scope is clear. 3. **Are there 3+ valid approaches with different tradeoffs?** - **Yes:** Plan mode. Proposals clarify the tradeoff space. - **No:** Direct execution if right approach is obvious. 4. **Will failing mid-work be expensive?** - **Yes:** Plan mode. Upfront approval saves rework. - **No:** Direct execution. Cost of failure is acceptable. 5. **Are you familiar with this codebase?** - **Yes:** Decide based on other factors. - **No:** Plan mode always. Unfamiliar code means hidden interdependencies. ## Exam-pattern questions ### Q1. Single-file null-check: should you use plan mode? No. Plan mode has overhead. Reserve for 3+ step architectural decisions where there are multiple valid approaches and rework would be expensive. A clear bug-fix uses direct execution. ### Q2. 30-file refactor: direct execution or plan mode? Plan mode is mandatory. Blast radius too large to wing it. Without upfront analysis, you commit to a suboptimal architecture mid-refactor and rework hours of work. Plan mode's iteration cost (milliseconds) replaces rework cost (hours). ### Q3. The plan looks bad. Should you execute and fix the result later? Reject the plan and iterate (zero cost, same session). Tell Claude what's wrong; Claude revises. Executing a bad plan and reworking is expensive. Plan mode's value is in iteration cost being free, not in execution being safe. ### Q4. You're working in an unfamiliar codebase (different framework, different conventions). Plan mode optional? Mandatory. Unfamiliar code means hidden interdependencies. Plan mode makes them visible: Claude explores, identifies risks, proposes a strategy respecting framework conventions. Direct execution in unfamiliar code is a minefield. ### Q5. Can you switch from direct execution to plan mode mid-task? Plan mode is a mode, not a patch. Switching mid-work commits to prior decisions made in direct mode. For complex tasks, start in plan mode. Switching late captures only future steps; the architectural commitments are already made. ### Q6. Plan mode in CI/CD pipelines: viable? No. Plan mode requires human approval (a decision gate). Only for interactive development. For automated CI/CD refactors, use direct execution with comprehensive testing. ### Q7. Plan mode and the -p flag: same purpose? Different. -p makes Claude Code non-interactive (CI/CD). Plan mode is interactive approval-gated. Different tools for different goals: plan mode for refactoring, -p for headless automation. ### Q8. Codebase is too large for plan mode to read entirely. How do you scope? Scope the request. Instead of "refactor the whole monolith," say "refactor the customer domain into a microservice." Plan mode explores only the relevant parts. For massive codebases, pre-summarize architecture in ARCHITECTURE.md. ## FAQ ### Q1. How long does plan mode take? Plan generation: 2-5 min for a 50K-line codebase. Execution: 5-15 min. Total ~10-20 min. Direct execution often takes 20-30 min plus rework time when the approach proves suboptimal. ### Q2. Can I iterate on a plan without starting over? Yes. Plan mode keeps everything in one session. Reply with feedback, Claude revises. No cost except token budget. ### Q3. What if the plan is wrong and I execute anyway? You're responsible for approving. Reject the plan and iterate before execution, when iteration is free. ### Q4. Does plan mode work for new features or only refactoring? Any task with ambiguous architecture: features, library upgrades, data model changes. Anytime there are 3+ valid approaches. ### Q5. Is plan mode the same as code review? No. Code review happens after writing; plan mode validates before writing. Plan mode prevents architecturally-wrong code from being written. ### Q6. Can I run plan mode locally or only in Claude Code? Plan mode is a Claude Code feature. The API equivalent is a separate analyze-before-execute pattern in your own code. ### Q7. What if my codebase is too large for plan mode? Scope the request. "Refactor the customer domain into a microservice" not "refactor the whole monolith". Plan mode explores only the relevant parts. ### Q8. Does plan mode work across git branches? Plan on the current branch. For cross-branch coordination, plan on main, approve, execute on a feature branch. Plan mode doesn't manage branch strategy; git does. ### Q9. Can I use plan mode in CI/CD pipelines? No. Plan mode requires human approval. Only for interactive development. For automated CI/CD refactors, use direct execution with comprehensive testing. ### Q10. Difference between plan mode and the -p (print) flag? -p is non-interactive (CI/CD). Plan mode is interactive approval-gated. Different tools: plan mode for refactoring, -p for headless automation. --- **Source:** https://claudearchitectcertification.com/concepts/plan-mode **Vault sources:** ACP-T03 §4.3 plan mode; GAI-K04 §15 decision table; ASC-A01 Course 4 **Last reviewed:** 2026-05-04 **Evidence tiers** — 🟢 official Anthropic doc / API contract · 🟡 partial doc / inferred · 🟠 community-derived · 🔴 disputed.