Plan Mode in Claude Code - Think Before You Build with AI

I asked Claude to add soft deletes to an existing ASP.NET Core API. No planning, no constraints — just “add soft deletes to all entities.” Fifteen minutes later, I had a mess: Claude had modified 14 files, introduced a global query filter that broke three existing endpoints, changed the DbContext in ways that conflicted with my migration history, and added a DeletedAt column to tables that didn’t need it.

I spent the next 30 minutes undoing everything. Manually. One file at a time.

The fix wasn’t a better prompt. The fix was planning before coding. And that’s the single most underrated habit when working with AI coding assistants.

This isn’t a feature tour of Claude Code’s Plan Mode — features change, keyboard shortcuts get remapped, UIs get redesigned. What doesn’t change is this: the developers who plan before they build with AI consistently ship better code, faster, with fewer do-overs.

Claude Code happens to have the best planning workflow I’ve used. Let me show you how I use it.

If you’re looking at where AI-assisted development fits into the bigger picture of becoming a proficient .NET developer, check out the full roadmap:

Let’s get into it.

Why Planning Is the Most Underrated AI Coding Habit

Here’s the pattern I see with developers who are new to AI coding assistants:

1. They type a vague prompt like “add authentication to my API”
2. The AI starts writing code immediately — fast, confident, and wrong in subtle ways
3. They correct one thing, the AI introduces another issue
4. Three corrections later, the context is polluted with failed approaches
5. They give up and start over, having wasted 30+ minutes

Sound familiar? Haven’t we all faced this at some point?

The problem isn’t the AI. The problem is that AI coding assistants are too eager to execute. They’re trained to be helpful, which means they start writing code the moment you give them a direction. Without constraints, they make assumptions — about your architecture, your patterns, your preferences — and those assumptions compound into a cascade of wrong decisions.

I’ve been loosely tracking my sessions over the past few months. The pattern is clear: when I skip planning, I end up redoing the task from scratch roughly 40% of the time. That’s not just lost time — it’s lost tokens, lost momentum, and lost patience.

Planning flips this dynamic. Instead of letting the AI sprint in a random direction, you force it to:

• Read your codebase first
• Ask clarifying questions
• Propose an approach
• Wait for your approval before touching a single file

This works with any AI coding tool. But Claude Code makes it practical with a dedicated Plan Mode that enforces read-only analysis before execution.

The rule I follow: If I can describe the exact diff in one sentence, I skip the plan. If I can’t, I plan first. This one rule has saved me more time than any prompt engineering technique.

What Is Plan Mode in Claude Code?

Plan Mode is a read-only operating mode in Claude Code where Claude can analyze your entire codebase, ask clarifying questions, and generate a detailed implementation plan — but cannot modify files, run commands, or execute any code. It separates thinking from doing.

In Plan Mode, Claude has access to these read-only tools:

What it cannot do: write files, edit files, run shell commands, execute tests, or make any changes to your project. Claude is forced to think, not act.

This matters because Claude Code’s Explore Subagent — a Haiku-powered specialist — automatically activates during Plan Mode to efficiently search your codebase while saving context tokens. You get thorough research without burning through your main context window.

Plan Mode vs Normal Mode vs Auto-Accept Mode

Claude Code has three operating modes, and understanding when to use each one is critical:

The workflow that Boris Cherny (the creator of Claude Code) uses himself: start in Plan Mode, go back and forth until the plan is right, then switch to Auto-Accept and let Claude execute. Most of his sessions begin in Plan Mode.

How to Enter Plan Mode

There are multiple ways to activate Plan Mode depending on your workflow:

Keyboard Shortcut — Shift+Tab

Press Shift + Tab twice to cycle through the three modes. The first press switches to Auto-Accept Mode (you’ll see ⏵⏵ accept edits on), the second press activates Plan Mode (you’ll see ⏸ plan mode on at the bottom of your terminal).

Press Shift + Tab again to cycle back to Normal Mode.

Windows users: If Shift + Tab only toggles between Normal and Auto-Accept modes and skips Plan Mode entirely, use Alt + M instead. This is a known issue on some Windows terminal configurations. If neither works, check your terminal key binding configuration.

