Plan mode

In the last lesson, you learned to write a spec. Now you need a way to verify that Claude understood it before it starts changing your code. That's what plan mode is for.

Plan mode is Claude Code's built-in workflow for structured work. Instead of reading your spec and immediately writing code, Claude pauses. It proposes what it's going to do. You review. You approve. Then it executes.

Press Shift+Tab to enter plan mode. Or type /plan. That's it.

The 4-phase workflow

Every plan mode session follows the same four phases.

The power of this workflow is the gap between phase 2 and phase 3. That's where you catch misunderstandings, missing steps, and wrong assumptions — before they become code.

When to plan

Not every task needs a plan. Planning has a cost: it takes time and context. Use it when the payoff is worth it.

Plan when:

• The task touches multiple files
• You're working in an unfamiliar part of the codebase
• The task involves critical systems (auth, payments, data migrations)
• The work will take more than 5 minutes
• You're not sure about the right approach

Skip planning when:

• It's a single-file edit
• You're doing formatting or renaming
• The fix is obvious and you know exactly what needs to change
• The task is a known pattern that Claude has done before in your codebase

The plan as a contract

Once you approve a plan, Claude follows it. Step by step. This is the mechanism that gives you control without micromanaging.

If Claude deviates from the plan — starts refactoring files it wasn't supposed to touch, or changes the approach mid-implementation — you can course-correct immediately (more on this in the next lesson). The plan is your reference point. You know what was agreed. You can tell when the agent goes off-script.

This is fundamentally different from working without a plan, where you only discover the agent's decisions after it's already made them.

> /plan

> "Add a getBySlug query to the blog TRPC router.
   Follow the existing getById pattern.
   Add Zod validation for the slug input.
   Don't modify the blog schema or existing queries."

Claude responds:
  Step 1: Read blog router and getById implementation
  Step 2: Add slugInput schema with Zod string validation
  Step 3: Add getBySlug public procedure following getById pattern
  Step 4: Register in the router export
  Step 5: Run type check to verify

> "Step 2 — use the existing slug pattern from the
   projects router instead of creating a new one.
   Otherwise, approved."

[Claude implements the adjusted plan]

Notice what happened: I caught a duplication issue at the plan stage. Without plan mode, Claude would have created a new schema, I would have noticed during code review, and I would have had to ask for a correction. The plan saved a round trip.

The common mistake: over-planning

A plan should have 5-10 steps. If Claude generates a 20-step plan, the task is too big. Split it.

I've seen people run 50-step plans. By step 30, the context is polluted, the agent has lost track of the earlier steps, and the output quality drops. Long plans also make it harder for you to review — you skim instead of reading, and miss the one step that's wrong.

Advanced setups take this further: use a specialized planner agent. Here is what that agent definition actually looks like:

---
name: planner
model: opus
tools: [Read, Grep, Glob]
---

Notice two design decisions. First, the planner uses Opus — the most powerful model — because planning is where depth of reasoning matters most. Second, it gets only read tools. The planner cannot edit files, run commands, or make changes. It can only gather and think. This is deliberate: a planner that can also implement will skip the checkpoint and start coding. Restricting tools forces the separation between planning and execution.

For now, the rule is simple: if the plan is too long, the task is too big.

Plan mode vs auto mode: a decision guide

Here's how I decide for every task:

Is it a single file?
  Yes → auto mode
  No  → Is it touching critical systems?
    Yes → plan mode, review every step
    No  → plan mode, quick review, fast approval

Most of my work lands in the middle: plan mode with a quick review. I spend 60 seconds reading the plan, adjust one or two steps, and approve. The implementation runs in auto mode from there.

The 4-phase workflow feels slow the first time you use it. By the third time, it feels like exactly the right amount of structure. You're not guessing what Claude will do. You know. And when you know, you can trust the output — or catch the mistake before it happens.