On this page
Claude Code plan mode reads your code and proposes a plan before it edits anything, so the plan can only be as good as what you give it. It reads files well. It can’t read why the feature matters, who it’s for, what number should move or what done looks like. Hand it those four things first, and the plan comes back shaped around your users instead of a guess.
- Plan mode researches and proposes. It makes no edits until you approve.
- The plan inherits every gap in your prompt: no user, no metric, no checkable must-haves.
- Give it the why, who it’s for, the metric and must-haves with acceptance criteria.
- Check each must-have against the plan before you approve it.
How plan mode turns a request into a plan
Plan mode tells Claude to research and propose changes without making them. Claude reads files and runs shell commands to explore, then writes a plan. In most sessions, edits stay blocked until you approve it.
- Enter plan mode. Press Shift+Tab until the status bar shows plan mode on, prefix one prompt with /plan, or start with claude –permission-mode plan.
- Give it the task. Paste the brief, or type @ and a file path to include that file in your message.
- Let it research. Claude hands codebase research to the built-in Plan subagent, which keeps the file reads out of your main conversation.
- Review the plan. Press Ctrl+G to edit it in your text editor, or choose to keep planning and say what to change.
- Approve it. Claude leaves plan mode and starts editing, either in auto mode or with you approving each edit.
Anthropic’s permission modes docs cover the approval options in full. To make plan mode the default for a project’s terminal sessions, set defaultMode to plan in .claude/settings.json.
Why the plan inherits every gap in its input
Plan mode is good at the how. It finds the component to change, the table to migrate and the test file to extend. The why, the who and the definition of done aren’t in the repo, so Claude fills them with defaults.
Ask for “a waitlist” and a reasonable plan might add a waitlist settings page, email and push alerts, and a manual approval queue. None of that is wrong in general. All of it is wrong for a studio owner who checks the app between classes and wants empty mats filled without lifting a finger.
The built-in Plan subagent that does the research also starts without your CLAUDE.md files, which keeps it fast. So product context that lives only in CLAUDE.md doesn’t reach the research step. Context in your prompt does.
| Missing from the prompt | What the plan does instead |
|---|---|
| Who it’s for | Plans for a generic user, with extra settings, options and admin screens |
| Why it matters | Solves the literal request, even when the real problem sits next to it |
| The metric | Has no step that records whether the feature worked |
| Must-haves with acceptance criteria | Ends at “add tests”, with tests Claude invents |
| What already exists | Builds a second version of a component you already have |
| What’s out of scope | Adds features that sound related |
Give plan mode the why, who, metric and must-haves
The fix is a short brief before the plan. It saves a long chat after it. A Build Pack covers these: why it matters, who it’s for, the metric, and the must-haves with acceptance criteria. It also says what’s already broken and what already exists. You can write the same thing by hand.
For example, a founder building a booking tool for yoga studios keeps hearing one request from owners: let clients wait for a spot in a full class.
/plan Add a waitlist to full classes.
/plan Build the waitlist in @docs/packs/waitlist.md. Plan against its must-haves, reuse what it lists as existing, and leave out anything it marks out of scope.
The file behind that prompt is short. Here is an illustrative version.
# Waitlist for full classes
## Why it matters
Owners lose drop-in revenue when spots open late and nobody
fills them. 7 owners raised it in 6 weeks, in support
threads and calls: "Two late cancels and the mat sits empty."
## Who it's for
Owners of single-location studios. They run classes from
a phone between sessions. Clients book on mobile web.
## Metric
Share of late-cancelled spots that get refilled.
## Must-haves and acceptance criteria
1. A client can join the waitlist from a full class page.
Check: the button shows only when the class is full.
2. When a spot opens, the first person gets a text and has
30 minutes to claim it.
Check: a test opens a spot, sends one text, expires at 30 min.
3. An unclaimed spot passes to the next person.
4. The owner sees the waitlist order on the class roster.
## Already exists
SMS sender in src/notify/. Roster component in src/classes/.
## Already broken
Capacity can go negative after an admin edit (issue 212).
## Out of scope
Paid priority on the waitlist. Waitlists for workshops.
Notice the numbers. They count people and quote one of them, with no forecast. The metric names what should move, and the target is yours to set before you build. Compare yours with a sample Build Pack, or see how to write a PRD for Claude Code, Cursor and Lovable.

Check the plan against each must-have
Plans read well, and that’s the risk. Before you approve, hold the plan up against the brief, line by line.
- Every must-have maps to at least one step
- Each step says how it will be checked: a test, a script or a screen
- The plan reuses what the brief lists as existing
- Nothing in the plan touches what’s out of scope
- The known bug is fixed on purpose or left alone on purpose
- One step records the metric
If something’s missing, choose to keep planning and name the gap: “Must-have 3 has no step. Add one, with a test that passes an unclaimed spot along.” Naming the line works better than asking for a better plan, and it costs less than finding the gap in a diff.
Note. The /plan prefix covers one prompt. After you approve, Claude is editing. To plan the next feature, prefix that prompt with /plan again or cycle back with Shift+Tab.
Skip plan mode for small, obvious changes
Plan mode adds a round trip. For a typo, a copy change or a one-file fix with an obvious test, just ask. Use it when the change crosses several files, touches stored data, or when you’d struggle to say what done looks like. In that last case, write the brief first, because the plan can’t supply what the brief leaves out.
If you can’t write the brief yet, Anthropic’s best practices suggest letting Claude interview you: “Interview me until you could write the spec, then write it to SPEC.md.” Answer its questions, then plan from that file in a fresh session.
See what plan mode should receive. A sample Build Pack for a made-up product, with every section’s source.
See a sample Build PackDoing this in MindBacklog
MindBacklog keeps what your users said, ranks the problems they have, and hands your coding agent the why. The Build Pack carries why it matters, who it’s for, the metric, and the must-haves with acceptance criteria. Every section names its source, and the only numbers are counts. Copy it for Claude Code or Cursor, or let your agent pull it over MCP on the Growth and Scale plans. How the Build Pack works.
Questions
How do I turn on plan mode in Claude Code?
Press Shift+Tab until the status bar shows plan mode on. You can also prefix a single prompt with /plan, or start a session with claude –permission-mode plan. Press Shift+Tab again to leave without approving a plan.
Does Claude Code plan mode edit files?
Not before you approve. In plan mode Claude reads files and runs commands to explore, then writes a plan, and in most sessions edits stay blocked until you accept it. Approving the plan switches the session to editing.
Can I change the plan before Claude starts building?
Yes. Press Ctrl+G to open the plan in your text editor and change it directly, or choose to keep planning and tell Claude what to fix. Naming the must-have a step misses works better than asking for a better plan.
