Claude Code Configuration & Workflows · Lesson 4 of 6

3.4 - Plan Mode vs Direct Execution

Learn the decision framework for choosing plan mode or direct execution, understand the Explore subagent, and master the hybrid plan-then-execute pattern

Claude Code works in two main modes: plan mode and direct execution. The exam tests whether you can pick the right one for a given task. It's not a matter of taste - there are clear criteria for when each mode fits.

Plan Mode: When to Use It

Plan mode is for complex tasks where you need to explore the codebase, evaluate multiple approaches, and design a strategy before making changes. Use plan mode when:

Large-scale changes are involved. Restructuring a monolith into microservices, reorganising a module system, or refactoring a core abstraction all require understanding the existing structure before changing it.
Multiple valid approaches exist. When there are different ways to solve the problem (e.g., different integration architectures with different infrastructure requirements), you need to evaluate them before committing.
Architectural decisions are required. Service boundaries, module dependencies, API contracts - these decisions have downstream consequences. Planning prevents costly rework.
Multi-file modifications are needed. A library migration affecting 45+ files requires a consistent strategy. Without a plan, you risk applying the migration inconsistently across files.
Codebase exploration is necessary. When you need to understand dependencies, trace data flows, or map the existing structure before changing anything.

Plan mode enables safe exploration and design. Claude reads the codebase, analyses dependencies, and proposes an approach - all without modifying any files.

Direct Execution: When to Use It

Direct execution is for well-understood changes with clear, limited scope. Use direct execution when:

The change is well-scoped. A single-file bug fix with a clear stack trace. Adding a date validation conditional. Updating a configuration value.
The correct approach is already known. You know what needs to change, where, and how. There is no design decision to make.
The scope is limited. One function, one file, one clear modification.

Direct execution skips the planning phase and makes changes straight away. For simple, well-defined tasks, planning adds nothing.

Key Concept

The decision is not about difficulty but about ambiguity. A difficult but well-defined bug fix (clear stack trace, single function, known cause) is direct execution. A seemingly simple feature request that could be implemented three different ways and affects multiple modules is plan mode.

The Explore Subagent

The Explore subagent keeps verbose discovery output out of the main conversation. On multi-phase tasks, exploring the codebase throws off a lot: file listings, dependency graphs, code excerpts, analysis notes. Let all that flow into the main conversation and it fills the context window, which drags down the quality of later responses.

The Explore subagent:

Runs the exploration in isolation
Produces summaries of its findings
Returns those summaries to the main conversation
Keeps the main context window clean for the actual implementation work

Use the Explore subagent during multi-phase tasks where the discovery phase is verbose but the implementation phase needs focused context.

The Hybrid Approach: Plan Then Execute

The combination of plan mode for investigation and direct execution for implementation is common in practice and tested on the exam. The pattern:

Plan phase: Use plan mode to explore the codebase, understand dependencies, evaluate approaches, and design the implementation strategy.
Execute phase: Switch to direct execution to implement the planned approach, file by file, with the strategy already decided.

For example, migrating from one logging library to another across 30 files:

Plan: Identify all files importing the old library, map the API differences between old and new, design the migration pattern, check for edge cases.
Execute: Apply the migration pattern to each file using the planned approach.

It's plan THEN direct, not plan OR direct. The exam expects you to spot the pattern.

Decision Framework Summary

Task characteristics	Mode
Architectural restructuring	Plan mode
Library migration (many files)	Plan mode (then direct execution)
Multiple valid implementation approaches	Plan mode
Codebase exploration needed	Plan mode (with Explore subagent)
Single-file bug fix with clear stack trace	Direct execution
Adding a validation check to one function	Direct execution
Configuration value update	Direct execution
Known fix, known location, known approach	Direct execution

Recognising Complexity Upfront

A common exam trap: starting in direct execution and switching to plan mode only once complexity shows up. When the requirements already say the task is complex (e.g., "restructure the monolith into microservices"), reach for plan mode straight away. The complexity isn't going to emerge later - it's right there in the task description. Waiting for surprises is the wrong move.

