Plan mode: making the agent read before it writes

The default failure mode of a coding agent is confident code aimed at the wrong target, not bad code. You ask for a change, the agent starts editing within thirty seconds, and by the time the diff lands it has fully committed to an approach you would have vetoed in one sentence. Claude Code ships a structural fix: plan mode. Press Shift+Tab twice and the agent loses its pen.

In plan mode the agent can read files, grep, and trace call paths, but it cannot edit, run state-changing commands, or touch your working tree. It is forced to do what a careful senior does in unfamiliar code: research first, propose second. It comes back with a plan that names the files it will touch, the approach, and the order, and you approve, redirect, or reject before a single write happens.

Reviewing at the right altitude

A fifteen-file diff is the wrong place to discover that the agent misunderstood the assignment. Diff-level review catches typos and off-by-ones; the expensive mistakes live higher up: wrong layer, wrong abstraction, wrong problem entirely. A plan is a few hundred words of pure intent, and intent is exactly what you want to review. Catching a wrong approach in a plan costs one message; catching it in a finished diff costs the afternoon.

Plan mode separates deciding from doing — and deciding is the part that deserves human attention.

This is the general principle behind human-in-the-loop design: put the checkpoint where the weight is, not where the activity is. Approving edits one by one is supervision at the wrong altitude, high effort for low signal. Approving a plan is one decision that carries most of the weight.

When planning pays

• Multi-file refactors. Anything touching more than three files has ordering and blast-radius questions worth settling up front.
• Unfamiliar territory. In a codebase the agent has not seen this session, forced reading beats eager writing every time.
• Ambiguous asks. If your own prompt contains "probably" or "something like", the plan is where that ambiguity gets resolved, cheaply.

When it's ceremony

Rename a function, bump a dependency, fix the obvious null check: if you can specify the change completely in one sentence and verify it in the diff at a glance, plan mode is pure overhead. Skip it. The mode exists to de-risk decisions, and a one-liner contains no decisions worth de-risking.

Two honest caveats. First, plans drift: approval is not a contract, and an agent that hits a surprise mid-execution will improvise, so the final diff still needs your eyes. Second, a plan is only as good as the exploration behind it: plan mode makes reading possible, not thorough, and a lazy plan approved is worse than no plan at all, because it launders a bad decision through a ritual of consent.

My rule after months of use: plan mode by default in code I do not own, direct mode in code I know cold. The tax is one approval click. The payoff is that the agent's first draft is aimed at the right target. Re-aiming is the most expensive thing you do all day.