Guides

Using plan mode in Claude Code for large changes

The expensive mistake with a big change is not a bad line of code, it's a wrong approach discovered after forty files were edited. Plan mode makes Claude read the code and propose an approach first, so you can correct the direction while nothing has been touched.

What plan mode does

In plan mode Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source. Edits stay blocked until you approve the plan. It is one of Claude Code's permission modes, alongside default and acceptEdits; see permissions without clicking Allow 100 times for how the modes compare.

Three ways to enter it

Method	How
Mid-session	Press Shift+Tab until the status bar shows ⏸ plan mode on
One prompt only	Prefix the prompt with /plan
At launch	claude --permission-mode plan

Press Shift+Tab again to leave plan mode without approving anything. The exact mode cycle depends on your version and which optional modes are enabled, so watch the status bar rather than counting presses.

Write a prompt that produces a useful plan

"Plan the migration" gets a vague outline. Name the goal, the constraints, and what the plan must include:

/plan Replace our custom date helpers in src/utils/date.ts with date-fns.

Constraints: no behavior changes, no new dependencies besides date-fns,
public function signatures stay the same.

In the plan, list: every file that imports the helpers, the order you'd
change them in, how we verify each step (which tests or commands), and
anything risky or ambiguous you want me to decide before you start.

The last line matters most. Asking Claude to surface open questions turns the plan into a short review conversation instead of a document you skim and approve.

Review and approve the plan

When the plan is ready, Claude presents it and asks how to proceed. The options are:

• Yes, and use auto mode: approve and start editing in auto mode. If auto mode isn't available to your session, this option reads Yes, auto-accept edits.
• Yes, manually approve edits: approve, then review each edit individually.
• No, keep planning: stay in plan mode and tell Claude what to change.

For a large or hard-to-undo change, "manually approve edits" for the first few steps is a reasonable way to confirm the plan is being followed before you loosen oversight. Approving exits plan mode; to plan again, press Shift+Tab or use /plan on the next prompt.

Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds. Deleting a step you don't want is faster than arguing it away in chat.

A workflow for large changes

• Plan in small pieces. If the plan lists more than a handful of steps, tell Claude to plan only the first mergeable slice. Large plans drift as the code changes underneath them.
• Ask for verification per step. Each step should name the test or command that proves it worked. See refactoring a large codebase for characterization tests and worktree isolation.
• Keep the plan visible. After approval, ask Claude to work step by step and stop after each one, so the approved plan stays the reference.
• Re-plan when reality diverges. If a step turns up something the plan didn't expect, switch back to plan mode instead of letting Claude improvise across many files.

Make plan mode the default for a project

For a repository where every change deserves review, such as payments, auth or migrations, set the default mode in the project's .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Terminal sessions in that project then start in plan mode. The VS Code extension doesn't read project settings for the starting mode; set claudeCode.initialPermissionMode to plan in your VS Code user settings instead. More on settings files in settings.json explained.

Things to know

• Plan mode is not a sandbox. Claude can run shell commands while exploring. Which of those prompt you depends on your session and settings, so don't treat plan mode as a guarantee that nothing executes.
• Bypass permissions weakens it. In interactive terminal sessions where bypass permissions are available, Claude is still instructed to plan without editing, but Claude Code doesn't enforce the edit block. Plan mode keeps its blocks in non-interactive -p runs and in the VS Code chat panel.
• Plans are saved as files. Claude Code writes plan files under ~/.claude/plans/, or the directory set by the plansDirectory setting.

If you want a hard guardrail on top of the plan, such as blocking edits to specific paths no matter what mode you're in, a PreToolUse hook does that. The free hook builder generates one without hand-writing the script.