Plan-Mode Thinking

Hand an agent a task like “clean up the retry logic in the payment client” and a capable harness will start immediately — reading a file, then another, then opening an edit. Three files and a dozen tool calls later, the shape of the problem becomes clearer, and it is not the shape the agent guessed at. The retry logic was fine; the real bug lived one layer up, in the queue consumer that called it. By now the working tree has eleven changed files, two of which happen to fix something real as a side effect, tangled in with nine that do not need to exist.

Finding that out in code review, an hour later, is a different problem than finding it out before a single line changed. The second version costs a conversation. The first costs an archaeology project: which of these eleven files were actually necessary, which incidental fixes get lost if the branch is reverted wholesale, and whether it is faster to sort the good from the bad by hand or start over. This is the failure plan-mode exists to prevent — not by making an agent smarter, but by making the moment it commits to an approach visible and reversible before that approach produces a single diff.

What plan mode actually restricts

Plan mode is not a metaphor for careful thinking; it is a harness-native primitive — a specific, documented mode that most modern coding agents now support directly. In Claude Code, entering it restricts the session to read-only operations: reading files, searching, running shell commands to explore. File edits stay blocked, exactly as they would in the harness’s default manual mode. What plan mode adds is a deliverable. Instead of trailing off into edits once it believes it understands the problem, the agent is expected to produce a plan and present it for explicit review. From that review, a person can approve into an execution mode with the plan as the agent’s brief, send it back with corrections before any code exists to revert, or open the plan in a text editor and rewrite it by hand.

The exact name and keybinding vary by harness, but the shape does not: a restricted phase that produces a proposal instead of a diff, and an explicit human transition into a phase where that proposal becomes the brief for actual edits. It is the same separation of concerns spec-driven development enforces across a whole project — specify what, then plan how, then implement — collapsed into a single session with no ceremony beyond a pause and a review. Nothing about the mechanism requires a particularly capable model; it requires only that the harness enforce the boundary mechanically, so “stay in research mode” is never a request the agent can quietly ignore under the pressure of a task that looks solvable.

Why mid-execution discovery costs more

Anthropic’s own guidance for the tool states the risk plainly: letting an agent jump straight to coding can produce code that solves the wrong problem. That risk is not really about code quality — a wrong approach can be executed cleanly. It is about the shape of the failure once it is caught. Software engineering has argued for decades, in various forms, that catching a mistake earlier costs less than catching it later; Barry Boehm’s escalating cost-of-change curve is the best-known version of that claim, built from waterfall-era project data at TRW and IBM. The exact multiplier has not aged well. Laurent Bossavit’s critique in The Leprechauns of Software Engineering found the empirical basis of Boehm’s curve thinner than the folklore built on top of it, and whether the curve holds at all under modern, iterative practice remains a live, unresolved argument among practitioners rather than a settled fact.

An AI session does not need Boehm’s number to make a narrower version of the same point. A false start inside one continuous editing session does not produce a clean, isolatable mistake — it produces edits interleaved with whatever else the agent did while pursuing the wrong approach, some of it valid. Reverting cleanly means separating the two after the fact, which is slower and riskier than reviewing a plan that never became code at all. Reviewing a plan is also cheap in a way reviewing a finished wrong turn is not: a plan stays roughly the size of the reasoning behind a change, no matter how large that change eventually becomes, while reviewing an executed mistake means reading the diff and reconstructing what should have happened instead. The cost asymmetry plan-mode trades on is not abstract; it is the difference between deleting a paragraph and untangling a paragraph from the one next to it.

Plan-mode thinking

Call the discipline plan-mode thinking: separating the decision about approach from the act of making changes, enforced at the smallest useful grain a single session can carry. Earlier chapters in this volume followed spec-driven development as an external artifact — a specification document written, reviewed, and iterated before a coding agent ever runs, in the constitution-specify-plan-tasks-implement shape GitHub’s spec-kit popularized. Plan-mode thinking is the same core insight, decide then do, compressed into a single sitting, with no document surviving the session and no ceremony beyond a pause and a review. It is spec-driven development’s cheapest possible instantiation, chosen when a lighter touch fits the size of the problem.

Where the tension this volume named between living specs and static plans plays out over a project’s lifetime, a plan-mode proposal is disposable by design. It exists to be approved or rejected within minutes, not maintained, versioned, or referenced again once the session ends. That disposability is the point: the mechanism is worth using precisely because it costs almost nothing to invoke and almost nothing to discard.

When to plan, when planning is waste

Blanket advice in either direction is wrong. Defaulting every task through a proposal-and-approval cycle turns a safety mechanism into ceremony; skipping it on every task reintroduces the exact failure it exists to prevent. The dividing line is not the tool, it is the task: how ambiguous the right approach actually is, how expensive a wrong one would be to unwind, and how much context the agent is missing about why one plausible path beats an equally plausible alternative.

If you could describe the diff in one sentence, skip the plan.

Anthropic, Claude Code best practices

That heuristic is a reasonable proxy for small and well-specified: a one-line bug fix, a renamed variable, a log line added where one is missing. None of these earn a proposal-and-approval cycle — the cost of a wrong first attempt is close to the cost of writing and reading a plan for it, so the plan is pure overhead. The third row of the table is the subtler case, and the one teams tend to skip: an agent handed a task by someone who already knows, from experience the agent has no access to, why the obvious-looking approach is the wrong one. A plan surfaces that mismatch before it becomes a diff; skipping the plan on an ambiguous task because the agent “seems confident” does not.

The ceremony failure mode

The costlier failure mode is not skipping plan mode on small tasks. It is defaulting into it on every task regardless of size, until a team’s engineers stop reading plans closely and start approving them the way an overloaded reviewer approves a pull request: because reading carefully feels slower than watching the diff land, and the ritual has to move forward either way. That pattern is familiar from an older discipline — heavyweight, mandatory human code review that exists everywhere in an organization’s process documentation and nowhere in its actual judgment, because everyone learned to treat the gate as a formality rather than a genuine check. A plan nobody reads is not a safety mechanism; it is a delay with a rubber stamp at the end of it. The same failure mode governs the plan-step checkpoints a later volume in this Library calls Checkpoint Thinking: a gate loses its function the moment approving it becomes faster than reading it.

What a plan-mode session should let you ask

The volume’s throughline holds at every grain size intent architecture is practiced at. A full spec-kit workflow decides, then does, across days and multiple documents; plan-mode thinking decides, then does, inside one sitting and one review. Choosing between them is not a maturity ladder where more ceremony is always the safer choice. It is matching the weight of the gate to the size of the decision behind it — and noticing when the gate has stopped doing that job. A team that gets this right will use plan mode constantly on some days and barely touch it on others, and neither pattern is evidence of anything by itself.