Exam traps

Defaulting to direct execution for multi-file architectural changes

Multi-file modifications with multiple valid approaches require plan mode. Direct execution risks costly rework when dependencies are discovered late. If the task involves architectural decisions or affects many files, plan first.
Using plan mode for a single-file bug fix with a clear stack trace

A single-function fix with a known cause and clear stack trace is the textbook case for direct execution. Plan mode adds unnecessary overhead when the problem, location, and solution are all clear.
Not recognising the plan-then-execute hybrid pattern

The exam tests whether you know to combine plan mode for investigation with direct execution for implementation. This is the correct approach for tasks like library migrations: plan the strategy, then execute it.
Starting direct execution and switching to plan mode only when complexity emerges

When complexity is already stated in the requirements (e.g., monolith restructuring), plan mode should be chosen upfront. The complexity is known, not speculative. Do not wait for surprises.

Practice question

Your team faces three tasks: (1) restructure a monolith into microservices, (2) fix a null pointer exception in a single function with a clear stack trace, (3) migrate from one logging library to another across 30 files. Which mode should be used for each?

A Plan mode for all three, since they all involve code changes
Task 2 is a well-understood, limited-scope bug fix with a clear stack trace. Plan mode adds no value when the problem, location, and solution are all clear.
B Plan mode only for (1), direct execution otherwise
Task 3 affects 30 files with API differences between the old and new library. Without planning the migration pattern first, you risk inconsistent application across files and missing edge cases.
C Plan mode for (1) and (3), and direct execution for (2) Correct
Task 1 involves architectural decisions with multiple valid service boundary options - plan mode is essential. Task 3 affects 30 files and needs a consistent migration strategy designed before execution. Task 2 is a single-function fix with a clear stack trace - direct execution is appropriate.
D Direct execution for all three with comprehensive upfront instructions
Task 1 requires codebase exploration to understand dependencies before restructuring. Comprehensive upfront instructions assume you already know the right structure - but you cannot know that without exploring the code first.

Build exercise: Practice Plan Mode vs Direct Execution Decision-Making

Intermediate · 45 minutes

You'll practice:

Apply the decision framework for choosing plan mode vs direct execution based on task ambiguity
Execute the hybrid plan-then-execute pattern for multi-file migrations
Use the Explore subagent to isolate verbose discovery output from the main conversation
Recognise complexity upfront rather than waiting for it to emerge
Distinguish task difficulty from task ambiguity when selecting execution mode

Identify a complex multi-file task in a codebase (refactoring, migration, or restructuring) and use plan mode to explore dependencies and design an approach

Plan mode is for tasks with multiple valid approaches, architectural decisions, or multi-file modifications. The exam tests whether you choose plan mode upfront when complexity is stated in the requirements rather than waiting for surprises.

You should see: Claude Code explores the codebase without modifying any files. The output includes: identified dependencies between modules, multiple possible approaches with tradeoffs, and a recommended implementation strategy. No files are changed during the planning phase.
Hints
1. ```
Choose a task that involves architectural decisions or affects more than a handful of files. A refactor, migration, or restructuring qualifies.
```
2. ```
Use plan mode by prefixing your prompt with a planning instruction. For example, ask Claude to analyse the existing structure before proposing changes. Look for tasks where there is no single obvious approach.
```
3. ```
Start with: "In plan mode, analyse the authentication module. Map all files importing from auth/, identify the dependency chain, and propose two approaches for extracting it into a standalone service. Do not modify any files."
Expected output: a dependency map and two or more approaches with tradeoffs.
```
Identify a simple single-file bug and use direct execution to fix it - observe the efficiency gain over planning

Direct execution is correct when the problem, location, and solution are all clear. The exam tests that you do not over-plan well-understood changes. The decision is about ambiguity, not difficulty.

