Claude Code Plan Mode: A Step-by-Step Workflow

The worst time to discover Claude misunderstood your refactor is after it has rewritten eleven files. By then you're not reviewing code, you're doing forensics on a diff you never agreed to. The fix is a plan-mode workflow where the plan itself is the thing you review and approve — like reading a PR before you merge, not after. This walkthrough covers plan mode as a real verify-gate: how to trigger it, what a good plan looks like, how to iterate, how the approval handoff works, and how to bail back mid-task when things drift.

What plan mode actually is (and isn't)

Plan mode is not the prompt "think before you code." That phrasing is advisory — Claude can read it and edit anyway. Plan mode is a tool-enforced read-only permission mode. In it, Claude reads files and runs read-only exploration commands, but it cannot edit source, run state-changing shell commands, or commit until you approve a plan. The gate is enforced by the harness, not by Claude's good intentions.

One clarification that saves confusion: plan mode stops editing, not prompting. Read-only commands that would normally ask permission still ask, exactly as they do in default mode. Plan mode narrows what can happen; it doesn't make the session quieter.

Three ways to trigger plan mode

Pick whichever fits the moment.

1. Mid-session toggle. Press Shift+Tab to cycle modes: default → acceptEdits → plan. The status bar shows the active mode, so glance there to confirm you've landed on plan.
2. One prompt. Prefix the request with /plan:

   /plan refactor the auth middleware to support refresh tokens
   

3. At startup. Launch the whole session gated:

   claude --permission-mode plan
   

One Windows gotcha: on some terminals Shift+Tab only toggles Normal/Auto and skips plan entirely. Community reports mention a fallback key, but builds differ — watch your own status bar to confirm the cycle rather than trusting a specific keystroke.

Make plan mode the default for risky repos

For production-touching or shared-infrastructure projects, don't rely on remembering to gate. Set it in .claude/settings.json:

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

Now every session in that repo starts read-only. Nobody forgets the gate, because the gate is the default.

What a good plan looks like

This is the heart of the workflow: you are reviewing an artifact, so approve only a plan that earns it. A strong plan:

• Names the exact files it will touch — not "the auth layer," but src/middleware/auth.ts and the specific modules around it.
• States the order of operations so you can see the sequence, not just a pile of changes.
• Calls out the dangerous implications — schema changes, migrations, anything that widens the security surface.
• Lists what it will NOT do, so scope is bounded explicitly.
• Ends with a verification step — the exact tests or commands that prove the change worked.

If the plan is vague about which files, or it skips the verification step, that's your signal to keep iterating. Don't approve a plan you couldn't hand to another engineer and expect them to execute without questions.

Iterating on the plan before any code

You have two levers, and neither writes a line of source.

Lever one — reply with feedback. Tell Claude what's missing and it revises the numbered plan in place. Three prompts worth keeping on hand:

Before listing steps, tell me the 2 riskiest assumptions in this plan.

List every file you'll modify and why; flag any you're unsure about.

Add a rollback step and the exact test command that proves this works.

Lever two — edit the plan directly. Press Ctrl+G to open the proposed plan in your $EDITOR. Tighten it, delete a step, add a constraint, save, and Claude proceeds from your edited version. This is the fastest way to cut a step you know is wrong without negotiating it away in chat.

Iterate as many rounds as it takes. Re-planning is free; bad edits are not.

The approval handoff

When the plan is ready, Claude presents an approval menu. The options you'll typically see:

• Approve and start in auto mode — Claude runs autonomously after approval (auto mode requires Claude Code v2.1.83+).
• Approve and accept edits — switches to acceptEdits; changes apply without per-edit prompts.
• Approve and review each edit manually — you confirm every edit as it happens.
• Keep planning with feedback — back to iteration.
• Refine with Ultraplan — hand the plan to a heavier cloud planner (more below).

Approving exits plan mode, switches the session into whichever mode you chose, and starts editing. It also auto-names the session from the plan content, unless you already named it with --name or /rename. If you have showClearContextOnPlanAccept enabled, each approve option also offers to clear the planning context first.

For big changes, don't pick auto. Choose "review each edit manually," or take acceptEdits and do a deliberate git diff pass afterward. The whole point of the gate is to keep a human in the loop where review is cheapest — at the edit, not after the commit.

Bailing back to plan mode mid-task

Even an approved plan can drift. The diff surprises you, scope creeps, Claude starts touching a file that wasn't on the list. Re-gate immediately:

1. Stop the run.
2. Press Shift+Tab to cycle back into plan, or prefix your next message with /plan to force the next turn through planning.
3. Tell it what changed and ask for a fresh plan.

Copy-paste:

Stop. Don't edit anything else. /plan re-plan the remaining work given what you just changed in X.

This is the core verify-gate discipline. Re-planning costs a minute. Unwinding a tangle of half-correct edits costs an afternoon.

When to use it — and when to skip

Reach for plan mode when a change is:

• multi-file (a useful rule of thumb: 3+ files),
• refactor-shaped,
• schema- or migration-touching,
• security-sensitive, or
• anywhere near production.

Skip it for trivial mechanical one-liners — fixing a typo, bumping a version string — where the gate is pure friction. Judgment, not dogma.

Scaling up: Ultraplan for the hardest changes

For changes too big to plan in a single terminal pass, Anthropic shipped Ultraplan in April 2026 as a research preview. It offloads planning to a cloud session that can think for a long stretch, then hands you a browser review UI: highlight a passage, leave an inline comment, iterate across as many rounds as you want, and finally choose to execute in the cloud or send the polished plan back to your terminal.

The cost-aware version of this: draft locally with plan mode first, confirm the direction is right, then pick "Refine with Ultraplan" for the heavy polish. Starting in the cloud every time burns quota you didn't need to spend.

Plan mode in the bigger loop

Plan mode is one stage in the canonical Explore → Plan → Code → Commit loop. On a large codebase, push the Explore stage onto a subagent: let it do the read-heavy research and return a summary, so your main context stays lean and you plan from a tight brief instead of a flooded window.

The mental model that makes all of this click: the plan is a pull request for intent. You read it, you push back, you approve — and only then does anyone write code. Build that one habit and "the agent went off and did something weird" mostly stops happening.