The /plan Command

Starting with Claude Code v2.1.0, you can type /plan directly in the prompt to enter Plan Mode without the keyboard shortcut. This is especially useful if you’re already mid-conversation and want to switch to planning.

CLI Flag — Start in Plan Mode

To launch a new Claude Code session that begins in Plan Mode:

claude --permission-mode plan

This is my preferred approach for complex tasks. I know I’m going to plan first, so I start in the right mode from the beginning.

Headless Plan Mode

For scripted or CI workflows, combine Plan Mode with headless mode:

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

Set Plan Mode as Your Default

If you find yourself starting in Plan Mode more often than not, make it the default:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

The 4-Phase Workflow: Explore, Plan, Implement, Commit

Anthropic’s official best practices recommend a structured 4-phase workflow. This is the pattern I follow for every non-trivial task:

Phase 1: Explore (Plan Mode)

Read the relevant code. Understand the current state before proposing changes.

Read the /src/Features/Products directory and understand how
the existing product endpoints are structured. Also look at
how pagination is handled in any existing endpoint.

Claude reads files, searches patterns, and builds understanding — all without modifying anything. This phase is critical because it prevents Claude from making assumptions about your architecture.

Phase 2: Plan (Plan Mode)

Ask Claude to create a detailed implementation plan based on what it learned.

I want to add advanced filtering and sorting to the Products
endpoint. Create a detailed plan. What files need to change?
What's the implementation order? What are the edge cases?

Claude generates a structured plan with file changes, implementation order, and considerations. This is where Ctrl+G becomes your best friend (more on that in the next section).

Phase 3: Implement (Normal or Auto-Accept Mode)

Switch out of Plan Mode (Shift + Tab) and let Claude execute the plan.

Implement the plan. Start with the query parameter models,
then the filter extensions, then update the endpoint.
Run the build after each step.

Because Claude already has context from the planning phase, execution is faster and more accurate. It knows which files to touch, in what order, and what constraints to respect.

Phase 4: Commit (Normal Mode)

Have Claude create a descriptive commit and optionally a pull request.

Commit with a descriptive message and open a PR

This workflow is directly from Anthropic’s documentation, and it mirrors how the Claude Code team uses the tool internally. The key insight: phases 1 and 2 (Explore + Plan) are the cheapest in terms of tokens and the most valuable in terms of outcome.

Real Walkthrough: Planning an ASP.NET Core Feature

Let me walk you through a real Plan Mode session. I’m going to add advanced filtering, sorting, and cursor-based pagination to an existing Products endpoint in an ASP.NET Core Minimal API.

Step 1: Enter Plan Mode and Explore

I start Claude Code with Plan Mode:

claude --permission-mode plan

My first prompt asks Claude to understand the existing code:

Read the Products feature directory and understand:
1. How the current GetProducts endpoint works
2. What the Product entity looks like
3. How the DbContext is configured
4. Whether any other endpoint already implements pagination

Also check my CLAUDE.md for project conventions.

Claude reads through the relevant files, finds the existing endpoint structure, notices I’m using Minimal APIs with the Carter library pattern, identifies the EF Core 10 DbContext, and sees that no endpoint currently implements pagination.

It also reads my CLAUDE.md and picks up that I use .slnx format, Scalar instead of Swagger, and follow a specific project structure.

Step 2: Ask Claude to Plan

Now I ask for the implementation plan:

Plan the implementation for adding advanced filtering, sorting,
and cursor-based pagination to the GetProducts endpoint.

Requirements:
- Filter by: name (contains), category (exact), price range (min/max), isActive
- Sort by: name, price, createdDate (ascending/descending)
- Cursor-based pagination with configurable page size
- Return pagination metadata in response headers

Use the patterns from my existing codebase. Don't introduce
new libraries — use what's already in the project.

Claude asks clarifying questions through the AskUserQuestion tool — this is a newer feature where Claude presents multiple-choice options instead of open-ended questions:

Claude asks: “For cursor-based pagination, which approach do you prefer?”

• A) Keyset pagination using the primary key (most performant)
• B) Offset-based with cursor encoding (more flexible)
• C) Let me explain my preferred approach

