Planning

Everything so far has been about doing — making edits, running commands, setting how freely the agent acts. This chapter is about the move that comes before doing, and it’s the one that separates an operator who trusts the agent from one who gets burned by it: making Claude Code think the whole change through and hand you a plan, before it touches a single file.

You saw plan mode go by as the tight third rung on the Shift+Tab ladder — the mode that reads and proposes but changes nothing. That one-line description undersells it. Plan mode is how you point the agent at a task that’s too big, too ambiguous, or too risky to let it start editing on instinct, and get back a researched proposal you can read, argue with, and correct while it’s still cheap — before any code is written, not after you’re staring at a tangle of wrong edits.

Why plan before you build

The failure mode this fixes is specific. Hand a vague, far-reaching task to an agent in accept-edits and it will do something immediately — and confidently. If it guessed the architecture wrong, you don’t find out until twenty files have changed and the diff is too big to reason about. You’re now reviewing an implementation when you should have been reviewing a decision. Plan mode pulls that decision to the front: research first, agree on the approach, then implement against a plan you both already understand.

The rule of thumb is about the size and shape of the task:

• Small and obvious — a rename, a one-file fix, a tweak you could describe in a sentence — just let it build. Planning is overhead here.
• Big, cross-cutting, or ambiguous — touches many files, has more than one reasonable design, or you’re not sure how the existing code is wired — plan first. The riskier the change, the more the plan earns its keep.

The test: if you’d want a junior engineer to write a short design note before starting, you want plan mode.

The change we’ll follow

Same payments service from the last two chapters — but this task is a different animal. A customer got double-charged last week: their client retried a request that had actually succeeded the first time, and the service happily ran the charge twice. The fix is to make the charge endpoint idempotent — a retried request with the same key should never bill twice.

That’s not a rename. It’s a real design problem: where does the idempotency key come from, where do you store it, what happens when two identical requests race, how do you handle a key that’s seen but not yet finished. You do not want the agent guessing at all of that and editing live. So we’ll run it the right way:

• Enter plan mode and let Claude research the existing charge path without changing anything
• Read its proposal and choose how it executes — or send it back to keep refining
• Keep the plan on disk and resume it in a fresh session, so the approach survives a closed laptop or a cleared context
• Hand the whole thing to the cloud with Ultraplan when you want a richer review surface than the terminal

By the end, reaching for plan mode on anything non-trivial will be reflex — the cheap insurance you buy before letting the agent loose on a hard change.