You should see: Claude Code makes the fix immediately without a planning phase. The change is confined to a single file or function. The total time from prompt to fix is noticeably shorter than the plan mode task above.
Hints
1. ```
Choose a bug with a clear stack trace or error message that points to a single function in a single file.
```
2. ```
A good example is a null check missing in a function, an off-by-one error, or a typo in a configuration value. The fix should be obvious before you start.
```
3. ```
Try: "Fix the null pointer exception in src/utils/format.ts line 42 - the user object may be undefined when called from the unauthenticated route."
Claude should fix the single function immediately without exploring the broader codebase.
```
Use the hybrid approach: plan mode to design a migration strategy for a library change across multiple files, then switch to direct execution to implement the plan

The plan-then-execute hybrid is a specific pattern tested on the exam. Plan mode designs the strategy; direct execution applies it consistently. This is the correct approach for tasks like library migrations affecting many files.

You should see: Phase 1 (plan): Claude identifies all files importing the old library, maps API differences, and produces a migration pattern. Phase 2 (execute): Claude applies the migration pattern file by file using the planned approach. The implementation is consistent across all files.
Hints
1. ```
Choose a real or simulated library migration that affects multiple files. Plan first, then execute the plan.
```
2. ```
For example, migrate from one date library to another. First ask Claude to plan: find all imports, map API differences, identify edge cases. Then ask Claude to execute the plan file by file.
```
3. ```
Phase 1: "Plan a migration from moment.js to date-fns. Identify all files importing moment, map the API differences for each usage pattern, and design the migration approach. Do not modify files yet."
Phase 2: "Now execute the migration plan. Apply the date-fns replacements to each file using the patterns you identified."
```
Use the Explore subagent for a verbose codebase discovery task and observe how it keeps the main conversation context clean

The Explore subagent isolates verbose discovery output so the main conversation context stays focused. Without isolation, extensive file listings and analysis fill the context window and degrade subsequent responses.

You should see: The Explore subagent runs the discovery task and returns a concise summary to the main conversation. The full verbose output (file listings, dependency graphs, code excerpts) is not visible in the main conversation. Subsequent responses in the main conversation remain high quality.
Hints
1. ```
Give Claude a broad codebase exploration task and observe whether the main conversation is cluttered with verbose output.
```
2. ```
The Explore subagent is used for multi-phase tasks where discovery produces extensive output. Request exploration of a large module or feature area.
```
3. ```
Ask: "Use the Explore subagent to map the entire src/api/ module: list all files, trace the dependency graph, identify patterns and anti-patterns, and summarise the findings."
The main conversation should show a summary, not pages of file listings.
```

Create a written decision framework: list your criteria for choosing plan mode vs direct execution, with examples for each

Internalising the decision criteria is essential for the exam. The framework should cover the key distinction: ambiguity determines the mode, not difficulty. A difficult but well-defined fix is direct execution; a simple-sounding feature with multiple approaches is plan mode.

You should see: A clear decision framework with at least four criteria for plan mode and three for direct execution. Each criterion has a concrete example. The framework explicitly addresses the ambiguity-vs-difficulty distinction.

Hints

Think about what makes a task ambiguous vs well-defined. List the signals for each mode.

Plan mode criteria: multiple valid approaches, architectural decisions, multi-file changes, codebase exploration needed. Direct execution criteria: known fix, known location, limited scope, clear stack trace.

Your framework should include entries like:

Plan Mode When:
- Multiple valid approaches exist (e.g., monolith to microservices - where do service boundaries go?)
- Multi-file modifications needed (e.g., library migration across 30+ files)
- Codebase exploration required (e.g., understanding dependency chains before refactoring)

Direct Execution When:
- Clear stack trace points to a single function (e.g., null pointer at line 42)
- Known fix, known location (e.g., update a config value)
- Limited scope, no design decisions (e.g., add a validation check)

Sources

Claude Code Plan Mode Documentation - Anthropic
Claude Certified Architect Foundations Exam Guide - Task Statement 3.4 - Anthropic
Claude Certified Architect Foundations Exam Guide - Sample Question 5 - Anthropic