Plan mode in Claude Code: agree on the plan before the agent touches code

The most common failure with coding agents isn't syntactically wrong code; it's correctly doing something nobody needed: the agent misreads the request, edits 15 files its own way, and you lose time reverting. Claude Code's plan mode targets exactly this: Claude can read code, run exploratory commands and write a plan, but can't modify source code until you approve. This post summarises how to use plan mode per the official docs and how to make it a team habit.

Where does plan mode sit among the permission modes?

Deny rules in settings always apply in every mode. Plan mode doesn't replace deny rules; it's a "think first" layer, not a security layer.

Turning on plan mode: 3 ways

1. At startup: claude --permission-mode plan.
2. Mid-session: press Shift+Tab until the status bar shows ⏸ plan mode on. Press again to leave without approving.
3. For one prompt: start the prompt with /plan.

To always start in plan mode for a repo, set in .claude/settings.json:

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

For the VS Code extension, the docs note it doesn't read project-level startup modes; use the user setting "claudeCode.initialPermissionMode": "plan".

The plan approval flow

When Claude finishes the plan, you can choose:

• Yes, and use auto mode (or auto-accept edits if auto isn't available): approve and let Claude work straight through.
• Yes, manually approve edits: approve the direction but still review each change.
• No, keep planning: stay in plan mode and say what to change in the plan.

Two useful details: press Ctrl+G to open the plan in your text editor and edit it directly; plans are saved in ~/.claude/plans/ (configurable with the plansDirectory setting), so you can paste them into a ticket or PR as a design doc.

A prompt for a good plan

/plan Add rate limiting to the /login API.
Requirements:
- At most 5 wrong passwords / 15 minutes / IP + username
- Use the existing Redis, no new dependencies
The plan must cover: files to change, Redis key design, how to test,
risks for users sharing an IP (offices, NAT).
Ask if anything is unclear instead of assuming.

A good plan usually includes: the files it will touch, the order of work, how to verify (which tests, which commands), and the assumptions made. If the plan lacks verification, that's a sign to "keep planning".

When to use it, when not to

Risks and caveats

• A nice plan doesn't mean correct code: you still need tests and review after execution.
• Context fills up: the exploration phase reads many files. The showClearContextOnPlanAccept option lets you approve the plan and clear the planning context, keeping execution lean.
• Approving with auto mode: convenient but skips reviewing each edit. For sensitive code, choose manual approval.

How to apply it

• Dev: Build the habit of Shift+Tab into plan mode for any task touching more than 3 files. Reading a plan for 2 minutes is cheaper than reverting for 30.
• Tech Lead: Set defaultMode: "plan" for important repos. Ask for the plan (the file in ~/.claude/plans/) to be attached to large PRs so reviewers understand the intent.
• PM: A plan is a free technical spec: use it to check the agent understood the acceptance criteria before time goes into coding.