Claude Code plan mode: review the plan before any file is touched

Originally published at https://aicoding-guide.com.

You ask for a refactor and come back to a large diff heading somewhere you didn't intend. Everyone using Claude Code hits that once. Plan mode is the answer to it.

In plan mode, Claude reads and investigates, then stops at presenting an implementation plan. You read the plan, correct it, and only then let the work start — which matters more the larger the change.

Key point
What you will learn

• Three ways into plan mode, and how it differs from the other modes
• The path from a plan to an implementation
• Where a plan earns its extra step, and where it doesn't

Where plan sits among the permission modes

Claude Code's permission modes decide how much runs without asking you.

Mode	File reads	File edits	Commands
plan	Automatic	Not allowed	Not allowed, apart from some read-only ones
default (Manual)	Automatic	Asks	Asks
acceptEdits	Automatic	Automatic	Asks
auto	Automatic	Reviewed by a classifier	Reviewed by a classifier
dontAsk	Automatic	Never prompts	Never prompts
bypassPermissions	Automatic	Automatic	Automatic, for isolated environments only

Plan mode is the read-only one. That also makes it a good fit for work that shouldn't change anything at all: investigation, design, review. For the full behavior of each mode, including which ones a project settings file can't set, see Changing Claude Code's default permission mode.

Three ways in

1. Shift+Tab

Pressing Shift+Tab in a session cycles through the modes. The current mode shows below the input box, so press until it reads plan. This is the quickest route.

2. A launch flag

claude --permission-mode plan

Use it for a session you want to start by investigating.

3. Make it the default

{
  "permissions": {
    "defaultMode": "plan"
  }
}

While you're still building intuition, this is a safe default: every session starts by showing you a plan. For how the permissions block fits together, see Configuring permissions in Claude Code's settings.json.

From plan to implementation

1. In plan mode, say concretely what you want. For example: "Consolidate the authentication logic into lib/auth.ts and remove the duplication from each API route."
2. Claude reads the relevant files and presents a plan: which files it will change, in what order, and what it is unsure about.
3. Read it, and reply with corrections. For example: "Leave middleware.ts alone this time."
4. Once the plan is right, take the option to proceed. The session switches to a mode that can edit, and the work begins.
5. Afterwards, compare the diff against the plan and check nothing was missed.

Glossary
What a good plan contains: the files it will change, the files it decided not to change, the order, and the risks. A plan with no filenames in it is too abstract — ask it to enumerate the target files.

Where plan mode pays off

• Changes spanning several files: refactors, API redesigns, swapping a dependency
• Work that needs a design decision first: where something belongs, whether to reuse an existing mechanism or add one
• Exploring an unfamiliar codebase: finding where a feature lives, without touching it
• Reviews: reading a diff or a PR and returning findings only

Using plan mode for a one-file fix or a typo only adds a confirmation step. There, acceptEdits gets you there faster.

Writing a prompt that produces a usable plan

The quality of the plan tracks the specificity of the request.

Goal: share the retry logic across the payment paths
Constraints: don't increase calls to the external API; don't modify existing tests
Wanted output: list of files to change, a summary per file, the implementation order, the test approach

Separating goal, constraints and wanted output is what gets all the parts of a plan filled in.

Approving a plan is not approving the diff
An approved plan doesn't guarantee the implementation matches it. After running with acceptEdits especially, check git diff for changes the plan never mentioned.

Summary

• Plan mode is read-only: it investigates and presents a plan, and changes nothing
• Enter it with Shift+Tab, --permission-mode plan, or defaultMode: "plan"
• Use it for multi-file changes and design decisions; skip it for small fixes
• Write the request as goal, constraints and wanted output to get a plan you can act on