plan-mode

A claude-code mode that separates exploration from execution. In plan mode, Claude does read-only investigation, refines goals and constraints, and submits a concrete plan; only after the user approves does any file get modified (2026-04-27-claude-code-architecture-governance-engineering).

Why it matters

For complex refactors, migrations, or cross-module changes, the failure mode of “rush straight to code” is wandering further and further down a wrong assumption. Plan mode keeps the cost of exploration cheap (no writes) and forces the assumption check before execution begins.

Activation

Shift+Tab twice to enter plan mode.

Implementation note (cache-aware)

The intuitive design — switch to a read-only tool subset on entry — would invalidate the cache. Actual implementation: EnterPlanMode is a model-callable tool. The model invokes it when it detects a complex problem; the tool roster doesn’t change, so the cache prefix stays stable. Read-only behavior is enforced elsewhere in the harness (2026-04-27-claude-code-architecture-governance-engineering).

Advanced pattern: AI reviews AI

tw93‘s recommendation: open one Claude in plan mode to write the plan, open a Codex instance with a “senior engineer” persona to review the plan. Cross-model review catches more than single-model self-review. The plan-mode artifact is the natural handoff format (2026-04-27-claude-code-architecture-governance-engineering).