Plan before you build: plan mode and written plans in Claude Code
The short answer: Plan mode makes Claude read and think without editing your files until you approve a plan. Save the plan as a file too, so a fresh session can build from it.
Key points
- Plan mode lets Claude read and propose changes without editing your files until you approve a plan.
- Edit the plan before you approve it: Ctrl+G opens it in your text editor.
- Save the plan as a file in your project, then build from a fresh session that reads it.
- The more expensive a mistake is to undo, the more plan you want.
On this page
What is plan mode in Claude Code?
Plan mode is a setting in which Claude researches your project and proposes changes, but does not edit your source files. The docs say it reads files, runs shell commands to explore, and writes a plan, and that edits stay blocked until you approve the plan (Claude Code docs: permission modes).
It is one of several permission modes. The others range from Manual, where Claude asks before anything but reading, to modes where it works with fewer questions.
How do I turn it on?
The docs give four ways:
- Press
Shift+Tabto cycle to it. - Start a single prompt with
/plan. - Start a session in it with
claude --permission-mode plan. - Make it the default for a project by setting
defaultModetoplanin.claude/settings.json.
To leave it, press Shift+Tab again.
Watch out
One catch from the docs: at the approval prompt, press Esc first, because Shift+Tab there approves the plan.
What happens when I approve a plan?
You get three choices. You can approve and let Claude work in auto mode, approve and review every edit yourself, or say no and keep planning so you can tell Claude what to change. Approving ends plan mode and Claude starts editing.
Tip
The docs also say you can press Ctrl+G to open the proposed plan in your text editor and change it before Claude goes ahead. Do this. A plan you have edited is a plan you understand.
Why plan at all?
Because the cheapest place to fix a misunderstanding is before anything is built. The best-practices page says it directly: when Claude builds something different from what you had in mind, it is usually missing information it can’t get from your project. Planning is how that information gets out of your head.
A plan also gives you something to read. You can’t review hundreds of changed lines, but you can read ten bullet points and say “no, not like that”.
Isn’t plan mode enough?
Not quite. Plan mode gives you a plan inside a conversation, and conversations get long, cleared or lost. A plan in the chat has three weaknesses:
- It scrolls away. Twenty messages later, nobody remembers step three.
- It is tied to one session. A fresh session knows nothing about it.
- You can’t point to it. There is nothing to check the finished work against.
The docs note that plan files are kept on disk, in ~/.claude/plans/ or in a folder you set with plansDirectory. But the best-practices page describes a stronger habit: write the plan down as a file in your project.
What is a written plan?
A file, usually Markdown, that says what you are building, in what steps, and what “done” means. The best-practices page shows the idea with an interview. You tell Claude the rough idea and ask it to interview you until it could write the spec, then write it to a file called SPEC.md. Claude comes back with multiple-choice questions about the parts you haven’t decided: for example what happens to requests over a limit, or what is out of scope.
Then comes the important step from the same page: once the file exists, start a fresh session to build from it. The build begins with a clean context and a written definition of done.
- Plan modeClaude reads and proposes; no edits
- Save the planA file in your project, like PLAN.md
- Fresh sessionBuilds one step from the file
- CheckA command that passes or fails
Next step: back to the fresh session, until the plan is done
What goes in a good plan?
Keep it short enough to read in two minutes.
- The goal in one or two sentences. Who uses it and what they get.
- What is out of scope. The list of things you are not building now.
- The steps. Small enough that each one can be checked.
- How you will check each step. A command that passes, or a screen you can look at.
- Decisions already made. So Claude doesn’t re-decide them.
- Open questions. Things you have not decided yet.
How do I use the plan while building?
Start a new session and say:
Ask Claude
Read PLAN.md and do step 1 only.
Then:
- When step 1 is done, ask Claude to show how it checked the result, then move to step 2.
- If the plan turns out to be wrong, change the file first and then the code. The file stays the truth.
- After the build, ask a reviewer to compare the result with the plan. The best-practices page has a prompt for it: use a subagent to review the diff against the spec file, check every requirement is implemented and the listed edge cases have tests, and skip style.
Watch out
That last part, “skip style”, matters. The docs warn that a reviewer asked to find problems will always find something, and fixing everything leads to extra layers and tests for cases that can’t happen.
When can I skip planning?
When the change is small and obvious: a typo, a colour, one clear fix. For anything that touches several files, changes how data is stored, or involves sign-in or payments, plan first.
A rule of thumb: the more expensive a mistake is to undo, the more plan you want.
Where does the plan live after the build?
Keep it. A plan with the date and what changed becomes the history of why things were built the way they were. Next month, when you wonder why a feature works that way, the answer is in a file, not in a conversation you deleted. Anything that must apply to every future session, such as the check command, goes in your CLAUDE.md (memory docs).
A short checklist
- Use plan mode for anything bigger than one clear fix.
- Edit the plan before you approve it (
Ctrl+G). - Save the plan as a file in your project.
- Build from a fresh session that reads the file.
- Give every step a check that passes or fails.
- Update the file when the plan changes.
- Keep the plan afterwards.