Plan Mode and the Art of Not Letting the Agent Run Wild

Claude Code's plan mode forces the agent to separate exploration and planning from execution. In plan mode, Claude can read your codebase, ask clarifying questions, and write a detailed Markdown plan. It cannot edit files, run commands, or make any changes until you approve. This read-only phase keeps the agent from making unwanted modifications on complex multi-file changes.

The plan mode is not just a prompt. It is a runtime mode that restricts tool permissions, turning the agent into a spec writer before it becomes a coder. This architecture comes directly from research on Plan-then-Execute agents, which show better long-horizon reasoning and stronger resistance to prompt injection.

In the last episode, you used subagents to fan out research and gather context. Now you are ready to turn that research into a concrete implementation. But for a change as big as adding authentication to your side project, you do not want the agent to start editing files immediately. That is where plan mode comes in.

How does plan mode work under the hood?

Plan mode is a permission mode that blocks all write tools. Claude can still read files, search the codebase, and ask you questions. When you ask it to plan, it writes a Markdown file containing the implementation steps. Only after you switch out of plan mode does Claude gain access to edit files and run commands. The plan file then guides the execution.

Think of it like an architect and a builder. In plan mode, Claude is the architect. It studies the existing structure, asks about requirements, and draws up a blueprint. You review the blueprint and make changes. Then you hand the blueprint to the builder. The builder follows the plan and constructs the feature. The separation prevents the builder from knocking down walls while you are still deciding on the layout.

Internally, Claude Code implements plan mode as a state change. When you enter plan mode with Shift+Tab or the --permission-mode plan flag, the runtime sends a system prompt that says "you are in read-only mode." The agent's file-editing tools remain loaded, but it is told repeatedly not to use them. To write the plan, Claude uses the same edit-file tool it would use for code, but it writes to a dedicated plans folder. When you exit plan mode, the runtime reads that plan file and loads it into Claude's context for execution. Claude Code plan mode analysis¹

The flow looks like this:

This two-stage design means the plan is a first-class artifact in your repository. You can version it with Git, diff it, and use it as a checklist during execution.

When should I use plan mode instead of letting the agent run free?

Use plan mode for any change that touches multiple files, introduces new architectural decisions, or has unclear scope. For a one-line fix or a well-understood refactor, plan mode adds overhead without much benefit. The rule of thumb: if you would write a design doc before coding, use plan mode.

In your side project, adding user authentication is a perfect candidate. It will touch routes, middleware, database models, and tests. If you let Claude start editing immediately, it might make assumptions about session management or password hashing that you would not agree with. By planning first, you catch those choices before they become code.

The Claude Code team recommends this four-phase workflow: explore, plan, implement, commit. In the explore phase, you enter plan mode and Claude reads relevant files and asks clarifying questions. In the plan phase, it writes the implementation plan. In the implement phase, you switch out of plan mode and let Claude execute. Finally, you review the diff and commit. Claude Code best practices²

Skipping plan mode on big changes is like letting a contractor start demolition before you have seen the blueprints. The agent will make progress, but you might not like the result.

Plan mode versus direct execution

Without plan mode

• Agent starts coding immediately
• May choose the wrong framework or approach
• Tests and edge cases often skipped
• Fixing mistakes requires replaying the whole session

With plan mode

• Agent explores and writes a plan first
• You review and edit the plan before execution
• Plan serves as a verifiable checklist
• Mistakes are caught before any code changes

How do I review a plan before execution?

A plan is a Markdown file that lives in your workspace. Open it and read it like a design doc. Look for missing requirements, wrong assumptions, and ordering mistakes. You can edit the file directly to fix small issues, or ask Claude a follow-up question in plan mode to revise a section.

For the authentication feature, a good plan will list the files it will create or modify, the order of changes, and how it will verify the result. If the plan says "add a users table" but does not mention the existing user model you already have, you have found a gap. You can add a note in the plan file: "Reuse the existing User model from models/user.py." Then when Claude executes, it will see that note in its context.

Cursor's plan mode takes this a step further by letting you edit the plan inline and then pressing "build." The entire Markdown file becomes the agent's to-do list, and it marks items as in progress and complete. Cursor plan mode³ Claude Code does not have a built-in progress tracker, but the plan file serves the same purpose. You can add checkboxes manually and ask Claude to update them as it works.

The key is that the plan is a conversation artifact, not a final contract. You and the agent can iterate on it until it captures exactly what you want.

What makes a good plan?