I select option A. Claude then asks about the filter combination logic (AND vs OR), default sort order, and maximum page size. After my answers, it generates a plan.

Step 3: Review and Edit the Plan

Claude produces a structured plan. Here’s what it looks like (abbreviated):

## Implementation Plan: Advanced Filtering for Products

### Files to Create
1. `Features/Products/Models/ProductFilter.cs` — Query parameter model
2. `Features/Products/Extensions/ProductQueryExtensions.cs` — IQueryable extensions

### Files to Modify
1. `Features/Products/GetProducts.cs` — Update endpoint to accept filters
2. `Features/Products/Models/ProductResponse.cs` — Add pagination metadata

### Implementation Order
1. Create the filter model with validation
2. Create IQueryable extension methods for filtering/sorting
3. Implement cursor-based pagination logic
4. Update the endpoint to wire everything together
5. Test with Scalar API explorer

### Edge Cases
- Empty filter parameters should return unfiltered results
- Invalid sort column should fall back to default (CreatedDate desc)
- Cursor for deleted records should skip to next valid record

This is where I press Ctrl+G to open the plan in my default text editor. I can edit it directly — remove steps I don’t want, add constraints Claude missed, reorder priorities. Any changes sync back to Claude’s context automatically.

In this case, I add a note: “Don’t add a separate pagination middleware — keep the pagination logic in the query extension methods. I want this self-contained per feature.” I also remove a step where Claude planned to add a generic PaginatedResponse<T> wrapper — I want feature-specific response models, not generic abstractions.

PRO TIP: Don’t try to describe plan edits through conversation. Press Ctrl+G, edit the plan file directly, and save. It’s faster and more precise. You can also use /plan open to open the plan file from the filesystem.

Step 4: Switch to Execution

With the plan reviewed and edited, I press Shift + Tab to switch to Auto-Accept Mode and tell Claude to implement:

Implement the plan. After each file, run dotnet build to verify
there are no compilation errors.

Claude executes step by step, referencing the plan it created. Because it already explored the codebase and I already approved the approach, there are no surprises. No rogue global query filters. No unnecessary abstractions. No modifications to files that shouldn’t be touched.

The whole implementation takes about 12 minutes. Without planning, this same task previously took me 35+ minutes with two do-overs.

Editing Plans Like a Pro

Plan editing is where the real power is. Most developers don’t realize they can directly modify Claude’s plans before execution.

Ctrl+G — Open in Your Editor

When Claude generates a plan in Plan Mode, press Ctrl+G to open it in your default text editor (VS Code, Vim, Notepad++ — whatever you’ve configured). Edit the plan, save, close — and Claude picks up your changes automatically.

What I typically edit:

• Remove steps that add unnecessary abstractions
• Add constraints like “don’t modify the existing migration files”
• Reorder priorities to implement the most critical piece first
• Add test requirements like “write a test for the cursor edge case before implementing it”

/plan open — Filesystem Access

Claude writes plan files to your filesystem. By default, they land in ~/.claude/plans/ with auto-generated random names like jaunty-petting-nebula.md or calm-silver-fox.md. Not exactly easy to find later.

Running /plan open opens the current plan file directly in your editor, regardless of where it’s stored. Any changes you make are automatically synced back to Claude’s context.

Where Plans Are Stored (and Why You Should Care)

The default ~/.claude/plans/ location has two problems: the random file names make it impossible to find a specific plan later, and the global directory means plans from every project are mixed together.

My recommendation: store plans in your project directory and commit them to version control. Plans are decision records — they capture why you built something a certain way, not just what you built. That context is invaluable during code reviews, onboarding, and when you revisit the code six months later wondering “why did I do it this way?”

Configure project-local plan storage in .claude/settings.json:

{
  "plansDirectory": "./docs/plans"
}

Relative paths resolve from the workspace root. Claude creates the directory automatically if it doesn’t exist. Now your plans live alongside your code, with meaningful file names you can control.

What I do in practice:

