How to use Claude Code's /plan command to get a full implementation plan before any code is written. Covers plan review, approval, iteration, and when to use plan mode vs direct execution.
Claude Code plan mode lets you review exactly what Claude intends to do before a single file is touched. It's the right tool for multi-file refactors, schema migrations, and any change where getting the sequence wrong creates rework.
# In an interactive Claude Code session:
/plan Refactor the payments module to extract a PaymentGateway interface
# Or with a full prompt:
/plan Add end-to-end tests for the /api/orders endpoint using pytest
Claude reads the relevant files, then outputs a structured plan — numbered steps, files affected, commands to run. It then stops and waits.
Plan (7 steps):
1. Read payments/processor.py to understand current interface
2. Create payments/gateway.py — abstract PaymentGateway base class with
charge(), refund(), and get_status() methods
3. Update payments/processor.py — StripeGateway(PaymentGateway) subclass,
move all Stripe-specific logic out of route handlers
4. Update payments/processor.py — PayPalGateway(PaymentGateway) subclass
5. Update routes/payments.py — replace direct Stripe calls with
gateway.charge() / gateway.refund()
6. Update tests/test_payments.py — add gateway mock fixture, update 12
existing tests to use it
7. Run: pytest tests/test_payments.py -v
Ready to proceed? (enter to confirm, or give feedback)
# Approve and execute:
proceed
# Add a constraint mid-plan:
Also update the admin/billing.py route — it calls Stripe directly too
# Redirect a step:
Step 4: use the existing PayPalProcessor class instead of creating a new one
# Cancel:
/clear
| Scenario | Use plan mode | Use direct |
|---|---|---|
| Files touched | 3+ files | 1-2 files |
| Schema changes | Yes — review before migrate | No migrations |
| API surface changes | Yes — check callers first | No public API |
| Test refactors | If mocking strategy changes | Adding tests only |
| CI / headless | Not available | Always |
| Quick fix (typo, rename) | No | Yes |
/plan Review the open diff against main and propose what needs changing
before this is mergeable: missing tests, error handling gaps,
security issues, style violations
# Claude reads git diff, produces a prioritized checklist
# You pick which items to action before approving
When running Claude Code via the SDK or as an agent, plan mode maps to the EnterPlanMode / ExitPlanMode tool calls. Your orchestrator can intercept the plan, log it, or require human sign-off before calling ExitPlanMode.
# Example: require human approval for plans touching /migrations/
# In your orchestrator hook:
if "migrations" in plan_text:
await notify_slack(f"Plan requires approval:
{plan_text}")
await wait_for_approval()
await claude.exit_plan_mode()
/plan once per phase — plan phase 1, approve, execute, then /plan phase 2For automating repetitive plans across multiple repos, see Claude Code headless mode. For controlling what Claude is allowed to do during plan execution, see Claude Code permissions.