Task statement 3.4 · Claude Code configuration and workflows
Determine when to use plan mode vs direct execution
Two requests arrive the same morning: migrate packages/web from Moment.js to date-fns across 45 files, and add a missing date check to one function in packages/api. Only the migration has an approach to decide before any file changes.
share
Two tempting shortcuts ignore what the request already says. Starting in direct execution and switching to plan mode "if it gets complicated" waits for complexity that is already stated, such as service boundaries to decide. Writing exhaustive instructions up front fixes the approach before anyone has read the code. Either way, the wrong approach is found after files have changed, which is the rework plan mode prevents.
KnowledgeWhat plan mode does
Plan mode is a permission mode in which Claude researches and proposes changes without making them. Claude reads files and runs shell commands to explore, and it hands larger research to the read-only Plan subagent, whose output stays in its own context window. Your source stays unedited until you approve the plan, so exploration and design happen before any change is committed, which prevents costly rework.
- Enter plan mode with
Shift+Tab, a/planprefix on one prompt, orclaude --permission-mode plan. - Claude explores and presents a plan.
- You approve it, choose "No, keep planning" and say what to change, or press
Shift+Tabto leave without approving. - Approving exits plan mode into an editing mode, and Claude carries out the plan by direct execution.
Interactive · triage a task
Choose a task to see its lane.
Direct execution · the stack trace names one function in one file, and the fix is obvious, so nothing is left to decide.
Direct execution · one validation conditional in one function is a diff you could describe in one sentence.
Plan mode, then direct execution · the service boundary is an architectural decision. Once you approve it, the moves follow the plan.
Plan mode, then direct execution · adapter or caller-by-caller is decided before any of the 45 files changes. Then the session executes the approved order.
Plan mode, then direct execution · the two approaches need different infrastructure in packages/infra, so you choose before any code exists.
KnowledgeWhich tasks need a plan
Plan mode is designed for complex tasks involving large-scale changes, multiple valid approaches, architectural decisions and multi-file modifications, because a wrong choice there shows up only after many files change. Direct execution is appropriate for simple, well-scoped changes, where you could describe the diff in one sentence, so a plan only costs tokens and time.
A decision remains
Microservice restructuring: where does the billing/users boundary in packages/api run?
Library migration, 45+ files: an adapter first, or edit each caller?
Two integration approaches: a hosted search API, or Elasticsearch in packages/infra? Their infrastructure requirements differ.
The change is understood
Single-file bug fix, clear stack trace: TypeError … null (reading 'getTime') at isOverdue (dates.ts:42). Return false for a null dueDate.
Adding a validation check to one function: validateTask() rejects a dueDate before startDate.
SkillPlan the migration, then execute it
Started directly, Claude converts 20 files to inline date-fns calls, then reaches 7 files using moment.tz time zones, and the 20 are reworked around a shared adapter. Plan mode is only needed while the approach is undecided. In plan mode Claude maps which files use the old API and proposes an order. You approve, the session leaves plan mode, and Claude edits the 45 files following that plan.
⏸ plan mode on > plan the move of packages/web from moment to date-fns Plan subagent: 45 files import moment; 7 use moment.tz Plan: 1 add src/lib/dates.ts over date-fns and date-fns-tz 2 switch the 45 files to it, one folder at a time 3 remove moment; run the tests after each folder ❯ Yes, manually approve edits ← leaves plan mode Claude edits dates.ts, then the 45 files, in that order
SkillKeep discovery out of the main conversation
A multi-phase task often opens with a verbose discovery phase. Done in the main conversation, its searches and file reads fill the context window before implementation starts. The Explore subagent is read-only and built for code search. It reads in its own context window, skips CLAUDE.md and git status to stay fast, and returns only a summary, which is all the main conversation receives:
> use the Explore subagent to find every call to formatDue() in packages/ and summarise how each caller uses it Explore · 61 files read in its own context window ← 45 callers. 38 pass a Date and use the default format. 7 pass a time-zone name, so they need the tz option.
| Yes: boundaries, approach or scope are open | Plan mode. Approve the plan, then the session executes it directly. |
| No: the change is understood | Direct execution, with no plan. |
- Complexity stated in the request calls for plan mode from the first prompt, not partway through.
- Approval ends plan mode, and the plan then runs as direct execution.
- Explore stops discovery output from exhausting the main context, because only its summary returns.