Plan mode in Claude Code — when to turn it on, when not to bother

Plan mode is a separate Claude Code mode where the agent doesn't modify files, it only talks, explores code and writes a plan. The last few weeks taught me when this pays off and when it just costs time. Concretes.

Anatomy of a good plan

Plan mode forces five phases:

1. Initial understanding, explore agents build a code map
2. Design, Plan agent (or the user) designs the solution
3. Review, alignment check with intent
4. Final plan, written to the plan file (the only thing the agent can edit)
5. ExitPlanMode, signal the plan is ready for approval

A plan is ~150-300 lines of markdown. Sections: Context, Phases, Critical Files, Risks. Same format every time, easy to read.

When I TURN IT ON

Three task shapes where this pays off:

1. A networked change — many files, many dependencies

A refactor touching 10+ files. Without a plan the agent starts from one file and drifts. With a plan it has a list and an order.

Example from this week: adding i18n (PL/EN) to the blog. Files affected:

• 1 loader (signature extension)
• 4 components (locale prop)
• 3 new components (BlogIndex, PostDetail, LocaleSwitch)
• 5 new routing files under /en/blog/
• sitemap

Without a plan: the agent would start from app/blog/page.tsx, only touch PL, leave EN for later. With a plan: did git mv → types → loader → components → routes in one coherent wave.

2. Unclear scope

"Help me with X" where X has multiple interpretations. Plan mode forces asking questions before writing code. Win: I don't write two versions because I misread.

3. Something heavily destructive

Data migration, schema change, mass git changes. Plan mode has built-in guards (can't modify files, can't run destructive commands). An extra safety layer before the model does anything.

When I DO NOT turn it on

Four situations where plan mode slows me down:

1. Typo / small fix

Changing 1-2 lines in a single file. Plan mode forces a ceremony that costs 5 minutes. A regular session: 30 seconds. Disproportionate.

2. "What is this code" exploration

When I just want to understand. Plan mode wants to produce a plan at the end. I want a dialogue. I do this without plan mode and ask ad-hoc.

3. UI iteration

Creative work: "change the button color, see, change again". Plan mode kills iteration; every change is a new plan. For UI I use the normal mode with a dev server.

4. Something I did identically yesterday

Repetitive tasks. They live in skills / hooks / scripts. Plan mode reinvents the wheel.

Questions that improve a plan

Plan mode lets you ask the user questions. Key thing: ask about real forks, not about approval. Examples:

❌ "Do you like the plan?", that's what ExitPlanMode does

❌ "Should I do this in TypeScript?", context already says (.ts files in repo)

✅ "PL+EN dual or PL only?", real fork, changes 5 files

✅ "Caching: in-memory or Redis?", different deploy implications

✅ "Publishing mechanism: draft queue or live AI?", different risks

A question should have 2-4 options, mutually exclusive, with consequences. AskUserQuestion in a plan is the difference between "talking to an agent" and "designing together."

Plan mode pitfalls

Three I caught:

1. Plan agent designs from scratch, not reuse. Early plans suggested writing functions that already existed in lib/. Lesson: in the Plan agent prompt I include "actively search for existing utilities to reuse". Helps.

2. Explore agents read snippets, not whole files. They can miss something below their window. Lesson: if a file is long and central, I read it myself before accepting the plan.

3. The plan goes stale. When implementation takes > 2 hours, the plan drifts from reality. Lesson: I pause, update the plan file, continue.

ExitPlanMode — what it actually does

The final command. Signals "plan ready". At this point:

• the plan is shown to the user
• the user accepts or asks for changes
• after acceptance the agent leaves plan mode and can edit files

One subtlety: in ExitPlanMode you can declare allowedPrompts, a list of action categories the agent will perform. This pre-empts permission prompts. Reduces friction in execution.

// Example declaration
{
  allowedPrompts: [
    { tool: "Bash", prompt: "git mv, git add, git commit in this repo" },
    { tool: "Bash", prompt: "npm run build" },
    { tool: "Bash", prompt: "docker compose up -d --build" }
  ]
}

TL;DR

Use plan mode when: networked change, unclear scope, destructive operation.

Skip plan mode when: < 5-minute fix, exploration, UI iteration, repetitive task.

Ad-hoc questions about real forks. Plan as a readable artifact, not a ceremony.

Plan mode isn't magic. It's enforced "think before you write". The enforcement is worth its cost only when the task is big enough that without it we'd run into trouble. Otherwise it's overhead.