claude code plan mode mastery

by Ray Svitla

most claude code users type a request and let the agent run. read files, edit code, run tests, fix errors — all in one shot. this works for simple tasks. for anything complex, it’s how you burn $5 on a wrong approach.

plan mode exists to prevent this. it tells claude to think and plan without touching anything. no file edits, no commands, no tool calls that change state. just analysis and strategy.

toggle it with shift+tab in the UI, or type /plan. the agent switches from “do things” to “think about things.”

why planning matters

without a plan, claude code does something reasonable with the first approach that comes to mind. it reads a few files, forms a theory, starts editing. sometimes the theory is wrong. now you have half-applied changes based on a misunderstanding, and the agent is three tool calls deep before it realizes the problem.

with a plan, the agent thinks through the approach first. it considers multiple strategies, identifies which files matter, predicts potential issues, and presents you with a coherent strategy. you review, adjust, then let it execute.

the cost difference is real: a failed approach that needs to be undone and retried costs 2-3x the tokens of a correct first approach. plan mode’s thinking tokens are cheaper than execution-and-undo tokens.

when to use plan mode

multi-file changes. anything that touches more than 3 files benefits from planning. “refactor the error handling across the API” — plan first, then execute systematically.

unfamiliar code. working in a repo you don’t know well? plan mode lets the agent analyze the architecture before making assumptions. “plan: how is authentication implemented in this project? trace the flow from request to response.”

architecture decisions. “plan: I need to add websocket support. what’s the best approach given our current Express setup?” — this produces a strategy, not a half-implemented websocket server.

risky changes. database migrations, auth changes, deployment configs. anything where a wrong move is expensive to undo.

when you’re not sure what you want. sometimes the task is vague. “plan: the checkout flow feels slow. what are the possible bottlenecks and how would you investigate each one?” — let the agent think before it starts profiling random endpoints.

when NOT to use plan mode

simple, clear tasks. “add a createdAt field to the user model” — just do it. planning a one-line change is overhead.

tasks you’ve done before. if you know exactly what needs to happen and where, skip the plan. “add rate limiting to the /api/upload endpoint using express-rate-limit” — there’s nothing to plan.

urgent fixes. production is down. you know the fix. type the instruction and let it execute.

the rule: if you can describe the exact changes in your head, skip the plan. if there’s uncertainty about approach, scope, or impact — plan first.

tactical patterns

the explore-plan-execute cycle

1. "plan: I need to add email notifications when orders ship. 
    look at the existing code and tell me where this should go."
2. [review the plan, adjust if needed]
3. [switch off plan mode]
4. "execute the plan we discussed. start with step 1."

this three-phase approach — explore, plan, execute — keeps the agent focused. each phase has a clear purpose and the agent doesn’t drift.

the architecture review

"plan: review the database schema in prisma/schema.prisma 
and the API routes in src/api/. identify any inconsistencies 
between the schema and the API types."

pure analysis. the agent reads files and reports findings without changing anything. great for code review, audit, and understanding.

the multi-option plan

"plan: I need to add search to the product catalog. 
give me 3 approaches ordered by implementation complexity. 
for each: what it takes, what it costs, what it doesn't cover."

forcing multiple options prevents the agent from committing to the first idea. you get to choose the approach, not accept whatever the agent defaults to.

plan + ultrathink

for genuinely complex decisions:

"plan, ultrathink: we need to migrate from monolith to 
microservices. current architecture is [description]. 
what's the migration strategy?"

plan mode keeps the agent from executing prematurely. ultrathink gives it the reasoning budget to think deeply. the combination is expensive per-interaction but cheap compared to executing a bad migration strategy.

the plan as artifact

a good plan from claude code is worth saving. copy it to a markdown file, a github issue, or your project docs. it’s not just an intermediate step — it’s documentation of the reasoning behind your approach.

"plan: redesign the auth system for multi-tenancy. 
after planning, write the plan to docs/auth-migration-plan.md"

now you have a document you can review with your team, iterate on, and reference during implementation.

common mistakes

planning everything. if you plan every single task, you’re adding overhead to trivial work. plan mode is for uncertainty, not ritual.

ignoring the plan. asking for a plan then immediately saying “ok just do it” without reading the plan. the plan might identify problems you haven’t considered. read it.

planning too broadly. “plan: build the entire application” — the plan will be generic and useless. scope it to specific features or changes.

never leaving plan mode. I’ve seen people stay in plan mode for an entire session, generating plans but never executing. at some point you have to build the thing.

the mental model

plan mode is thinking time. execution is doing time. separating them is the same discipline that makes architects draw before builders build, that makes writers outline before writing, that makes generals strategize before fighting.

it’s not a claude code feature. it’s a workflow discipline that claude code makes easy to practice.

→ ultrathink — deep reasoning for complex plans → context optimization — manage tokens across plan + execute → reduce claude code costs — plan mode as a cost strategy

Ray Svitla stay evolving