▲ Claude Academy
Sign in

Vault / wiki/201/claude-code-plan-mode.md

updated 2026-05-28

Plan Mode

A read-only thinking mode where Claude proposes a plan before making any changes. The user approves (or edits) the plan, then execution proceeds.

Why

  • Reduces "off-the-rails" implementations on ambiguous tasks.
  • Surfaces architectural decisions before code lands.
  • Lets the user redirect early when the model misread the problem.

How

  • Enter via Shift+Tab cycle, or by starting Claude with --permission-mode plan.
  • In plan mode, write/edit tools are blocked. Read, search, fetch are allowed.
  • The agent calls ExitPlanMode with its proposed plan as an argument.
  • User approves → Claude exits plan mode and executes; user rejects → Claude revises.

When to use

  • Tasks spanning multiple files.
  • Refactors with unclear scope.
  • Anything involving migrations or schema changes.
  • New features where the design is up for discussion.

When NOT to use

  • Trivial edits or known-narrow changes (typo fix, single function).
  • Exploratory "what does this code do?" sessions.
  • Time-sensitive single-file work.

Plan format

A good plan:

## Plan

1. **Add `FeatureFlag` enum** in `src/flags.ts`. New values: `betaUI`, `paymentsV2`.
2. **Update `useFlag` hook** in `src/hooks/useFlag.ts` to read from new enum.
3. **Migrate 4 callsites**:
   - `src/components/Header.tsx`
   - `src/components/Checkout.tsx`
   - ...
4. **Add tests** in `__tests__/flags.test.ts`.

Risks:
- The `paymentsV2` flag affects production billing — leave that callsite untouched, document for a follow-up PR.

CCA-F angle

The "Code Generation with Claude Code" scenario commonly tests plan-mode adoption — when to enforce it via --permission-mode plan (e.g., in CI for autonomous PRs) and when interactive cycling is enough.

See also