claudekit / guides / plan-mode
[ Guide · Practical · 8 min ]

Using Plan Mode Well

published · updated

A practical guide to when and how to use Claude's plan mode. Walks through what to review in a plan and how to handle changes mid-flight on high-impact work.

Why plan mode

Jumping straight into complex work risks:

  • Going far in the wrong direction before you can stop it
  • Hiding the change scope from you until after the fact
  • Magnifying losses when an assumption is wrong

Plan mode is the gate before any code change — it shows you the plan, you approve, then it runs. Slightly slower upfront, much higher success rate on complex work.

Enter and exit

MethodWhat it does
Shift+TabCycles permission modes: default → acceptEdits → plan. If bypass permissions or auto mode is available, they follow plan in the cycle.
/plan prefixPrefix a single prompt with /plan to enter plan mode. Add a description, like /plan fix the auth bug, to start planning right away.
claude --permission-mode planStarts the session in plan mode.
permissions.defaultMode: "plan"In .claude/settings.json, makes plan mode the default for the project’s terminal sessions. In the VS Code extension, set claudeCode.initialPermissionMode to plan in your user settings instead.

While plan mode is on, the status bar shows ⏸ plan mode on. Press Shift+Tab again to leave plan mode without approving a plan.

What a good plan contains

Claude’s plan typically includes:

  1. Context — why the change is needed
  2. Files to modify — exact paths
  3. What changes per file — function or section level
  4. Assumptions — what state or environment is assumed
  5. Verification — build, tests, manual checks

If a section is empty, ask Claude to fill it. If an assumption is wrong, correct it and ask for a revised plan.

Approving the plan

When the plan is ready, Claude presents it and asks how to proceed:

OptionWhat it does
Yes, and use auto modeApprove and start in auto mode. If auto mode isn’t available to your session, this option reads Yes, auto-accept edits.
Yes, manually approve editsApprove and review each edit individually.
No, keep planningStay in plan mode and tell Claude what to change.

Approving a plan exits plan mode and switches the session to the permission mode the option describes. Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds.

When to use it

Good fitSkip it
New feature (3+ files)Single typo fix
RefactorSingle-file rename
DB migrationAdding a console.log
Dependency changeComment edits
API signature changeObvious bug fixed in seconds

What to review

  • Missing files — affected files Claude didn’t catch
  • Wrong assumptions — “assumes X exists” — does it?
  • Irreversibility cost — migrations, deletions, data changes
  • Test plan — how the change will be verified after the fact

Mid-execution adjustments

When execution needs to deviate from the plan, cycle back to plan mode with Shift+Tab, or prefix your next prompt with /plan, get a revised plan, then resume.

Pairs with

  • CLAUDE.md — “Use plan mode for complex changes” as a rule encourages Claude to suggest it.
  • Superpowers — the superpowers:writing-plans and superpowers:executing-plans skills save plans as files for larger work. (The legacy /write-plan and /execute-plan commands were removed in Superpowers v5.1.0.)
  • claude-mem — preserve plans and progress across sessions.

Common misconceptions

  • “Plan mode means no edits at all” — mostly. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source until you approve. When auto mode is available, the classifier reviews shell commands instead of prompting you. The exception: in interactive terminal sessions with bypass permissions available, plan mode won’t ask before most edits or commands.
  • “Approval guarantees execution exactly as planned” — usually yes, but Claude stops if it hits an issue.
  • “Plan mode is always better” — for trivial work it’s overhead. Use it when impact is broad.

Next steps

§ 11

Frequently Asked Questions

frequently asked
§ 11.1
What is plan mode?
Plan mode tells Claude to research and propose changes without making them, and waits for your approval. It prevents going far in the wrong direction on complex or high-impact work.
§ 11.2
How do I enter it?
Press Shift+Tab to cycle permission modes until you reach plan, or prefix a single prompt with `/plan`. To start in plan mode, run `claude --permission-mode plan` or set `permissions.defaultMode` to `plan` in `.claude/settings.json`.
§ 11.3
When should I use it?
Use it for multi-file refactors, new feature implementation, DB migrations, or dependency changes — anything with broad impact. Skip it for trivial fixes where the planning overhead outweighs the benefit.
§ 11.4
How should I review the plan?
Check the change scope (which files and functions), the assumptions, the irreversible risks, and the verification steps. If a scenario is missing, choose No, keep planning and tell Claude what to change.
§ 11.5
What if I need to replan after approving?
Approving a plan exits plan mode and switches the session to the permission mode you picked, so Claude starts editing. To plan again, cycle back to plan mode with Shift+Tab, or prefix your next prompt with `/plan`.