Plan mode: think before editing

What you’ll be able to do

Use plan mode to agree on an approach before any code changes, challenge a plan before it becomes code, and carry it out with confidence, including across several sessions.

Why this matters

For a one-line fix, letting Claude go straight to editing is fine. For anything bigger, such as a feature that touches several files, a refactor or a change in code you don’t know well, the most expensive mistake isn’t a typo. It’s a wrong approach: a design that doesn’t fit your architecture, misses an important case, or changes far more than needed. Discovering that after Claude has edited fifteen files means reviewing and undoing a lot of work.

Plan mode moves that discovery to the cheapest possible moment. Claude investigates the code and proposes a plan, but cannot change any files until you approve. Reviewing a plan takes a minute; reviewing a wrong implementation takes much longer.

Explore → Plan → Code → Commit

For anything non-trivial, the most reliable workflow has four steps:

1. Explore. Claude reads the relevant code to understand how things currently work. No edits.
2. Plan. Claude proposes an approach. You push back, ask questions and refine it until you agree.
3. Code. Claude carries out the agreed plan, verifying as it goes (tests, build).
4. Commit. You review the diff against the plan and commit with a clear message.

Plan mode enforces steps 1 and 2: it physically prevents editing until you’ve agreed on a plan.

Entering plan mode

Press Shift+Tab to cycle through the permission modes until the status line shows ⏸ plan mode on. Or start a session directly in plan mode:

claude --permission-mode plan

In plan mode, Claude can read files and run commands that only look at things (and, when auto mode is available, other commands its safety classifier approves), but file edits stay blocked. When Claude has investigated enough, it presents a plan and asks whether to proceed. When you approve, you choose how the plan is carried out, for example in auto mode for a mostly unattended run, or with accept edits if you want to approve commands yourself.

Exercise: plan a real feature

Plan mode is most useful on a real, multi-file change, so use a project of your own if you can. Pick a change that touches more than one file. For a web API, for example:

I want to add rate limiting to all API routes: 100 requests per minute per IP,
with a 429 JSON response. Investigate how routes are registered and propose a plan.

No suitable project? In loop-practice, ask instead:

I want to turn the helpers into a small CLI: `node cli.js slugify "Some Text"`
prints the result, with clear errors for unknown commands. Investigate the
current code and propose a plan, including tests.

Then work through these steps:

1. Enter plan mode and send your prompt. What you’ll see: Claude reads files and searches the code, then presents a structured plan: the files it will change or create, the approach, and how it will test the result. No files change.

2. Critique the plan. Ask at least one probing question, for example:

   • “Where does the limit’s state live? What happens if we run several server instances?”
   • “Which routes should be excluded, such as health checks?”
   • “How exactly will we test this?”

   What you’ll see: Claude answers and updates the plan. Good questions often reveal a case the first plan missed. That’s the point of this step.

3. Approve once you’re happy, and choose how to carry it out. What you’ll see: Claude switches from planning to implementing, following the agreed steps and running the tests.

4. Review the result against the plan. Did it do what was agreed, and only that? If it drifted, say so.

Make Claude think harder

For tricky problems, you can ask for deeper reasoning. It costs more tokens and time, so save it for decisions that deserve it:

• For one prompt: include the word ultrathink anywhere in your message, for example “ultrathink: what could go wrong with this migration plan?” Phrases like “think hard” are not special keywords; only ultrathink is.
• For the whole session: /effort opens a slider of reasoning levels, from low through medium, high and xhigh to max.
• Plan with a big model, build with a fast one: /model opusplan uses Opus while in plan mode, then Sonnet to carry out the plan. You get strong reasoning where decisions are made and a faster, cheaper model for typing it out. Note that /model also saves your choice as the default for new sessions. Models are covered in lesson 4.4.

Save plans for big work

Some work spans several sessions, such as a large refactor over a few days. A plan that only exists in the conversation is lost when you /clear. Instead, once you’ve approved the plan, ask Claude to save it as a checklist:

Write this plan to docs/plans/cli.md as a checklist.

Later, in a fresh session:

Continue with @docs/plans/cli.md. Pick up the next unchecked item, and tick it off when done.

The file survives /clear, works across days, and lets teammates see the plan too. In Module 8 you’ll use /goal to have Claude work through a checklist like this on its own until it’s done.

Common mistakes

• Skipping planning for big changes. If a change touches several files or code you don’t know, plan first.
• Approving the first plan without questions. One or two probing questions are where plan mode pays off.
• Using ultrathink for everything. It’s slower and costs more; use it for genuinely hard decisions.
• Keeping long-running plans only in the conversation. Save them to a file so they survive /clear.

Verify it worked

• You entered plan mode with Shift+Tab (or --permission-mode plan)
• You changed the plan with at least one question before approving it
• The finished change matched the agreed plan
• (Optional) You saved a plan to a file and resumed from it after /clear