• Store plans in docs/plans/ and commit them to git
• After Claude generates a plan with a random name, I rename it to something descriptive like 2026-02-25-add-product-filtering.md before execution
• For significant features, the plan becomes the PR description — copy-paste the plan into the PR body so reviewers see exactly what was planned vs what was built
• For quick tasks, I don’t bother saving the plan at all — it served its purpose during the session

PRO TIP: Add plansDirectory to your project’s .claude/settings.json (not the user-level one). This way every team member’s plans go to the same place when they clone the repo.

When to Edit vs When to Reprompt

When to Plan and When to Skip

Not every task needs a plan. Over-planning simple tasks wastes time just as much as under-planning complex ones. Here’s the decision framework I’ve built from months of daily usage:

The One-Sentence Rule

If you can describe the exact diff in one sentence, skip the plan. This comes directly from Anthropic’s official best practices:

“Planning is most useful when you’re uncertain about the approach, when the change modifies multiple files, or when you’re unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.”

Decision Matrix: Real .NET Scenarios

My Rule of Thumb

• 1-2 files, obvious change → Normal Mode or Auto-Accept
• 3+ files, any ambiguity → Plan Mode
• Architectural decision involved → Always Plan Mode
• Unfamiliar codebase → Always Plan Mode

Plan Mode + CLAUDE.md: The Power Combo

Here’s something none of the other guides mention: Plan Mode output quality is directly proportional to how good your CLAUDE.md file is.

When Claude enters Plan Mode and reads your codebase, it also reads your CLAUDE.md. If that file tells Claude about your architecture, coding standards, preferred patterns, and testing approach — the plan it generates will respect all of those constraints.

Without CLAUDE.md, Claude might plan to:

• Add a generic repository layer (when you use CQRS)
• Use Swagger (when you use Scalar)
• Create a .sln file (when you use .slnx)
• Use DateTime.Now (when your standards require DateTimeOffset.UtcNow)

With a well-crafted CLAUDE.md, Claude’s plan already follows your conventions from the start. Zero corrections needed.

This is why I recommend writing your CLAUDE.md before your first Plan Mode session on a project. The 30 minutes you spend writing it saves hours of plan corrections.

What to Put in CLAUDE.md for Better Plans

Focus on things Claude can’t infer from reading your code:

# Architecture
- Minimal APIs with Carter library pattern (not controllers)
- Feature-folder structure: Features/[Feature]/[Endpoints, Models, Extensions]
- No generic repository pattern — query directly with DbContext

# Testing
- xUnit + FluentAssertions + NSubstitute
- Integration tests use WebApplicationFactory
- Run: dotnet test --no-build

# Conventions
- Scalar for API docs (not Swagger)
- .slnx solution format
- DateTimeOffset.UtcNow (never DateTime.Now)
- CancellationToken on every async method

These constraints are invisible to Claude without CLAUDE.md — but they’re the exact things that cause plans to go sideways when missing.

Tips from Daily Usage

After months of using Plan Mode daily across .NET projects, here are the practices that have made the biggest difference:

Keep Planning Scope Small

Plan what you’ll implement in the next 30 minutes or less. Large plans that cover an entire feature across 20 files lose coherence because Claude’s context fills up. Instead, plan in chunks:

• First plan: the data model and migrations
• Second plan: the endpoint and validation
• Third plan: the tests

Use Extended Thinking During Planning

Press Alt + T (Windows/Linux) or Option + T (macOS) to enable extended thinking while in Plan Mode. This gives Claude more room to reason through architectural decisions, edge cases, and tradeoffs. With Opus 4.6’s adaptive reasoning, the model dynamically allocates thinking depth based on complexity.

This is especially valuable when you’re asking Claude to evaluate multiple approaches — “Should I use keyset pagination or offset pagination for this endpoint?”

Use Subagents for Deep Investigation

When you need Claude to research a large part of your codebase during planning, tell it to use subagents:

Use subagents to investigate how our authentication middleware
works and what claims are currently available in the pipeline.

Subagents run in separate context windows and report back summaries. Your main session stays clean for the actual planning work, and you don’t burn your primary context on exploration.

After Two Failed Corrections, Start Fresh

