Plan Mode: Think Before You Build - Claude Code Masterclass

There's a moment in every complex refactor where you think: "I wish I could see what Claude is about to do before it does it." That's exactly what plan mode gives you.

In plan mode, Claude analyzes your codebase, proposes changes, and explains its reasoning -- but doesn't execute anything. You review the plan, adjust it, and then let Claude execute. It's the difference between "do this" and "show me what you'd do."

When Plan Mode Matters

Most of the time, you want Claude to just act. Fix the bug. Add the feature. Run the test. But there are moments where stopping to think is worth the extra step:

Complex refactors -- Renaming a core abstraction that touches 30 files
Unfamiliar codebases -- You just cloned a repo and need to understand it before changing it
High-stakes changes -- Database migrations, auth system modifications, production configs
Learning -- You want to understand why Claude would make certain changes, not just see the result
Team alignment -- You need to share a plan with teammates before committing to an approach

Plan mode is your architectural review before writing code

Think of plan mode as a pull request you create before writing any code. You get to see the full scope of changes, challenge the approach, and course-correct before a single file is modified. This is especially valuable when the cost of undoing work is high.

Activating Plan Mode

There are three ways to enter plan mode:

1. Keyboard shortcut (interactive)

While in Claude Code, press Shift+Tab to cycle through input modes. The modes cycle:

normal -> plan -> normal -> plan -> ...

The mode indicator appears next to the input prompt so you always know which mode you're in.

2. CLI flag (session-wide)

Start Claude Code in plan mode from the beginning:

claude --permission-mode plan

This starts the entire session in plan mode. Claude will propose changes but won't execute any write operations.

3. Permission modes

Plan mode is one of five permission modes:

Mode	Reads	Writes	Commands	Best for
default	Allowed	Asks permission	Asks permission	Day-to-day work
acceptEdits	Allowed	Auto-approved	Asks permission	Trusted edit workflows
plan	Allowed	Proposes only	Proposes only	Review before acting
dontAsk	Allowed	Auto-approved	Auto-approved	Automated pipelines
bypassPermissions	Allowed	Auto-approved	Auto-approved	Full automation (use with caution)

Permission modes are about trust levels

plan is the most conservative mode that still lets Claude reason about your code. bypassPermissions skips all safety checks -- use it only in sandboxed CI environments, never on your local machine with real data.

The Plan-Then-Execute Workflow

Here's how a plan mode session typically flows:

Step 1: Ask in plan mode

[plan] > Refactor the authentication module to use JWT tokens
         instead of session cookies. Show me what needs to change.

Step 2: Claude proposes

Claude will analyze your codebase and produce a structured plan:

Which files need to change and why
What the new code structure looks like
Which dependencies need to be added
What tests need updating
Potential risks or breaking changes

Step 3: You review and adjust

This is where the value is. You can:

Challenge specific parts: "Why change middleware.ts? Can we keep the current approach there?"
Add constraints: "Don't touch the database schema -- use a migration instead"
Reorder priorities: "Start with the token generation, then the middleware, then the tests"
Split the work: "Let's do this in three PRs instead of one"

Step 4: Switch to normal mode and execute

Press Shift+Tab to switch back to normal mode, then tell Claude to execute the plan:

[normal] > Execute the plan we discussed. Start with the token
           generation module.

Claude now has full context of the agreed-upon plan and executes accordingly.

Plan Mode vs. Just Asking

You might wonder: "Can't I just ask Claude to explain what it would do?" You can, but plan mode is different:

Aspect	Asking 'what would you do?'	Plan mode
File analysis	Claude may skim	Claude reads files thoroughly since it knows it needs a precise plan
Specificity	Often high-level	File-by-file, line-by-line changes
Safety	Claude might still edit if it misunderstands	Write operations are blocked at the system level
Context retention	Plan is in chat history only	Plan is structured and actionable

The key difference: in plan mode, Claude knows it can't execute, so it invests more effort in making the plan precise and complete. It reads more files, considers more edge cases, and produces more actionable output.

Combining Plan Mode with Sub-Agents

Plan mode becomes even more powerful when combined with sub-agents from the previous section.

A common pattern:

Start in plan mode to understand the scope
Create an Explore agent to research specific parts in parallel
Refine the plan based on the agent's findings
Switch to normal mode and execute

[plan] > I need to migrate our API from REST to GraphQL.
         @explorer Analyze our current REST endpoints and their usage patterns.
         Based on that, propose a migration plan.

The explorer agent investigates your API surface while plan mode ensures nothing gets changed prematurely.

Getting Better Plans

The quality of Claude's plans depends on what you give it. Some tips:

Be specific about constraints. "Refactor the auth module" produces a vague plan. "Refactor the auth module to use JWT, keep backward compatibility with existing sessions for 30 days, and don't change the database schema" produces a precise one.

Mention what you care about. "I care most about not breaking the mobile app's auth flow" tells Claude where to focus its analysis.

Ask for risks. "What could go wrong with this approach?" forces Claude to think adversarially about its own plan.

Set scope boundaries. "Only plan changes to src/auth/ -- don't touch other modules even if they import from auth" prevents scope creep.

The two-pass technique

For truly complex changes, do two passes in plan mode. First pass: "What are all the files and systems affected?" Second pass: "Now plan the actual changes, starting with the lowest-risk modifications." The first pass gives Claude (and you) a map before diving into details.

Exercise

Plan a refactor, then execute it

Pick a real piece of code in your project that could use refactoring (a long function, duplicated logic, or an outdated pattern). Use plan mode to create a refactor plan, review it, then switch to normal mode and execute.

Press Shift+Tab to enter plan mode. Describe the refactor clearly, including what you want to preserve (tests passing, API compatibility, etc.).

When reviewing the plan, challenge at least one decision. Ask Claude why it chose a particular approach and whether there's an alternative. This forces a deeper analysis.

Here's an example workflow:

# Start Claude Code
claude

# Press Shift+Tab to enter plan mode
[plan] > The `processOrder` function in src/orders/process.ts is 200 lines
         long. Plan a refactor to break it into smaller, testable functions.
         Keep the public API identical. All existing tests must still pass.

Review Claude's plan. It should identify:

Which blocks of logic can be extracted
What the new function signatures look like
How error handling chains between the new functions
Which tests need updating

Then switch:

# Press Shift+Tab to return to normal mode
[normal] > Execute the refactor plan. Run the tests after each extraction
           to make sure nothing breaks.

Claude will now execute the plan step by step, running tests along the way.

A live demo of plan mode works best with a real messy function. Open a 100+ line function, enter plan mode, and show the class how Claude breaks it down. The "aha moment" is when students see how much more thorough the analysis is in plan mode vs. just asking Claude to refactor directly.

Module Recap

This module covered three ways to extend Claude Code beyond basic prompting:

MCP -- Connect Claude to external tools (databases, browsers, APIs)
Sub-agents -- Parallelize work across multiple Claude instances
Plan mode -- Think before you build, especially for complex changes

These three capabilities stack. You can run a plan-mode session where Claude uses MCP servers to query your database schema and spins up an Explore agent to map your codebase -- all before proposing a single line of code.

The next module covers Compound Engineering -- how to chain these capabilities into repeatable workflows that compound your productivity over time.