Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Plan Mode

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Agent – plan mode is a workflow for directing agents.

Context

At the agentic level, plan mode is a workflow discipline: before making changes, the agent first explores the codebase, gathers context, and proposes a plan for human review. It’s the agentic equivalent of “measure twice, cut once.”

Plan mode addresses one of the core tensions of agentic coding: agents are fast and capable, but they can also be confidently wrong. An agent that starts editing files immediately may fix one thing and break three others because it didn’t understand the full picture. Plan mode inserts a pause between understanding and action.

Problem

How do you ensure an agent understands the problem and the codebase before it starts making changes?

Agents are biased toward action. Given a task, they’ll start writing code. This is productive for small, well-defined changes, but risky for larger or unfamiliar tasks. An agent that edits code before reading enough context may make changes that are locally correct but globally wrong: fixing a symptom instead of the cause, or modifying the wrong file because it doesn’t know where the real logic lives.

Forces

  • Speed is one of the agent’s main advantages, and planning slows it down.
  • Understanding requires exploration: reading files, tracing dependencies, examining tests. This takes tool calls and context window space.
  • Premature action can create messes that are harder to fix than the original problem.
  • Human review of a plan is faster and more reliable than review of scattered code changes.

Solution

When facing a non-trivial task, instruct the agent to work in two phases:

Phase 1: Explore and plan. The agent reads relevant files, examines the codebase structure, identifies the affected components, and proposes a plan. The plan should include: what files will be changed, what the changes will do, what assumptions the agent is making, and what risks it sees. The agent doesn’t modify any files during this phase.

Phase 2: Execute with approval. Once the human reviews and approves the plan (possibly with modifications), the agent proceeds to implement it. Changes follow the agreed plan, and deviations are flagged for discussion.

Some harnesses support plan mode as a built-in feature, restricting the agent from making changes until the plan is approved. Even without harness support, you can achieve this by instructing the agent: “Read the relevant code and propose a plan. Don’t make changes until I approve.”

Tip

Plan mode is most valuable for tasks involving multiple files, unfamiliar code, or architectural changes. For small, well-understood tasks (fixing a typo, adding a simple test) plan mode adds overhead without proportional benefit. Calibrate the level of planning to the risk of the task.

How It Plays Out

A developer asks an agent to refactor a payment processing module. Instead of starting to edit, the agent reads the module, its tests, and the three other modules that depend on it. It produces a plan: “I’ll extract the validation logic into a separate module, update the three callers, and adjust the existing tests. The public interface won’t change. I’ll add new unit tests for the extracted module.” The developer notices that the agent missed a fourth caller in a legacy system and points it out. The plan is updated before any code is touched.

A junior developer is working with an agent on an unfamiliar codebase. They make it a habit to start every task with “Let’s plan this first. Read the relevant files and tell me what you think we should do.” This practice teaches them the codebase while the agent does the exploration. They learn the architecture through the agent’s investigations, a form of guided discovery.

Example Prompt

“Before making any changes, read the payment module and its tests. Then produce a plan for extracting the validation logic into a separate module. List every file you’ll change and why. Don’t write code until I approve the plan.”

Consequences

Plan mode reduces the risk of large, scattered, hard-to-review changes. It surfaces assumptions early, when they’re cheap to correct. It gives the human a chance to contribute architectural knowledge that the agent may lack. And it produces better code reviews, because the reviewer already understands the intent behind the changes.

The cost is time. Planning takes tool calls and context window space that could have been spent executing. For simple tasks, plan mode is overhead. For complex tasks, it’s insurance. Learning when to plan and when to act is part of developing fluency with agentic workflows.

  • Depends on: Agent — plan mode is a workflow for directing agents.
  • Enables: Verification Loop — the plan provides the expected behavior that the verification loop checks against.
  • Contrasts with: Thread-per-Task — planning happens within a thread, while thread-per-task is about separating threads.
  • Uses: Context Engineering — plan mode is a form of front-loading context before action.
  • Enables: Human in the Loop — the plan review point is a natural place for human oversight.