Plan Mode — The Most Underrated Superpower in AI Coding Agents

When I first started using plan mode in Claude Code, it completely changed how I approach problems with AI coding agents.

Before that, I did what most people do:

Ask for a feature → let the agent write code → fix the mess afterward.

The results were as expected:

• Over-engineered implementations

• Scattered edits across the repository that were hard to review

• Code that technically worked but slowly turned into a black box

Then I discovered plan mode.

Instead of jumping straight into implementation, the agent was forced to slow down, analyze the codebase, ask clarifying questions and produce step-by-step instructions. The output became drastically better, and maintainable.

I assumed plan mode made the model think harder. It doesn’t. It simply removes the ability to act. That constraint forces analysis first. Understanding this distinction is the key to using AI coding agents effectively. Let’s break it down

Plan mode works by changing three things.

• The system prompt

• Allowed tools

• Execution context

System Prompt

Every coding agent runs with a system prompt that defines its role, rules, and constraints. On each step, the model combines this with the user prompt, current workspace state, and tool outputs to decide what to do next. Because it has highest priority, it enforces safe, consistent behavior and overrides conflicting instructions.

In build mode, the objective is execution. The agent is encouraged to modify files, run commands, and complete the task as quickly as possible. (Interestingly, Codex is designed to be more autonomous and Claude is designed to collaborate more with user. That is an interesting topic for a separate blog post)

In plan mode, the objective shifts to analysis. The agent is instructed to read the codebase, ask clarifying questions, and produce a step-by-step plan without making changes.

You can find a reverse engineered system prompt for claude code plan mode here. The interesting part in that system prompt is,

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
- Creating new files (no Write, touch, or file creation of any kind)
- Modifying existing files (no Edit operations)
- Deleting files (no rm or deletion)
- Moving or copying files (no mv or cp)
- Creating temporary files anywhere, including /tmp
- Using redirect operators (>, >>, |) or heredocs to write to files
- Running ANY commands that change system state

Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.

Similarly, you can find the exact plan mode system prompt for opencode in their open source codebase here.

Another interesting part from the prompt that I really like is

**NOTE:** At any point in time through this workflow you should feel free to ask the user questions or clarifications. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.

This is the key part that makes plan mode more powerful. It doesn’t make assumptions, and provides a questionnaire to the user to come up with a concrete plan. The same model produces very different output simply because the goal defined in the prompt is different.

Tool restrictions

In claude code, the plan mode is not just a system prompt, but also a permission model. A list of available tools is sent along with the system prompt to the model. Then the model returns instructions for the agent to execute the tools and send the output in next step. The coding agent makes sure that only the allowed tools are executed, irrespective of what the model asks to do.

Opencode also behaves in a similar way. Here is the source where it defines the default permissions for plan mode. It resolves to something like below,

 "plan": {
      "model": "<default>",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
  }

Because it cannot modify anything, it is forced to reason first. This constraint has a larger impact on output quality than any prompt wording. Removing the ability to act naturally encourages the model to analyze.

The role of the plan artifact

The plan itself is not just documentation. It is an execution artifact. In most plan-based agents, the plan becomes the input to the next phase. How this handoff happens has a big impact on behavior.

Claude code

In Claude Code, plan mode produces a detailed markdown file with explicit, step-by-step instructions. This file is saved to a special directory (usually in ~/.claude folder) and treated as the single source of truth for the next phase.

When switching from plan → build:

• the session context is cleared

• a fresh agent starts

• only the markdown file is provided as input

Effectively, plan → plan.md → prompt for build

Because the steps are already concrete, you can often allow edits and execute the entire change in one pass. In practice, this works well. I frequently iterate on the plan first, refine it until it’s precise, and only then switch to build. Once the plan is solid, implementation becomes mostly mechanical.

Sometimes I keep the plan inside the project directory instead of the default location so I can review and tweak it manually before execution.

Cursor

Cursor follows a similar model. It also generates a plan artifact and treats it as the basis for execution. Since it’s an IDE, you can inspect and edit the plan directly before building. The behavior is effectively the same: clear context and execute from the plan.

Opencode

OpenCode handles this differently. There is no dedicated plan file by default.

The model produces a plan conversationally, but when switching to build:

• the session context is preserved

• only the system prompt changes

• edit tools become available

So the same conversation continues with more permissions. It uses the build-switch system prompt to indicate that model is now allowed to use edit tools (source).

Because context is not reset and there is no explicit plan artifact, execution is less deterministic. The model still carries earlier assumptions and exploratory reasoning, which sometimes leads to premature edits. In my experience, this makes one-shot execution less reliable compared to Claude’s “plan → clean build” workflow. This is much less of an issue if you are using a high reasoning model though.

To get similar behavior, I explicitly ask OpenCode to write a plan.md, refine it manually, then start a fresh session and feed that file as input myself. That recreates the same “compiled prompt” approach.

Summary : When to Use Plan Mode vs Build Mode

Most official docs explain plan vs build in abstract terms. I found that too vague. After using these agents daily, I follow a simple rule of thumb.

Build mode

Use build when the task is simple and deterministic.

• easy, one-shot changes

• straightforward implementation

• only one obvious way to do it

• I already know exactly how I’d code it myself

• writing documentation, RFC or specs

Most people assume docs or RFCs belong in plan mode. In practice, they’re iterative editing tasks. It’s faster to write, tweak, and refine directly in build mode.

Plan mode

Use plan when thinking matters more than typing.

• changes that affect multiple files

• unclear or open-ended problems

• I’m not sure how to implement it yet

• I want the agent to propose steps first

• brainstorming or exploring a codebase

• I don’t want the agent touching files yet

If I have to think, I use plan. If I already know the solution, I use build.

Final takeaway

Plan mode doesn’t make the model smarter. It makes the instructions clearer. Clear instructions produce better code. Most developers don’t naturally write detailed prompts for an LLM. Plan mode does that for you. It turns vague intent into a concrete specification, and that specification becomes the prompt for the build agent.

Once you understand this, the workflow becomes simple: plan first, then execute.

That shift alone dramatically improves reliability.