If you’ve corrected Claude’s plan twice and it’s still wrong, the context is cluttered with failed approaches. Don’t keep going — run /clear and write a better initial prompt that incorporates what you learned from the first attempt. A fresh session with a precise prompt almost always outperforms a long session with accumulated corrections.

Preserve Plan Context During Long Sessions

If your session is getting long and you’re worried about context compaction losing important planning context, use:

/compact Focus on the Products filtering plan and implementation decisions

This tells Claude what to prioritize when compacting, ensuring your plan survives context management.

When Plan Mode Isn’t Enough — Scale with Agent Teams

For truly large features that span multiple bounded contexts or require parallel work streams, a single Plan Mode session won’t cut it. That’s where Claude Code Agent Teams come in — multiple Claude instances coordinating through a shared task list.

Key Takeaways

• Plan before you code with AI — This is the single highest-leverage habit. It applies to any AI coding assistant, not just Claude Code.
• Use the one-sentence rule — If you can describe the diff in one sentence, skip the plan. If you can’t, plan first.
• Follow the 4-phase workflow — Explore → Plan → Implement → Commit. It’s what Anthropic recommends and what the Claude Code creator uses daily.
• Edit plans directly — Press Ctrl+G to open the plan in your editor. Don’t describe edits through conversation.
• CLAUDE.md makes plans 10x better — The time you invest in writing a good CLAUDE.md pays back in every Plan Mode session.

Troubleshooting Common Plan Mode Issues

Shift+Tab Doesn’t Cycle to Plan Mode on Windows

This is a known issue on some Windows terminal configurations. Shift + Tab may only toggle between Normal and Auto-Accept, skipping Plan Mode entirely. Fix: Use Alt + M instead, or type /plan directly in the prompt. If neither works, check your terminal key binding configuration — some terminals intercept Shift + Tab before Claude Code receives it.

Plan Mode Lost After Context Compaction

In earlier versions, switching to Plan Mode could be silently lost when Claude Code automatically compacted the conversation to free up context space. Fix: This was fixed in v2.1.47. Update to the latest version with npm update -g @anthropic-ai/claude-code. If you’re on the latest version and still experiencing this, re-enter Plan Mode with /plan after compaction triggers.

Claude Ignores Plan Constraints During Execution

You approved a plan, switched to execution, and Claude went off-script — adding files or patterns the plan didn’t include. This usually happens when the plan was too vague or the execution prompt didn’t reference it. Fix: After switching out of Plan Mode, explicitly say “Implement the plan exactly as written. Don’t add anything that isn’t in the plan.” Also, use Ctrl+G to make your plan constraints explicit before switching modes.

Plan Files Have Random Names and Are Hard to Find

By default, plan files go to ~/.claude/plans/ with auto-generated names like jaunty-petting-nebula.md. This makes them nearly impossible to locate after a session ends. Fix: Set plansDirectory in your project’s .claude/settings.json to a project-local path like ./docs/plans. Then rename plan files to something meaningful (e.g., 2026-02-25-add-filtering.md) after Claude generates them. See the “Where Plans Are Stored” section above for the full setup.

Claude’s Plan Is Too Generic or Misses Your Patterns

Claude generates a plan that looks reasonable but doesn’t match your project’s architecture or conventions. Fix: This almost always means your CLAUDE.md is missing or incomplete. Claude can’t respect conventions it doesn’t know about. Write a CLAUDE.md with your architecture, testing, and code conventions before your next Plan Mode session.

Summary

The principle is simple: think before you build. AI coding assistants are powerful, but that power goes to waste — or worse, causes damage — without a plan.

Claude Code’s Plan Mode is the best implementation of this principle I’ve used. The 4-phase workflow (Explore → Plan → Implement → Commit), combined with a good CLAUDE.md and the ability to edit plans with Ctrl+G, creates a development workflow that’s both faster and more predictable than letting AI just go.

Start your next session in Plan Mode. Force Claude to think first. Edit the plan. Then execute. You’ll be surprised how much smoother the build goes.

If you found this helpful, share it with your colleagues — and join the newsletter if you want my complete Plan Mode decision framework with 15+ .NET scenarios.

Happy Coding :)