Plan Mode

Plan mode is a specialized interaction mode where Claude focuses on planning instead of executing. Use it for complex features to define requirements, explore options, and create specifications—before writing any code.

What Is Plan Mode?

In plan mode, Claude:

• ✅ Asks clarifying questions
• ✅ Explores options and tradeoffs
• ✅ Creates detailed specifications
• ✅ Presents plans for your approval
• ❌ Doesn’t write code (until you approve)
• ❌ Doesn’t execute commands
• ❌ Doesn’t modify files

It’s the difference between:

Normal mode:

> add user authentication

# Claude immediately starts writing code
Creating auth.py...

Plan mode:

> add user authentication

Before I implement this, I have some questions:

1. What authentication method?
   ○ JWT tokens (stateless)
   ○ Session cookies (traditional)
   ○ OAuth 2.0 (third-party)

2. Password requirements?
   [asks for specifics]

3. Do you need password reset functionality?
   [clarifies scope]

Activating Plan Mode

Method 1: Keyboard Shortcut

Press Alt+M (Windows/Linux) or Option+M (Mac) to cycle through modes:

Normal Mode → Plan Mode → Normal Mode → ...

Look for the mode indicator in your interface.

Method 2: Explicit Request

Tell Claude you want to plan first:

> add a notification system
> before implementing, interview me to understand requirements

> add search functionality
> plan mode: let's define the spec before coding

> implement user preferences
> ask clarifying questions first, don't code yet

How Plan Mode Works

1. You describe what you want

   > add rate limiting to the API

2. Claude asks clarifying questions

   Uses the AskUserQuestion tool to present structured questions:

   ┌─────────────────────────────────────────┐
   │ What endpoints need rate limiting?      │
   │                                         │
   │  ○ All endpoints                        │
   │  ○ Only authenticated endpoints         │
   │  ○ Specific endpoints (specify)         │
   └─────────────────────────────────────────┘

3. You answer questions

   Select options or provide details.

