Plan Mode
Module: Agents & Subagents | Lesson: 4 of 4 | Time: ~10 minutes
What You Will Learn
- How to activate plan mode
- How read-only exploration works in plan mode
- How to design a solution before implementing it
Prerequisites
- Completed Subagent Types
What Is Plan Mode?
Plan mode is a special mode in Claude Code where Claude analyzes your code and produces a plan without making any changes. It is read-only — Claude will read files, search through code, and think through problems, but it will not edit, create, or delete anything.
Before construction workers build a house, an architect draws blueprints. Plan mode is the blueprint phase for your code changes. Claude examines the site (your codebase), designs the solution, and gives you a detailed plan to review. Only after you approve the plan does the actual building begin.
Activating Plan Mode
There are two ways to enter plan mode:
1. The /plan Command
Type /plan in your Claude Code conversation followed by your request:
/plan Add user authentication with JWT tokens to this Express app
Claude will switch to plan mode for this task.
2. Using the --plan Flag
Start Claude Code in plan mode from the beginning:
claude --plan
In this mode, Claude stays in plan mode for the entire session until you tell it to implement.
What Happens in Plan Mode
When Claude is in plan mode, it goes through these steps:
- Explores — Claude reads relevant files, searches for patterns, and understands the current state of your code
- Analyzes — Claude thinks through the problem and considers different approaches
- Plans — Claude produces a detailed, step-by-step plan of what changes need to be made
The output typically looks something like this:
## Plan: Add JWT Authentication
### Files to Create
1. `src/middleware/auth.ts` - JWT verification middleware
2. `src/routes/auth.ts` - Login and register endpoints
3. `src/types/auth.ts` - TypeScript interfaces for auth
### Files to Modify
1. `src/app.ts` - Add auth routes and middleware
2. `src/routes/index.ts` - Mark protected routes
3. `package.json` - Add jsonwebtoken dependency
### Steps
1. Install jsonwebtoken and @types/jsonwebtoken
2. Create auth types (User, TokenPayload)
3. Create JWT middleware that verifies tokens on protected routes
4. Create login endpoint that validates credentials and returns a token
5. Create register endpoint that hashes passwords and creates users
6. Update app.ts to mount auth routes
7. Add auth middleware to protected routes
Reviewing the Plan
After Claude presents the plan, you have several options:
| Action | What to Do |
|---|---|
| Approve the plan | Tell Claude to go ahead: "Looks good, implement it" |
| Modify the plan | Ask for changes: "Skip step 5, we do not need registration yet" |
| Ask questions | Get more detail: "What library will you use for password hashing?" |
| Reject the plan | Start over: "Let us take a different approach. What about using sessions instead of JWT?" |
This review step is the key benefit of plan mode. You see exactly what Claude intends to do before any code is changed.
Plan mode does not guarantee the implementation will be perfect. The plan is Claude's best analysis, but unexpected issues may come up during implementation. The value is in catching major design problems early — like choosing the wrong architecture or missing a key requirement.
When to Use Plan Mode
Plan mode is most valuable for:
| Situation | Why Plan Mode Helps |
|---|---|
| Large changes | You want to review the approach before Claude touches many files |
| Unfamiliar codebases | You want Claude to explore and explain before making changes |
| Critical code | You want full control over what gets modified (auth, payments, etc.) |
| Learning | You want to understand how something should be built before doing it |
| Team decisions | You want a plan to share with teammates before implementing |
Plan mode is less useful for small, obvious changes like "fix this typo" or "add a missing semicolon." For those, just let Claude do it directly.
Plan Mode + Agents
Plan mode works especially well combined with the agent concepts from earlier lessons. A typical workflow for a complex task:
- Plan mode to explore and design the solution
- Review the plan and make adjustments
- Implement — Claude can use subagents to work on different parts of the plan in parallel
- Verify — check that the implementation matches the plan
This plan-then-implement workflow prevents Claude from heading in the wrong direction on a large task. It is particularly valuable when the task involves multiple files or components.
Try It Yourself
Use plan mode to design a change before implementing it:
- Start Claude Code in a project (ideally one with some existing code):
claude
- Enter plan mode with a non-trivial request:
/plan Add a simple logging utility that logs to both the console and a file.
It should support log levels (info, warn, error) and include timestamps.
-
Read through the plan Claude produces. Ask yourself:
- Does the file structure make sense?
- Are there any missing steps?
- Would you do anything differently?
-
Ask Claude a clarifying question about the plan:
What happens if the log file does not exist yet? Will you create it automatically?
- If the plan looks good, tell Claude to implement it:
The plan looks good. Go ahead and implement it.
- After implementation, compare the result to the original plan. Did Claude follow it accurately?
What You Learned
- Plan mode is read-only analysis — Claude explores your code and produces a plan without making changes
- Activate plan mode with
/planin a conversation or--planwhen starting Claude - The plan includes files to create, files to modify, and step-by-step implementation details
- You can approve, modify, question, or reject the plan before implementation
- Plan mode is most valuable for large changes, critical code, and unfamiliar codebases
- Combining plan mode with agents creates a powerful plan-then-implement workflow
How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.