Claude Code Plan Mode: Plan Before You Edit

What plan mode is and why it matters

By default, Claude Code is an agent that acts. You give it a task, and it reads files, makes edits, and runs commands to get the job done. For small, well-scoped changes that is exactly what you want. For anything larger, acting immediately has a cost: the agent commits to an approach before you have seen it, and if the approach is wrong, you are now reviewing and unwinding edits instead of redirecting a plan.

Plan mode flips the order. In plan mode, Claude Code researches the task, reads the relevant code, and produces a concrete plan of what it intends to do, without making any edits or running any state-changing commands. You read the plan, correct anything that is off, and only then approve it for execution. The agent does the thinking out loud first; you steer before a single file changes.

This matters most on the changes where getting it wrong is expensive: multi-file refactors, anything touching schemas or migrations, payment or auth code, work in an unfamiliar part of the codebase, or any task where there are several reasonable approaches and you have a preference. Plan mode turns "review the diff and hope" into "approve the approach, then review the diff," which is a much stronger position. It is the closest thing Claude Code has to a "measure twice, cut once" gate.

For the broader set of habits that make agentic coding reliable, Claude Code best practices covers the workflow around plan mode, and Claude Code permissions covers the complementary safety layer of restricting what the agent may run.

Entering and exiting plan mode

Claude Code cycles through permission modes with Shift+Tab. Pressing it rotates between the default mode (Claude asks before edits and commands), auto-accept mode (Claude proceeds without prompting), and plan mode (Claude plans without acting). The current mode is shown in the interface, so you can see which one is active before you send a message.

The practical flow:

1. Press Shift+Tab until the interface indicates plan mode is active.
2. Type your task as you normally would.
3. Claude researches and reads code, then presents a plan instead of editing.
4. Review the plan. If it is wrong, reply with corrections and Claude revises it.
5. When the plan is right, approve it. Claude exits plan mode and executes.

To leave plan mode without executing, press Shift+Tab again to cycle back to another mode, or simply tell Claude you want to change direction. Plan mode is a posture, not a one-way door; you move in and out of it freely depending on how much you trust the next step.

The mental model: plan mode is read-only for your project. Claude can read files, search, and reason, but it will not write a file, delete anything, or run a command that changes state until you approve the plan. That guarantee is what makes it safe to point at risky work.

A worked example: a multi-file refactor

Say you want to extract authentication logic that is currently duplicated across several route handlers into a shared middleware. This is exactly the kind of change where plan mode earns its keep, because there are several ways to structure it and the wrong structure is annoying to undo.

In plan mode, you send:

Extract the auth checks duplicated in the route handlers into a single shared middleware, and update every route to use it.

Instead of editing, Claude reads the route files, finds the duplicated checks, and comes back with a plan along these lines:

Plan

1. Create src/middleware/auth.ts exporting requireAuth, consolidating the token validation currently repeated in five handlers.
2. Update src/routes/users.ts, orders.ts, billing.ts, admin.ts, and reports.ts to import and apply requireAuth instead of inline checks.
3. Preserve the existing 401 response shape so the frontend contract does not change.
4. Add a unit test for requireAuth covering valid token, missing token, and expired token.

I will not change the public response shapes. Shall I proceed?

Now you can steer before anything happens. Maybe you reply: "Good, but put the middleware in src/lib/auth-middleware.ts to match our existing convention, and skip admin.ts, it uses a different scheme." Claude revises the plan, you approve, and only then does it write the files. You reviewed the approach when correcting it was a one-line reply, not a multi-file diff revert. For schema-touching versions of this same pattern, Claude Code with PostgreSQL shows why planning before a migration is worth the extra step.

A worked example: an unfamiliar codebase

Plan mode is also the right first move when you are working somewhere you do not know well. You inherited a service and need to add a feature, but you are not sure how the existing pieces fit.

Enter plan mode and ask:

Add a webhook endpoint that records incoming events to the database and enqueues a background job to process them. Follow the patterns already in this codebase.

Because plan mode makes Claude read before acting, the plan it returns doubles as a map of the codebase:

Plan

