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

• claude-code-overview
• agentic-patterns