Plan Mode — Review the Approach Before a Single Line Changes

Mastering Claude Code — Tips & Tricks Chapter: Level 1 (Fluent) › 1.3 Plan Mode The cheapest insurance policy in Claude Code.

Claude is fast. That's the problem. On a nontrivial task it can confidently edit eight files in the wrong direction before you've finished reading its first sentence — and now you're reverting a half-done change instead of shipping. Plan mode fixes this by splitting the work in two: first Claude researches and proposes, you review and correct, and only then does it build. You catch the wrong approach when it costs one message, not one hour.

The One Idea

Separate "what's the plan?" from "do it." Approve the approach while it's still just words — because words are free to change and code is not.

What plan mode actually is

Plan mode is a read-only mode. While it's on, Claude can explore your codebase — read files, search, trace call paths — but it physically cannot edit, write, or run mutating commands. When it has a plan, it presents it and waits for your approval before touching anything.

That "physically cannot" is the whole point. Telling Claude "make a plan first" is a polite request it might race past. Plan mode is a guardrail — it removes the ability to act, so the plan is guaranteed to come before the code.

How to enter it

• Toggle mid-session: press Shift+Tab to cycle permission modes until you see plan mode on (the mode indicator shows ⏸ plan mode).
• Start a session in it: claude --permission-mode plan.

When Claude finishes researching, it surfaces the plan in an approval prompt. You then:

• Approve → Claude exits plan mode and executes exactly what you agreed to.
• Request changes → refine the plan; still zero code written.
• Reject → nothing happened. No cleanup, no revert.

Tip: in recent versions you can open the plan in your editor (Ctrl+G) and edit it directly before approving — often faster than a "request changes" round-trip when you just want to tweak a step or two.

Where it fits the core loop

The professional loop is explore → plan → code → verify. Plan mode owns the first two phases safely:

┌─ plan mode (read-only) ─┐        ┌─ normal mode ─┐
│  explore  →  plan        │  →✓→  │ code → verify │
└──────────────────────────┘  ↑    └───────────────┘
                          you approve here

The approval gate is the seam. Everything before it is reversible by definition.

Before / After: the payoff demo

Task: "refactor auth to use refresh-token rotation."

Without plan mode — Claude starts editing immediately:

> refactor auth to use refresh-token rotation

Editing src/auth/login.ts...
Editing src/auth/session.ts...
Editing src/middleware/auth.ts...
Editing 5 more files...

# ...halfway through you notice it's storing refresh tokens in localStorage
# (should be httpOnly cookies) and touched files you didn't want changed.
# Now you revert 8 half-edited files and start over.

With plan mode — Claude proposes first:

> [⏸ plan mode] refactor auth to use refresh-token rotation

PLAN
 1. Store refresh token in an httpOnly, Secure cookie (not localStorage).
 2. Add POST /auth/refresh that rotates + invalidates the old token.
 3. Files to change: auth/session.ts, auth/refresh.controller.ts (new),
    middleware/auth.ts.  (login.ts unchanged.)
 4. Risk: existing sessions invalidated → note migration.
 5. Tests: add refresh-rotation + reuse-detection cases.

Approve this plan?
> No — token store is right, but keep the old refresh endpoint for 1 release
  for backward compat.

Updated plan: adds a deprecation window on the old endpoint. Approve?
> Yes

You corrected a security mistake and a scope mistake before a single file changed. That's the difference between "fast" and "fast and right."

When to use it (and when to skip)

Use plan mode for:

• Anything touching more than a file or two.
• Unfamiliar codebases — let Claude map it before it edits it.
• Risky or hard-to-reverse changes (auth, migrations, payments, deletes).
• Tasks where the approach is genuinely uncertain and you want options.

Skip it for:

• One-line fixes, typos, a rename you've already decided.
• Tasks where planning costs more than just doing it.

Habit to build: if your gut says "this is more than a quick edit," hit Shift+Tab first. It's a two-second reflex that saves hours.

Getting a great plan (not just any plan)

A vague request gets a vague plan. Ask for structure. A strong plan request names what you want the plan to contain:

Plan this. In the plan, include:
- the exact files you'll change (and confirm what you WON'T touch),
- the approach and why, plus one alternative you rejected,
- the order of steps,
- risks / anything that could break existing behavior,
- the test strategy,
- explicitly, what is out of scope.
Don't write any code yet.

(That prompt ships as a copy-paste file in the artifact below.)

Power tips:

• Point at the anchor. "Follow the conventions in CLAUDE.md" — plan mode respects your constitution (Chapter 1.1), so the plan comes back on-style.
• Ask for options. "Give me two approaches with trade-offs" turns plan mode into a design tool, not just a to-do list.
• Iterate freely. Rejecting a plan is free. Push back until it's right — that's the entire value.

Review the plan like a reviewer

The plan is a mini pull request. Before you approve, check:

• Intent — does it solve what you actually asked, not an adjacent thing?
• Scope — is it minimal? Any drive-by changes to cut?
• Files — the right ones, and nothing surprising?
• Risk — does it name what could break, and handle it?
• Tests — is "done" actually verifiable?

If any answer is shaky, request changes. Approving a bad plan just moves the problem downstream. (Full checklist in the artifact.)

The caveat

Plan mode is a thinking gate, not a rubber stamp. Its value is your review — if you approve every plan without reading it, you've added a step and kept the risk. And don't over-apply it: gating a typo fix behind a plan is friction for friction's sake. The official best practices put it plainly: if you can describe the diff in one sentence, skip plan mode — planning overhead isn't free. Use it where the approach matters.

Downloadable: the Plan Mode Playbook

In ../artifacts/plan-mode-playbook/:

Use it in one line: press Shift+Tab, paste plan-request-template.md, review against plan-review-checklist.md, approve.