What You Need to Know
Claude Code works in two main modes. In plan mode, Claude reads the codebase, analyses dependencies and proposes an approach without modifying any files. In direct execution, Claude skips the planning phase and makes changes straight away. Clear criteria decide which mode fits a task.
This lesson uses one made-up example throughout: a wedding venue whose booking system has four jobs. Two are small: a date bug with a clear stack trace and a change to the deposit rate. Two are bigger: a payment provider with two possible connections and a swap of the logging library across 30 files.
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. For each of these tasks, you need to understand the existing code before the first edit. Use it 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. Different integration architectures, for example, have different infrastructure requirements. You need to evaluate the approaches before you choose one.
- Architectural decisions are required. Service boundaries, module dependencies and API contracts have consequences for later work. 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. You need to understand dependencies, trace data flows or map the existing structure before changing anything.
At the venue, plan mode fits the payment job and the logging swap.
You switch into plan mode rather than ask for it. There are three ways to switch:
- start the session with
claude --permission-mode plan - press Shift+Tab during a session until the status bar shows plan mode on
- prefix a single prompt with
/plan
Claude then writes nothing to disk until you approve the plan. Writing "in plan mode" into the body of a prompt does nothing. /plan at the start of a prompt switches to plan mode.
Direct Execution: When to Use It
Direct execution is for well-understood changes with clear, limited scope. Use it 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.
A plan resolves design decisions. A simple, well-defined task has no design decisions, so planning adds nothing. The venue's date bug and deposit rate are such tasks: the fix for each is known.
Key Concept
The choice of mode depends on ambiguity, not difficulty. A difficult but well-defined bug fix (clear stack trace, single function, known cause) suits direct execution. A seemingly simple feature request that could be implemented three different ways and affects multiple modules suits plan mode.
The Explore Subagent
The Explore subagent keeps verbose discovery output out of the main conversation. On multi-phase tasks, exploring produces file listings, dependency graphs, code excerpts and analysis notes. When that output stays in the main conversation, it fills the context window and degrades 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 free for the implementation work
Use the Explore subagent when discovery is verbose but implementation needs focused context. Mapping the venue files that import the old logging library is one such discovery.
The Hybrid Approach: Plan Then Execute
A common combination is plan mode to investigate, then direct execution to implement. The pattern has two phases:
- Plan phase: Use plan mode to explore the codebase, understand dependencies, evaluate approaches and design the implementation strategy.
- Execute phase: Switch to direct execution and implement the planned approach file by file. The strategy is already decided.
When you decide the pattern once, every file gets the same change. The venue's logging migration across 30 files splits into these two phases:
- Plan: Identify all files that import the old library. Map the API differences between the old and new libraries. Design the migration pattern. Check for edge cases.
- Execute: Apply the migration pattern to each file using the planned approach.
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
Do not start in direct execution and wait for complexity to appear. When the requirements already say that the task is complex, such as "restructure the monolith into microservices", choose plan mode straight away. That complexity will not emerge later. It is already in the task description. A venue request to split the booking system into separate services is that case.
In the exam
The exam tests whether you can pick the right mode for a given task. The plan-then-execute hybrid is common, and the exam expects you to spot it: plan mode first and then direct execution, not one mode or the other. A common trap is the late switch from direct execution to plan mode.
Plan mode is part of Domain 3, which carries 20% of the marks. No other Anthropic exam gives Claude Code that much weight, so this exam is the closest thing to a Claude Code certification.
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 clearest case for direct execution. Plan mode adds unnecessary overhead when the problem, location, and solution are all clear.
Doing verbose codebase discovery in the main conversation
Discovery output such as file listings and code excerpts fills the context window and degrades later responses. The Explore subagent runs the exploration in isolation and returns summaries, keeping the main context free for implementation.
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 Scenario
Your team faces three tasks. Task (1) is to restructure a monolith into microservices. Task (2) is to fix a null pointer exception in a single function with a clear stack trace. Task (3) is to migrate from one logging library to another across 30 files. The two libraries handle log levels and structured context differently. Which mode should be used for each?
Build Exercise
Practice Plan Mode vs Direct Execution Decision-Making
What you'll learn
- 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
Why: 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.
- Identify a simple single-file bug and use direct execution to fix it — observe the efficiency gain over planning
Why: 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.
- 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
Why: 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.
- Use the Explore subagent for a verbose codebase discovery task and observe how it keeps the main conversation context free of verbose output
Why: 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.
- Create a written decision framework: list your criteria for choosing plan mode vs direct execution, with examples for each
Why: 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.
Sources
- Claude Code Plan Mode Documentation — Anthropic
- Claude Code Permission Modes — Plan mode — Anthropic
- Claude Certified Architect Foundations Exam Guide — Task Statement 3.4 — Anthropic
- Claude Certified Architect Foundations Exam Guide — Sample Question 5 — Anthropic
- CCAR-F Exam Guide v1.0: Task Statement 3.4 — Anthropic