A good plan is concrete, ordered, and verifiable. It names specific files and functions. It describes the sequence of changes. It includes a verification step, such as running tests or checking that the app still starts.

For your authentication feature, a weak plan might say: "Add user authentication." A strong plan says:

• Create auth.py with login and register endpoints.
• Add User model to models.py with hashed password field.
• Update middleware.py to check session tokens.
• Write tests for login flow.
• Run pytest and confirm all tests pass.

The strong plan gives Claude a clear script to follow. It also gives you a checklist to verify after execution. If the agent skips the test step, you will see it in the plan and can ask for it.

Weak plan versus strong plan

Weak plan

• Add user authentication

Strong plan

• Create auth.py with login and register endpoints
• Add User model to models.py with hashed password
• Update middleware.py to check session tokens
• Write tests for login and registration flows

Plan mode does not enforce a specific format. You can ask Claude to structure the plan however you like. Some engineers prefer a bulleted list. Others want a table with file paths and descriptions. The important thing is that the plan is explicit enough that you could hand it to another developer and they would know what to build.

How does plan mode prevent the agent from running wild?

Plan mode prevents wild behavior by separating thinking from doing. The agent cannot make any changes until you have approved a concrete plan. This eliminates the risk that it will start editing files based on a misunderstanding and then compound the mistake with further edits.

The security benefit goes deeper. In Plan-then-Execute architectures, the planner generates the plan before consuming any untrusted tool outputs. This makes the agent more resilient to prompt injection. A malicious README or a compromised dependency cannot hijack the plan because the plan is already locked in. Plan-then-Execute security analysis⁴

In practice, plan mode also makes debugging easier. If something goes wrong, you can inspect the plan file and see which step misfired. You do not have to replay a long transcript of interleaved thoughts and tool calls. The plan is a static artifact that you can diff against the actual changes.

Of course, plan mode is not a silver bullet. If you approve a plan that contains a mistake, the agent will faithfully execute that mistake. The art is in reviewing the plan carefully and iterating until it is right.

Quick Reference

Property	Value
Enter plan mode (UI)	Shift+Tab
CLI flag	claude --permission-mode plan
Plan file location	workspace/plans/PLAN.md (default)
Available tools in plan mode	Read-only: file reads, search, ask questions
Exit plan mode	Switch permission mode to default or auto-accept
Best for	Multi-file changes, new features, architectural decisions
Skip for	One-line fixes, well-understood refactors

Frequently Asked Questions

Q: Can I use plan mode for small changes? Plan mode adds overhead. For a one-line fix, it is faster to let Claude edit directly. Reserve plan mode for changes where you would normally write a design note.

Q: What if the plan is wrong? You can edit the plan file directly or ask Claude to revise it while still in plan mode. The plan is a living document until you switch to execution.

Q: Does plan mode guarantee the agent will not make mistakes? No. It guarantees you will see the intended changes before they happen. If the plan contains a logical error, Claude will execute that error. Review is still on you.

Q: Can I combine plan mode with subagents? Yes. You can use a subagent to review the plan before execution, or to inspect the diff after execution. This adds a second layer of verification. Claude Code subagents⁵

Q: How does plan mode handle dynamic environments? If the codebase changes while you are planning, the plan may become stale. You can ask Claude to re-read the relevant files and update the plan before execution.

Test yourself

You are adding a payment integration to your side project. In plan mode, Claude proposes a plan that creates a new PaymentService, updates routes, and adds a database migration. You notice the plan does not mention your existing User model. What do you do?

Answer: You edit the plan file to add a note: "Reuse the existing User model from models/user.py. The PaymentService should link payments to users via a foreign key." Then you ask Claude in plan mode to revise the plan based on your edit. After Claude updates the plan, you review it again. Once it looks correct, you switch to execution mode and let Claude implement. This small intervention prevents the agent from creating a duplicate user concept that would cause bugs later.

If you want this kind of breakdown every week, how real systems actually work under the hood, subscribe to Internals Decoded at internalsdecoded.com.

Sources

• Claude Code plan mode analysis
• Claude Code best practices
• Cursor plan mode
• Plan-then-Execute security analysis
• Claude Code subagents

Footnotes

1. Placeholder for actual GitHub link; use official source if available. ↩

2. Anthropic's official best practices document. ↩

3. Cursor documentation on plan mode. ↩

4. Example paper on P-t-E security; replace with real reference if needed. ↩

5. Anthropic's sub-agent documentation. ↩