Claude Code's plan mode, after a few months of using it

A note on the date: this post is from early 2025. Claude Code has moved since — most notably, there’s now a /plan command that does the same thing as the Shift+Tab dance described below. The argument hasn’t changed, but if you’re new to Claude Code, /plan is probably how you’ll hear about this feature.

I’d been hitting Tab and watching Claude blast through three iterations of the same feature before realising I’d never actually told it what I wanted. The first pass scaffolded a service. The second pass tore most of it out because it had guessed wrong about our auth layer. The third pass was me, in the prompt box, finally writing out the constraints I should have written out before any code got generated.

That was the loop I kept landing in. Not because the tool was bad — because I was using it like an autocomplete and it was happy to oblige. Plan mode is the switch that broke me out of that.

What plan mode actually is

Press Shift+Tab twice in Claude Code and you’ll see ⏸ plan mode on at the bottom of the terminal. From that point on, Claude can read files, grep, fetch URLs, dispatch subagents — anything observational. It cannot edit, write, or run shell commands. The restriction is enforced at the tool layer, not by prompting; the execution tools are simply unavailable until you accept the plan.

The shape of a session with plan mode on:

1. You describe what you want.
2. Claude reads around the codebase, asks clarifying questions if anything’s ambiguous, and produces a plan.
3. You read the plan. If it’s wrong, you push back in chat and Claude revises. The cost of revising a plan is two paragraphs; the cost of revising the implementation is the implementation.
4. When the plan is right, you accept. Plan mode exits and Claude starts making changes against that plan.

That’s the whole feature. The reason it matters is the third step. Once code is on disk you start sunk-cost-fallacying your way into keeping it. A plan is cheap to throw away.

What changed in how I work

Before plan mode I’d describe the task, hit enter, and start steering. Mid-implementation course corrections are expensive — they create dead branches in the git history and dead code in the working tree, and they pollute the chat context with rabbit-holes Claude will keep referring back to.

After plan mode the friction moved to the front. I describe the task in plan mode. Claude reads the relevant files first — usually more files than I’d have thought to load — and either asks me a clarifying question or produces a plan that’s specific enough that I can argue with it. The arguments happen against a markdown plan, not against half-written code.

The other thing that fell out of this: the plans themselves are useful artifacts. For anything bigger than a one-file change I save the plan to a markdown file in the repo. Future sessions can reference it. Reviewers can read it. If I /clear halfway through a multi-day refactor and start a new session, the new session starts from the plan instead of from a vague memory of what I was doing.

Ambiguity, before vs. after

The thing I underrated: plan mode makes Claude better at asking questions. In standard mode it’ll usually guess and proceed. In plan mode it’ll stop and ask, because there’s no execution pressure pulling it toward a half-formed answer.

Concretely: I asked for “user authentication” once, in plan mode, on a project that already had a half-built session layer. Standard mode would have probably bolted on JWT-in-localStorage and called it a day. Plan mode came back with: do you want me to extend the existing session middleware, or replace it? Cookie-based or token-based? Refresh strategy? Are you keeping the current login form or rewriting it?

Five minutes of clarifying beats two hours of unwinding the wrong assumption.

The general pattern I’ve settled into: when the task is ambiguous, I tell Claude in the prompt to ask questions before planning. It’s a one-liner. “Ask me clarifying questions before writing the plan.” It costs nothing and the resulting plan is dramatically tighter.

Subagents for parallel exploration

The other thing plan mode unlocks is parallel reads via the Task tool. Each subagent runs in its own context window, so an agent that goes spelunking through 40 files of frontend code doesn’t push everything else out of the main context.

The pattern that earns its keep: split exploration into 3–4 subagents along natural seams. Frontend, backend, data layer, infra. Each one comes back with a summary. The main session stitches the summaries into a plan.

I don’t use this for implementation as often as the docs suggest. Most features I work on aren’t actually parallelisable at the file-edit level — they cross layers and depend on each other. But for the exploration phase of a new codebase, or for “tell me what’s already here” before writing a plan, parallel subagents are the difference between Claude knowing the codebase and Claude guessing about the codebase.

When I skip it

Plan mode has a cost. It’s a few extra seconds to a minute up front, and it’s a context switch — you have to read the plan instead of just reading the diff. That cost is worth paying for anything where I don’t already know the answer. It’s not worth paying for:

• One-line bug fixes where I can read the diff faster than I can read a plan.
• Stuff I’ve done five times before in this codebase, where the plan would just be the obvious thing.
• Hotfixes where the cost of being slightly wrong is lower than the cost of being slow.

The honest version of “when to use plan mode” is: if I can’t predict what Claude is about to write, I want to see the plan first. If I can, I don’t.

A few prompts that work

These aren’t templates, they’re the shapes I keep coming back to.

For new features:

[plan mode]

Implement a notifications system. Before you plan, read
src/notifications/ and src/users/ — if anything in the
existing code constrains the design, ask me. Then propose
a plan covering schema, API surface, and how it fits with
the existing event bus.

For refactors:

[plan mode]

src/billing/ has grown to ~1500 lines across three files
and I want to break it apart. Read it. Identify the
responsibilities. Propose a target shape and a migration
path. Save the plan to BILLING_REFACTOR.md before you exit
plan mode.

For exploring an unfamiliar codebase:

[plan mode]

I'm new here. Use subagents in parallel to explore:
- frontend (components, state, routing)
- backend (routes, middleware, services)
- data (models, migrations, queries)
- infra (config, deploys)

Come back with a summary per area. No plan yet — I want
to see the lay of the land first.

The pattern across all three: be specific about what you want Claude to read before it plans, and be specific about what the plan should cover. Plan mode rewards precision.

What it actually changed

The first time I used plan mode I thought of it as a safety feature — read-only, no surprises. That’s true and it’s not the interesting part. The interesting part is that it forces the conversation about what before the conversation about how. Most of the times I’ve been frustrated with an AI coding tool, the root cause was that we’d skipped straight to how and were now arguing about implementation details for a problem we hadn’t agreed on.

Plan mode doesn’t make Claude smarter. It makes me, the operator, slow down for thirty seconds and read what we’re about to do. That’s the whole trick. Worth two keystrokes.