Lesson 7.116 min · 5 cards · 8 exercises · 1 mission

Plan mode for bigger work

Move decisions before the code: when to plan, reading a plan for assumptions and scope, approving, editing with Ctrl+G, and keeping plans in the project.

Lesson 1.3 introduced plan mode as one of four modes. At level 7 the work gets bigger: a feature that touches three files, a refactor of a whole module. At that size, fixing a wrong turn after Claude has written the code costs far more than fixing a plan. This lesson uses plan mode on todo-api's issue #3 (the ?done= filter): when to plan, how to read a plan carefully, and how to approve it.

When to plan

Plan mode makes Claude research and propose, without editing yet. Claude reads files, runs commands to understand the code, writes a plan, and doesn't touch the code until you approve.

Worth it when:

  • the change touches several files, as issue #3 touches db.js, a route and the tests;
  • there are several ways to do it and you want to choose first;
  • you don't know that part of the code well;
  • getting it wrong is expensive: refactors, changes to data structures.

Not needed for small, clear jobs: a one-line fix, a changed message. Planning costs time and context too.

And when you don't yet know what you want, the docs suggest a step before that: ask Claude to interview you until it can write a spec into SPEC.md, then start a fresh session to build from that spec.

Getting into and out of plan mode

Three ways in:

  • Press Shift+Tab until the status bar shows ⏸ plan mode on.
  • Put /plan in front of a prompt, for that one prompt only.
  • Start the session with claude --permission-mode plan. To always start a project in plan mode, set "defaultMode": "plan" in .claude/settings.json.

In plan mode, Claude can still run commands to explore. If auto mode is available, its classifier reviews those commands instead of asking you; if not, commands outside the read-only set ask first. What Claude can't do is edit code.

When we tried it on issue #3, that's exactly what we saw: Claude read the files with git ls-files and cat, then used Write exactly once, to save the plan file. git status afterwards showed only the new plan file; not a single source file changed.

Getting out: press Shift+Tab when no approval prompt is open. Careful at the approval prompt: there, Shift+Tab approves the plan. To leave without approving, press Esc first.

Reading a plan carefully

The plan Claude wrote for issue #3 had five parts, and it's a layout worth expecting from every plan:

  1. Context: how the request was understood.
  2. Changes: what changes, file by file: src/db.js gains a parameter on list(), the GET / route checks ?done=, one line in README.md.
  3. Tests: which tests, with what data: four sample todos covering every mix of live/deleted and done/not done.
  4. Out of scope: what's deliberately left alone.
  5. Verification: how to check the result.

When you read one, look for four things:

  • Assumptions. Our plan said plainly: "I read true|false as case-sensitive, so TRUE gets a 400; tell me if you want it to accept any case." That's exactly where you decide, before there's any code.
  • Scope. Is every file on the list really needed? A line like "while I'm there, rewrite the error handler" is a sign of scope creep.
  • Out of scope. Claude spotted the double-delete bug that returns 500 (issue #1) but noted it wouldn't fix it in this plan. Good: one plan, one job.
  • How it's checked. A plan with no tests or verification isn't finished.

Approve, edit or keep planning

When the plan is ready, Claude asks what to do next:

  • Yes, and use auto mode: approve and continue in auto mode. If auto mode isn't available, this reads Yes, auto-accept edits.
  • Yes, manually approve edits: approve, but review each edit. Good for the first time you build from a plan.
  • No, keep planning: stay in plan mode and tell Claude what to change, for example "accept TRUE and True the same as true".

To edit the plan yourself, press Ctrl+G: the plan opens in your default text editor, and you change it directly and save before Claude starts.

Approving exits plan mode and switches to the matching mode; Claude starts editing. To plan the next job, press Shift+Tab to go back or use /plan. Approving a plan also names the session after it, which helps you find it later (lesson 7.3).

Where plans live, and context

Plans are written to files, by default in ~/.claude/plans. Set plansDirectory to keep them in the project:

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

Then plans sit next to the code, can be reread, and can be committed if the team wants a history of decisions.

Planning uses up context: Claude has read a pile of files. Set showClearContextOnPlanAccept: true and the approval prompt gains an option, "Yes, clear context and …", which approves, clears the planning context, and starts working from the plan alone. A good plan is enough to work from; everything Claude read while planning doesn't need to come along.

There's also a model choice: opusplan uses Opus in plan mode and switches to Sonnet automatically once work begins. Strong reasoning for the plan, economy for the execution.

A workflow for issue #3

Put together, here's a workflow for every day:

  1. Plan: /plan Implement issue #3 in app-works-247/todo-api (with the GitHub MCP from level 5, Claude reads the issue itself).
  2. Read carefully: assumptions, scope, out of scope, how it's checked.
  3. Adjust: "No, keep planning" with your feedback, or Ctrl+G to edit directly.
  4. Approve with "Yes, manually approve edits" the first time.
  5. Let the hooks do the rest: lesson 6.2's hooks check each file's syntax and won't let Claude report done while the tests are red.
  6. Compare the result with the plan, then commit.

Plan mode doesn't make Claude smarter. It moves the important decisions to before there's code, while changing your mind is still cheap. The next lesson, 7.2, handles the other direction: when the code is already written and the approach was wrong, how to go back.

Practice lesson 7.1

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.