Plan Mode and the Art of Not Letting the Agent Run Wild
When to plan first, how to review plans, and keeping control of big changes.
Claude Code's plan mode separates exploration and planning from execution. In plan mode, Claude reads your codebase, runs commands to explore, asks clarifying questions, and writes a detailed Markdown plan. It cannot edit your code until you approve that plan. This planning phase keeps the agent from making unwanted changes on complex multi-file work.
Plan mode is not just a prompt. It is one of Claude Code's permission modes, which you met in Part 1, and it changes what the runtime allows: the agent becomes a spec writer before it becomes a coder.
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?
In plan mode, Claude Code blocks edits to your source files. Claude can still read files, search the codebase, and ask you questions, and it can run shell commands to explore. Which commands run depends on your setup, according to the permission modes documentation: the built-in read-only commands such as ls and git status always run, and when auto mode is available, its classifier reviews other commands instead of prompting you; otherwise they ask first. When you ask Claude to plan, it writes a Markdown file with the implementation steps, and only after you approve that plan does Claude start editing.
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 keeps the builder from knocking down walls while you are still deciding on the layout.
To enter plan mode, press Shift+Tab until the status bar shows ⏸ plan mode on. Shift+Tab cycles through the modes (from auto mode, one press gives Manual, then accept edits, then plan), so it can take more than one press. You can also start a single prompt with /plan, or launch with claude --permission-mode plan. While Claude plans, it can hand codebase research to the built-in Plan subagent from Part 6, so the exploration output stays out of the main conversation.
When the plan is ready, Claude presents it and asks how to proceed. You choose one of three options:
- Yes, and use auto mode (it reads Yes, auto-accept edits when auto mode is not available to you): approve, and let Claude carry out the plan with few prompts.
- Yes, manually approve edits: approve, and review each edit as it happens.
- No, keep planning: stay in plan mode and tell Claude what to change.
Approving a plan exits plan mode and switches to the mode that option names. If you want to leave plan mode without approving anything, press Shift+Tab instead.
The flow looks like this:
Where does the plan live? By default Claude Code writes plan files to ~/.claude/plans/ in your home folder, outside the repository. If you want plans in git, where you can diff them and keep them as a record, set the plansDirectory setting to a folder in your project (the path is relative to the project root), or ask Claude to save a copy of the approved plan in the repo.
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. Anthropic's best practices guide puts the rule of thumb neatly: "If you could describe the diff in one sentence, skip the plan."
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 same guide recommends a four-phase workflow: explore, plan, implement, commit. In the explore phase, you enter plan mode and Claude reads the relevant files and answers your questions without making changes. In the plan phase, you ask it to write a detailed implementation plan. In the implement phase, you approve the plan and let Claude code against it, running the tests as it goes. Finally, you ask Claude to commit with a descriptive message.
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.
- Agent starts coding immediately
- May choose the wrong framework or approach
- Tests and edge cases often skipped
- Rolling back means undoing edits by hand or with /rewind
- Agent explores and writes a plan first
- You review and edit the plan before execution
- Plan serves as a verifiable checklist
- Most wrong assumptions are caught before code changes
How do I review a plan before execution?
Read the plan like a design doc. Look for missing requirements, wrong assumptions, and ordering mistakes. To fix something yourself, press Ctrl+G at the approval prompt: Claude Code opens the proposed plan in your text editor, and your edits are what Claude works from. For bigger changes, choose "No, keep planning" and tell Claude what to revise.
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 user model you already have, you have found a gap. Add a note to the plan: "Reuse the existing User model in api/src/models/user.ts." When Claude carries out the plan, it works from your note.
As Claude works through an approved plan, the plan itself is your checklist. Claude Code also has a task checklist you can show with Ctrl+T, but on the newest models it stays empty by default, because those models keep track of multi-step work without a written list; setting CLAUDE_CODE_ENABLE_TODO_TOOLS=1 turns the checklist tools back on. Either way, compare the finished work against the plan's steps.
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
api/src/handlers/auth.tswithloginandregisterendpoints. - Add a hashed password field to the
Usermodel inapi/src/models/user.ts. - Update
api/src/middleware/session.tsto check session tokens. - Write tests for the login and registration flows.
- Run
npm testand 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 against the plan and can ask for it.
- Add user authentication
- Create auth.ts with login and register endpoints
- Add a hashed password field to the User model
- Update the session middleware to check tokens
- Write tests, run npm test, and confirm they pass
Plan mode does not enforce a specific format. You can ask Claude to structure the plan any way you like. Some engineers prefer a bulleted list; others want a table with file paths and descriptions. What matters 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 edit your code until you have approved a concrete plan. That removes the risk that it starts editing files based on a misunderstanding and then compounds the mistake with further edits.
Plan mode also makes debugging easier. If something goes wrong, you can compare the plan with the actual changes and see which step misfired, instead of replaying a long transcript of thoughts and tool calls. And if the edits themselves go wrong, /rewind (or pressing Esc twice) takes the files back to an earlier checkpoint.
Of course, plan mode is not a silver bullet. If you approve a plan that contains a mistake, the agent will faithfully carry out that mistake. The art is in reviewing the plan carefully and iterating until it is right.
Quick Reference
| Property | Value |
|---|---|
| Enter plan mode | Shift+Tab until ⏸ plan mode on, or start a prompt with /plan |
| CLI flag | claude --permission-mode plan |
| Start in plan mode by default | "permissions": {"defaultMode": "plan"} in .claude/settings.json |
| What runs in plan mode | Reads, searches, questions, read-only commands; other commands go to the auto mode classifier or ask you |
| Plan file location | ~/.claude/plans/ (change it with plansDirectory) |
| Edit the proposed plan | Ctrl+G at the approval prompt |
| Exit plan mode | Approve the plan (auto mode or manual edits), or press Shift+Tab to leave without approving |
| Model for planning | opusplan uses Opus while planning and Sonnet while carrying out the plan |
| Best for | Multi-file changes, new features, architectural decisions |
| Skip for | Changes you could describe in one sentence |
Frequently Asked Questions
Q: Can I use plan mode for small changes? You can, but it 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? Choose "No, keep planning" at the approval prompt and tell Claude what to fix, or press Ctrl+G and edit the plan yourself. The plan is a living document until you approve it.
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 carry out that error. Review is still on you.
Q: Can I combine plan mode with subagents? Yes. Claude already uses the built-in Plan subagent for research while planning, and you can ask a subagent of your own to review the plan before you approve it, or to inspect the diff afterwards. That adds a second layer of verification.
Q: How does plan mode handle dynamic environments? If the codebase changes while you are planning, the plan may become stale. Ask Claude to re-read the relevant files and update the plan before you approve it.
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: Do not approve it yet. Either choose "No, keep planning" and tell Claude what is missing, or press Ctrl+G to open the plan in your editor and add the note yourself: "Reuse the existing User model in api/src/models/user.ts. Link each payment to a user through a foreign key." If you asked Claude to revise, read the new version carefully, because a fix in one step can shift others. Once the plan is right, approve it, choosing manual approval if you want to watch each edit of a payment change go by. This small intervention keeps the agent from creating a duplicate user concept that would cause bugs later.
Next: Memory and Sessions: Continuity Across Days. It shows what Claude Code remembers between sessions, and how to pick up yesterday's work.
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
- Choose a permission mode
- Best practices for Claude Code
- All settings
- Model configuration
- Create custom subagents
- Interactive mode