4. Claude creates a specification

   Based on your answers:

   # Rate Limiting Specification
   
   ## Scope
   - All authenticated endpoints
   - 100 requests per minute per user
   - 1000 requests per minute per IP
   
   ## Technical Approach
   - Redis for distributed rate limiting
   - Use redis-py with sliding window algorithm
   - Return 429 with Retry-After header
   
   ## Files to Modify
   - app/middleware/rate_limit.py (create)
   - app/routes/*.py (add decorator)
   - requirements.txt (add redis-py)
   
   ## Acceptance Criteria
   - Exceeding limit returns 429
   - Retry-After header accurate
   - Tests for limit enforcement

5. You approve or refine

   > this looks great, implement it
   # or
   > change the limit to 50 requests per minute, then implement

6. Implementation begins

   Claude switches to normal mode and executes the plan.

When to Use Plan Mode

✅ Perfect For:

New features with multiple components

> add a complete user notification system
> [plan mode helps define: types, delivery, preferences, storage]

Architecture decisions

> should we use a queue for background jobs or handle them inline?
> [plan mode explores tradeoffs]

Features with unclear requirements

> add analytics tracking
> [plan mode clarifies: what events? which service? PII concerns?]

Complex integrations

> integrate with Stripe for payments
> [plan mode defines: products, webhooks, error handling]

Anything involving money, auth, or data

> add payment processing
> [plan mode ensures security and compliance considerations]

❌ Overkill For:

Simple, well-defined tasks

> add a comment explaining this function
# Don't need plan mode—just do it

Quick fixes

> fix the typo in the error message
# Planning wastes time

One-line changes

> rename this variable
# Too simple for planning

Plan Mode vs Normal Mode

Aspect	Normal Mode	Plan Mode
Focus	Execute immediately	Plan thoroughly first
Questions	Maybe asks 1-2	Comprehensive interview
Output	Code changes	Specification document
Speed	Faster start	Slower start, faster finish
Best for	Clear requirements	Unclear requirements
Iterations	Costly (rewrites code)	Cheap (just updates spec)

Plan Mode + Thinking Modes

Plan mode and thinking modes work together:

You: [in plan mode] add a caching layer

Claude: <thinking>
Complex feature. Need to clarify:
- What to cache (API responses? Database queries?)
- Cache backend (Redis? In-memory?)
- Invalidation strategy
- TTL requirements
</thinking>

Let me ask some questions to understand your caching requirements:

┌─────────────────────────────────────────┐
│ What should be cached?                   │
│                                          │
│  ☐ API response data                     │
│  ☐ Database query results                │
│  ☐ Computed values                       │
│  ☐ Static assets                         │
└─────────────────────────────────────────┘

The thinking helps Claude ask better questions.

The Spec-First Workflow

A powerful pattern for complex features:

1. Planning session (plan mode)

   claude
   # Enable plan mode: Alt+M
   > add user preferences feature
   # [answer clarifying questions]
   > save the spec to docs/specs/user-preferences.md
   exit

2. Implementation session (normal mode)

   claude
   > implement the spec in docs/specs/user-preferences.md
   # [Claude implements following the spec]

3. Testing session (normal mode)

   claude
   > write comprehensive tests for the user preferences feature
   > use the spec in docs/specs/user-preferences.md for test cases

Each session gets fresh context focused on its phase.

Why Separate Sessions?

Planning conversations fill context with Q&A that you don’t need during implementation. Starting fresh for implementation gives Claude maximum context for code writing.

AskUserQuestion Tool

In plan mode, Claude uses the AskUserQuestion tool to present structured questions.

Question Types

Single choice:

┌─────────────────────────────────────────┐
│ Which database?                          │
│                                          │
│  ○ PostgreSQL                            │
│  ○ MySQL                                 │
│  ○ MongoDB                               │
│  ○ SQLite                                │
└─────────────────────────────────────────┘

Multiple choice:

┌─────────────────────────────────────────┐
│ Which features needed? (select all)      │
│                                          │
│  ☐ User registration                     │
│  ☐ Password reset                        │
│  ☐ Email verification                    │
│  ☐ Two-factor authentication             │
└─────────────────────────────────────────┘

Open-ended:

┌─────────────────────────────────────────┐
│ What's your email provider?              │
│                                          │
│  Your answer: _______________________    │
│                                          │
│  (e.g., "SendGrid", "AWS SES")          │
└─────────────────────────────────────────┘

Effective Planning Sessions

1. Start Broad

> add a recommendation engine

# Good: Let Claude explore the problem space
# Claude will ask about: algorithms, data sources, performance, etc.

2. Provide Context

> add search functionality
> context: Django REST API, PostgreSQL database, 100k products
> users want to filter by price, category, brand

Context helps Claude ask better questions.

3. Think Out Loud

> add analytics
> I'm thinking either Google Analytics or a self-hosted solution
> concerned about: GDPR compliance, cost, data ownership

Sharing your thoughts helps Claude understand priorities.

4. Ask for Tradeoffs

> compare approaches for implementing real-time chat
> I need to understand: complexity, scalability, cost

5. Request Examples

> show me example API requests and responses in the spec
> include: happy path, error cases

Refining Plans

Plans rarely perfect on the first try. Iterate:

Claude: [presents plan]

You: this looks good but change the caching TTL to 1 hour instead of 5 minutes

Claude: Updated the spec with 1-hour TTL. Anything else?

You: also add a manual cache invalidation endpoint

Claude: Added POST /api/admin/cache/clear to the spec. Ready to implement?

You: yes, proceed

Saving Specifications

Always save good specs:

> save this specification to docs/specs/notification-system.md

Benefits:

• Reference during implementation
• Share with team for review
• Use in future sessions
• Document decisions

Common Mistakes

❌ Using Plan Mode for Everything

# Overkill
> [plan mode] add a comment to this function

Fix: Reserve plan mode for genuinely complex work.

❌ Insufficient Context

# Too vague
> add authentication

# Better
> add authentication
> context: Flask API, PostgreSQL, 5000 daily users
> must support: password login, OAuth, API keys

❌ Skipping the Spec Save

# Bad: Spec only exists in conversation
> [plan mode creates great spec]
> implement it
# [spec lost if session crashes]

# Good: Save it
> save the spec to docs/specs/auth.md
> implement it

❌ Not Reviewing Before Implementation

# Risky
Claude: [30-page spec]
You: implement it
# [hope everything was correct]

# Safer
Claude: [presents spec]
You: let me review...
You: section 3 needs adjustment
Claude: [updates]
You: now implement

Plan Mode + Other Features

With Task Tracking

> [plan mode] add user dashboard

[Claude creates spec and task breakdown]

Specification created. Implementation will involve:

○ Create dashboard layout component
○ Add user statistics API endpoint
○ Implement data visualization
○ Add real-time updates via WebSocket
○ Write tests
○ Update documentation

Shall I proceed?

With Subagents

> [plan mode] refactor the authentication system

[After planning]

I can use subagents to parallelize the implementation:
- Subagent 1: Refactor backend auth
- Subagent 2: Update frontend auth flow
- Subagent 3: Update tests

Proceed with parallel implementation?

Exiting Plan Mode

Three ways to exit plan mode:

1. Approve the plan

   > this looks good, implement it
   # Claude switches to normal mode and implements

2. Keyboard shortcut

   Alt+M / Option+M to cycle back to normal mode

3. Explicit command

   > switch to normal mode

Summary

Plan mode is for thinking before doing:

• Activate with Alt+M or explicit request
• Claude asks clarifying questions (AskUserQuestion tool)
• Creates detailed specifications
• You approve, refine, or reject
• Then implementation begins

Use plan mode when:

• Requirements are unclear
• Multiple approaches possible
• Decisions have significant impact
• Want to review before committing

Skip plan mode when:

• Task is simple and clear
• Quick fixes or one-liners
• Exploring/prototyping

Tip

The best engineers spend 30% of time planning and 70% executing. Plan mode helps you do that with Claude.