The most expensive problem of pair programming with AI
I learned this the hard way: I asked Claude Code to "improve the performance of the search page". It read two files, drew its conclusions, implemented three "optimizations" in different places and wrote tests — all in under two minutes. I ran the tests, they passed. I merged. A week later I discovered it had refactored the wrong layer: the bottleneck was in the database query, not in the client-side JavaScript.
The mistake wasn't its fault, it was mine. I let the agent start implementing before understanding. And that's the most expensive problem of pair programming with AI: the machine's execution speed hides the slowness of comprehension. You save an hour of typing and lose a day debugging what it did.
Plan mode is Claude Code's official answer to that problem. It's a mode where the agent cannot edit anything — it can only read, research and write a plan file for you to approve. It sounds trivial, but it changes the whole dynamic. This article explains how it works, when to turn it on, when to turn it off, and how to write a plan file that doesn't turn into fluff.
If you haven't seen the seven pillars of Claude Code yet, start with the definitive guide first — plan mode makes much more sense after you understand the agentic loop.
What plan mode does (and doesn't)
In plan mode, write tools are blocked. Claude can:
- Read files (
Read,Grep,Glob) - Run read-only commands (
git log,git diff,npm ls) - Fire research subagents (
Explore,general-purpose) - Edit exactly one file: the plan, at a path predefined by the harness
What it cannot do:
- Edit any other file in the project
- Run state-changing commands (
git commit,npm install,curl -X POST) - Create branches, tags, or push remote changes
This lock is structural, not behavioral. It doesn't depend on the model "remembering" not to edit — the harness itself rejects the call. That means you can ask the agent to research freely without fear of being surprised by a hasty edit to a production file.
How to enter and exit
The fastest way to turn it on is pressing Shift+Tab twice at the prompt — the mode toggles and a plan mode badge shows up in the status line. To exit, the agent itself uses the ExitPlanMode tool, which it calls when it finishes the plan and asks for your explicit approval.
You can also start directly in plan mode by passing --permission-mode plan at CLI launch. Useful for CI runs, or when you know upfront the task is big and want to force the flow from the very first prompt.
The four phases of plan mode done right
The harness embeds a four-phase workflow. People who ignore it and treat plan mode like "normal chat without editing" waste the feature. People who follow it extract real value.
Phase 1 — Understanding. The goal is only to understand the problem and the relevant code. Here you should use Explore subagents to research multiple areas in parallel. The orchestrator receives the summaries without burning context reading file by file. If you don't know this pattern well, see how to fire them in Subagents in Claude Code: orchestrating tasks in parallel.
Phase 2 — Design. Now the agent should draft the approach. This is where the Plan subagent enters — a software architect that takes phase 1 context and returns an implementation proposal with trade-offs. You can run two or three Plan agents in parallel with different perspectives (simplicity vs performance, minimal change vs clean architecture) and pick.
Phase 3 — Review. The agent consolidates what it learned, validates against the original request, and uses AskUserQuestion to resolve ambiguities. This is where doubtful decisions come back to you before they become wrong code.
Phase 4 — Final plan. The agent writes the plan file with the essential sections: Context (why this change), Approach (the chosen path), Critical files (the files to modify), Verification (how to test). Only then does it call ExitPlanMode to ask for approval.
Anatomy of a plan file that doesn't turn into fluff
A good plan file has three traits. First, it explains the why before the how — the Context section must make the problem clear, not just the solution. When you revisit the plan a month later, the why is what orients you.
Second, it lists critical files with exact paths and, when relevant, line numbers. A vague plan file is permission for the agent to "find its way" during execution. A precise plan file is predictable execution.
Third, it has a Verification section — how to test the change end-to-end, which commands to run, what behavior to expect. Without it, plan mode output is just an idea; with it, it's an executable task.
Avoid the opposite mistake: plans that become implementations. If you write 300 lines of pseudo-code into the plan file, it's no longer a plan — it's untested code in a markdown file. Plan files should be decisions + paths + success criteria, not disguised implementations.
When not to turn it on
Plan mode isn't the default mode for a reason: it adds latency. For small tasks, the overhead costs more than the benefit. In the three cases below I leave it off:
- Known pointed edit. "Rename this variable", "add this field to the type". You already know what to do — plan mode just slows you down.
- Fast iteration on a feature you already understand. You and the agent have made 10 micro-adjustments; each one takes 30 seconds. Turning on plan mode destroys the rhythm.
- A fix following a compile error. The compiler already told you what the problem is. Planning a plan for that is theater.
Turn on plan mode when the task has at least one of these: uncertain scope, multiple files, mixed domains, architectural change, or high rollback cost. If you hesitate "will this touch more things?", the answer is plan mode.
Plan mode + memory + slash commands
Plan mode talks to the other pieces of Claude Code. Plan files can reference decisions stored in the Claude Code memory system — if a rule has already been agreed on, the plan doesn't need to reopen it. And it makes sense to package the ritual "turn on plan mode + research + write plan + request review" as a team slash command: learn to create your own in Creating custom Slash Commands, the most direct path to turning this workflow into a versioned habit. The background discipline (conventions, CLAUDE.md, ergonomics) has to be in place first — the guide to slash commands and skills covers the basics.
Next steps
Try this today: pick a task you'd call "medium" and turn on plan mode in the first second. Watch how the agent researches before giving its opinion. Read the plan critically, ask "what's missing?", approve only when it's clear. The first time it will feel slow. By the third time, you won't go back. When you want to take the next step and orchestrate parallel work during phase 1, combine plan mode with subagents — it's the combination that saves the most time on large tasks.
