Weigh four signals before choosing plan mode

Learning objective

Choose plan mode or direct execution by architectural uncertainty, change scope, blast radius, and number of viable approaches.

Core idea

For an architect using Claude Code, the mode decision starts with what remains undecided. If you know the required behavior, affected location, and acceptable fix, direct execution can move from a focused read to an edit. If you still need to choose an interface, dependency boundary, or implementation strategy, investigate in plan mode before code depends on that choice.

Anthropic recommends planning for uncertain approaches, changes across multiple files, and unfamiliar code. It also warns that planning adds overhead for small, clearly scoped fixes, such as fixing a typo, adding a log line, or renaming a variable. Its decision rule is: “If you could describe the diff in one sentence, skip the plan.” The useful distinction is whether investigation could change the proposed solution. A precise instruction to implement an already understood change needs less planning than a short instruction whose architectural meaning is unresolved.

See 3.4.2 for discovery controls, 3.4.3 for Explore delegation, and 3.4.4 for approving a plan and implementing it. This lesson owns the initial choice.

How it works

Assess four signals together

Architectural uncertainty concerns the design you have not settled. “Split billing from orders” leaves questions about interface ownership and dependency direction. “Reject an earlier delivery date in this existing validator” can describe a settled behavior. Plan mode gives the former task a research and proposal phase rather than allowing the first plausible design to become an implementation.

Change scope concerns how many places need coordinated modification. A library migration across 48 files calls for discovery of usage patterns before replacements begin. The number is a scenario fact, not a Claude Code limit: neither 45 nor 48 is a documented threshold at which the product requires plan mode. Multiple files are a planning signal because relationships between edits can matter more than individual replacements.

Blast radius concerns which behavior depends on the change. A one-file edit to a shared authorization decision can affect many callers. Conversely, a mechanical rename across several independent files can have a clear intended diff. Treat blast radius as a review question: what consumers rely on the behavior, and could the proposed fix change their contract? This is a way to assess uncertainty, not an automatic classification Claude Code performs for you.

Viable approaches concern choices you genuinely need to compare. An integration that can use either a synchronous call or a queue has consequences beyond syntax. The task remains architectural if each approach requires different infrastructure or changes failure behavior, even when either implementation would be short. Ask Claude to compare those approaches while planning instead of treating the first generated version as the decision.

These signals reinforce each other, but one strong signal can be enough. You do not need a large file count before planning a high-impact interface decision. Nor must you create a separate design exercise for every file in a migration once the shared approach is understood.

Select the workflow explicitly

Use claude --permission-mode plan to start a planning session. Within a session, cycle with Shift+Tab until the status bar shows ⏸ plan mode on, or prefix a prompt with /plan. The mode tells Claude to research and propose changes rather than edit source. The enforcement boundary and its bypass exception are covered in 3.4.2.

Direct execution is a workflow description, not a permission-mode value named direct. It means asking Claude to implement without a separate planning phase. The active permission mode still decides whether individual actions ask for approval. For example, claude --permission-mode default selects Manual mode, whose configuration value is default. Implementation can proceed there while you review actions individually.

Do not equate direct execution with bypassing checks. The task’s design can be settled while you still want edit approval. Likewise, selecting plan mode does not establish that the proposed design is correct; it establishes a phase in which you can inspect and revise it before implementation.

Reassess when evidence changes the task

A stack trace helps locate a failure, but does not prove the remedy. If a focused read shows that the apparent null-handling bug is actually an inconsistency between several callers, the original “small fix” classification no longer holds. Enter plan mode to investigate that design question before extending the change.

That reassessment differs from starting a known architectural migration directly and hoping to plan later. In the first case, evidence changes your understanding. In the second, the request already states the uncertainty. Anthropic’s explore–plan–implement workflow puts investigation before modification when those design questions are present at the outset.

Key distinctions and trade-offs

The following tasks separate workflow choice from permission choice:

Planning exchanges an extra research and review phase for a chance to correct assumptions before they shape code. It is valuable when understanding can change the solution. Direct execution reduces that overhead when the intended diff is already clear. Neither choice removes the need for verification criteria and evidence of the result.

A long prompt is not a substitute for a settled design. You can write exhaustive implementation instructions around an unverified assumption and still solve the wrong problem. The documented test concerns a one-sentence diff, not a one-sentence request. “Replace our authentication layer” is a one-sentence request, but it does not specify a one-sentence diff; the interfaces and behavior to change remain undecided.

Architecture / decision scenario

A developer-productivity team brings Claude Code three requests. A delivery validator needs an agreed conditional. An invoice formatter has a crash whose trace and local read reveal the missing check. A shared HTTP library must be replaced across 48 files, and two candidate replacements have different retry behavior and infrastructure requirements.

The architect selects direct execution for the validator and formatter, naming their files, expected behavior, and existing verification commands in the prompts. These tasks still run under the team’s chosen edit permissions; they do not require a separate architectural approval phase.

The library migration starts with claude --permission-mode plan. The architect asks for affected wrappers and callers, comparison of the two approaches, and the behavior consumers must retain. Although only one shared wrapper might need an early edit, its blast radius includes many callers. That makes the wrapper’s small size a weak argument for direct execution.

If the formatter investigation instead reveals inconsistent expectations across several modules, the architect switches that task into planning too. The deciding evidence is the discovered contract uncertainty, not a rule that all stack traces guarantee simple fixes.

Common exam traps

• Treating a one-sentence request as a one-sentence diff.
• Treating 45 affected files as a product threshold rather than a scenario signal.
• Choosing direct execution for a service-boundary decision because the initial edit is small.
• Adding a planning phase to an understood validation conditional without any unresolved choice.
• Confusing direct execution with bypassPermissions or a nonexistent direct mode.
• Substituting longer instructions for investigation of competing approaches.

What to remember

Choose plan mode when discovery can change the architecture, affected scope, or selected approach. Choose direct execution when the required diff is small and understood. Count behavioral dependencies as well as files, and keep workflow choice separate from permission to perform each action.

Knowledge check

References

• Anthropic, Best practices for Claude Code
• Anthropic, Choose a permission mode