1. The codebase uses Express routers under src/routes/ and a job queue via BullMQ in src/jobs/. New webhook router goes in src/routes/webhooks.ts, registered in src/app.ts.
2. Events table already exists (events in the schema); I will insert with the existing db client in src/lib/db.ts.
3. Enqueue via the existing eventQueue defined in src/jobs/queue.ts, matching the pattern in src/jobs/email.ts.
4. Verify the webhook signature using the secret in WEBHOOK_SECRET, following the validation helper in src/lib/crypto.ts.

That plan tells you how the codebase is wired and what Claude intends, before any code is written. If the agent misread a pattern, you catch it in the plan instead of in a diff that has already deviated from house style. This is one of plan mode's underrated benefits: on unfamiliar code, the plan is reconnaissance you would otherwise have to do by hand.

Steering a plan effectively

A plan is a draft to negotiate, not a verdict to accept or reject. The developers who get the most from plan mode treat the plan as a conversation:

• Correct the approach, not the wording. If the structure is wrong, say so directly: "do not add a new dependency, use the standard library," or "split this into two PRs." Claude revises the plan to match.
• Constrain scope explicitly. "Only touch the API layer, leave the frontend alone" in plan mode prevents the agent from wandering once it starts executing.
• Ask for the plan to be more specific if it is vague. "List the exact files you will change" forces a concrete plan you can actually evaluate.
• Approve in stages for large work. For a big task, approve the first phase, review the result, then plan the next. You keep the agent on a short leash where the risk is highest.

The goal is to spend your review effort at the cheapest possible moment, when changing direction costs a sentence, rather than the most expensive, when it costs reverting and re-running.

When to reach for plan mode

Plan mode is a tool, not a default for everything. Use it deliberately:

Reach for plan mode when:

• The change spans multiple files and the structure matters.
• You are touching risky surfaces: schemas, migrations, auth, payments, deploy config.
• You are in an unfamiliar codebase and want the plan to double as a map.
• There are several reasonable approaches and you have a preference.
• You want a record of the intended approach before execution, useful when pairing or reviewing.

Skip plan mode when:

• The task is a small, obvious, single-file change, planning it is pure overhead.
• You are iterating quickly on something low-stakes and a wrong turn is cheap to undo.
• You have already agreed the approach in conversation and just want it executed.

The honest rule of thumb: if a wrong approach would cost you more than a minute to unwind, plan first. If it would not, just let the agent run.

Pitfalls to avoid

A few ways plan mode goes wrong in practice, and how to sidestep them:

Approving a vague plan. A plan that says "refactor the auth code and update the routes" is not a plan you can evaluate; it is a restatement of your request. Push back: ask which files, which functions, what stays the same. Approve only a plan specific enough that you could predict the resulting diff.

Treating the plan as binding. The plan is the agent's intent, not a contract it will follow perfectly. Reality can surface something the plan did not anticipate. Still review the final diff; plan mode reduces surprises, it does not eliminate the need to check the result.

Forgetting which mode you are in. If you think you are in plan mode but you are in auto-accept, the agent will execute immediately. Glance at the mode indicator before sending a task you intended to plan. When in doubt, press Shift+Tab to cycle and confirm.

Using it for trivial work. Planning a one-line fix wastes a round trip and trains you to skim plans. Save plan mode for changes where the plan genuinely informs your review, so you actually read it when it matters.

Letting the plan get stale. On a long task, if you approve a plan and then the conversation drifts through several corrections, re-confirm the current intent before executing. Ask Claude to restate the final plan after a round of edits so you are approving what it will actually do, not an earlier version.

Plan mode in the larger workflow

Plan mode is the front half of a safe agentic workflow. The back half is the diff review and the deterministic guardrails that catch anything the plan and your review missed. Plan mode reduces surprises by getting agreement on the approach up front; Claude Code permissions reduces blast radius by restricting what the agent may run regardless of the plan; and Claude Code with Python (or your language's equivalent conventions) reduces defects by encoding the patterns the generated code should follow.

Used together, the loop becomes: plan the approach, approve it, let the agent execute within its permissions, review the diff. Plan mode is the step that moves your judgement to the cheapest point in that loop. For non-trivial work, that single habit, plan before you edit, is the difference between directing an agent and cleaning up after one.

Get Claudify. A complete Claude Code operating system with commands, permissions, and project memory tuned so plan-then-execute is the default for serious work.