Claude Code /plan Explained: Think Before You Code

Why You Need /plan

When developing with Claude Code, the biggest fear isn’t that Claude can’t write code — it’s that it writes a ton of code in the wrong direction.

A refactoring task involving a dozen files, and Claude dives right in without hesitation. Halfway through, you realize the approach is wrong, but seven or eight files have already been modified. Roll back? Too costly. Keep going? It only gets messier.

There’s another scenario: you want Claude to help you review the code architecture and spot optimization opportunities. But the moment you ask, it starts modifying code — you just wanted to discuss the approach, you never said go.

The root cause: Claude defaults to “execution mode” and doesn’t stop to think first.

That’s when you need /plan.

What Is /plan

/plan is Claude Code’s read-only planning mode. In this mode, Claude can only read code, search code, and analyze code, but cannot write files, edit code, or execute commands.

In interactive mode, type:

/plan

Or press Shift+Tab twice. The status bar at the bottom will show ⏸ plan mode on, indicating you’ve entered planning mode.

In this mode, Claude will:

• Analyze the codebase: Read files, search keywords, understand project structure
• Create an implementation plan: Write the plan as a Markdown file, saved to the plans directory
• Wait for your approval: Only exits planning mode and starts execution after you confirm

Simply put, /plan answers the question: how should this be done, rather than just doing it.

How to Enter and Exit Plan Mode

There are three ways to enter Plan Mode:

Method 1: Shift+Tab Shortcut

In the Claude Code interactive interface:

• First press Shift+Tab: Enters auto-accept mode (⏵⏵ accept edits on)
• Second press Shift+Tab: Enters planning mode (⏸ plan mode on)

Method 2: /plan Command

Type the slash command directly:

/plan

Same effect as the keyboard shortcut — handy when you can’t remember the keys.

Method 3: Startup Flag

Start Claude Code directly in planning mode:

claude --permission-mode plan

Also works in headless mode:

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

How to Exit

Press Shift+Tab once more to exit planning mode. When exiting, Claude will ask for additional confirmation about the task it’s about to execute — a safety mechanism to make sure you’re really ready to proceed.

Tools Available in Plan Mode

The core principle of planning mode is read-only, no writes. Here’s the tool availability:

Available Tools (Read-Only)

Tool	Purpose
Read	View file contents
Glob	Search files by pattern
Grep	Search file contents
WebSearch	Search the web
WebFetch	Fetch web content
TodoWrite	Manage task lists
Agent	Dispatch sub-agents for research

Blocked Tools (Write Operations)

Tool	Reason
Edit	Cannot edit files
Write	Cannot create files
Bash	Cannot execute commands
NotebookEdit	Cannot modify notebooks

Why this design? Because the planning phase should have zero side effects. When you ask Claude to analyze a problem and design a plan, that’s all it should do. Once you’ve thought it through and confirmed, exit planning mode to execute.

Plan File Storage and Management

Plans generated in Plan Mode aren’t throwaway — they’re saved as Markdown files with persistent storage.

Default Storage Location

Plan files are stored by default in:

~/.claude/plans/

Filenames are randomly generated, like dreamy-orbiting-quokka.md. Each file is a complete implementation plan.

Plan File Characteristics

• Persists across sessions: Close and reopen Claude Code, and the plan file is still there
• Survives context compaction: Even when conversations are compressed, plan files aren’t lost
• Human-editable: You can open the Markdown file directly, add annotations, and modify the plan

Custom Storage Directory

If you want plan files in your project repository for team collaboration and version control, configure it in settings.json:

{
  "plansDirectory": "./plans"
}

This saves plan files to the plans/ folder in your project root, enabling:

• Plans alongside PRs: Team members review the plan before reviewing code
• Annotations across sessions: No dependency on context compaction, annotations persist forever
• Collaborative editing: Treat plan files as living technical documents

Practical Use Cases

Case 1: Planning Before a Major Refactor

You need to refactor the authentication system, touching a dozen files. Enter planning mode first:

/plan
Refactor the auth system from sessions to JWT, list all files that need changes and the steps

Claude will read through all the relevant code and output a detailed implementation plan: which files to change, what to change, and in what order. Once you confirm the plan looks good, exit planning mode and start executing.

Case 2: Code Audit and Architecture Analysis

You don’t want to change code, just have Claude review code quality:

/plan
Analyze the project's error handling patterns, find inconsistencies, and suggest improvements

Plan Mode is naturally perfect for this — read-only analysis, output a report, don’t touch any code.

Case 3: Aligning Plans Across a Team

The team is building a major feature. Have Claude draft the plan and store it in the project repository:

{
  "plansDirectory": "./plans"
}

/plan
Design a technical plan for the push notification feature, including architecture choices, data models, and API design

After the plan is generated, team members can annotate the Markdown file directly, iterate through multiple rounds, and reach consensus before writing any code.

Case 4: Quickly Onboarding to an Unfamiliar Codebase

Taking over a new project? Use Plan Mode to have Claude map out the landscape:

/plan
Analyze the overall architecture of this project, what the core modules are, and how data flows through the system

Claude will systematically read code, search key files, and give you a panoramic view of the project. Much faster than digging through the code yourself.

Practical Tips

Tip 1: Use Opus Plan Mode

In the /model command, select option 4: “Use Opus in plan mode, Sonnet 4.6 otherwise.” This uses Opus (stronger reasoning) for planning and Sonnet (faster speed) for execution. Think with brainpower, execute with speed.

Tip 2: Store Plan Files in Your Repository

Configure plansDirectory to a project-relative path so plan files travel with the code. Benefits include PR-reviewable plans, Git-tracked change history, and multi-person annotation iterations.

Tip 3: Iterate with Multiple Annotation Rounds

Don’t rush to approve right after a plan is generated. Open the Markdown file, annotate where you think something is off, then have Claude update the plan based on your notes. After three rounds of iteration, a generic plan transforms into one that perfectly fits your project.

Tip 4: Mind the 7-File Rule

Experience shows that plans touching more than 7 files tend to drop in execution quality. The context window fills up with code during execution. If a plan involves too many files, consider splitting it into smaller plans and executing them step by step.

Final Thoughts

/plan solves a simple problem: making Claude think before it acts.

When developing with Claude Code, the biggest efficiency killer isn’t slow code generation — it’s going in the wrong direction and having to redo everything. For complex tasks, if you let Claude start immediately, you might discover halfway through that the approach is wrong, and all the previous work is wasted.

Enter planning mode first. Let Claude read the code thoroughly, lay out a clear plan, and get your confirmation before starting. Slow is fast — thinking clearly is the ultimate efficiency.

One command to make every change deliberate.