# What is plan mode in a coding agent?

Plan mode is a coding agent setting in which the agent proposes a plan without editing files, so a person can review the approach before any code changes.

Last updated September 29, 2026, 8 min read

## Learning objectives

After reading this article you will be able to:

-   Define plan mode
-   Explain what to check in an agent's plan
-   Compare plan review with code review

## Related content

-   [What is a coding agent?](https://specstory.com/learning/ai-coding/coding-agent)
-   [What is spec-driven development?](https://specstory.com/learning/ai-coding/spec-driven-development)
-   [What is human-in-the-loop for coding agents?](https://specstory.com/learning/ai-coding/human-in-the-loop)
-   [What are acceptance criteria?](https://specstory.com/learning/ai-coding/acceptance-criteria)

## What is plan mode in a coding agent?

Plan mode is a [coding agent](https://specstory.com/learning/ai-coding/coding-agent) setting that blocks file edits while the agent reads code and writes a plan for a person to approve. The plan usually states the approach, the files to change, and how the work will be checked. Approval ends plan mode, and the agent then writes the code.

Claude Code's [documentation](https://code.claude.com/docs/en/common-workflows) says that in plan mode "Claude reads files and proposes a plan but makes no edits until you approve." A plan is usually much shorter than the diff it leads to, so changing the approach there costs less than rewriting code.

Planning adds a step. Claude Code's [best practices](https://code.claude.com/docs/en/best-practices) recommend it when the approach is uncertain, the change spans several files, or the code is unfamiliar. For a small fix, the guide says "If you could describe the diff in one sentence, skip the plan."

## How does plan mode work?

A session in plan mode usually moves through these steps:

1.  A person turns on plan mode, e.g. by pressing `Shift+Tab` in Claude Code until the status bar shows plan mode, and describes the task.
2.  The agent reads files and runs commands to explore the codebase. Tools that edit files stay blocked.
3.  The agent can ask the person questions where the request leaves a choice open.
4.  The agent writes the plan and presents it for review.
5.  The person edits the plan, sends it back with comments, or approves it.
6.  Approval ends plan mode, and the agent edits files and runs commands to carry out the plan.

Diagram: Where plan review sits in a coding agent's task

The plan review checks the approach before any file changes. Only the later code review and run check what the agent built.

Approving the plan is one approval point in a [human-in-the-loop](https://specstory.com/learning/ai-coding/human-in-the-loop) setup. One careful reading covers the whole approach. Many separate edit prompts invite [approval fatigue](https://specstory.com/learning/environments/approval-fatigue) instead.

In Claude Code, the approval can switch the session to auto mode, where a classifier model reviews most actions. The plan review is then often the last approval a person gives before the pull request.

Claude Code writes plan files to `~/.claude/plans` in the home directory unless the `plansDirectory` setting names another folder. The questions and answers behind a plan stay in the session transcript, which is part of [AI coding session history](https://specstory.com/learning/ai-coding/ai-coding-session-history). An optional approval choice clears the planning context, so the agent writes the code from the plan alone. What the agent carries into coding is a question of [context engineering](https://specstory.com/learning/ai-coding/context-engineering).

## What is an example of a plan worth reviewing?

Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme turns on plan mode and asks a coding agent to "Let customers edit their delivery address during checkout." The agent reads 6 files, asks whether the address can change after payment, and returns this plan:

```text
Plan: let customers edit the delivery address during checkout

1. Add an Edit button to the address step in checkout/AddressStep.tsx.
2. Add updateAddress() to checkout/api.ts and save the new address.
3. Call resetCart() in cart/store.ts so the shipping cost reloads.
4. Move checkout/utils.ts to the new HTTP client.
5. Test that the saved address equals "12 Elm Street".
```

The developer reviews it in 6 steps:

1.  The developer reads `resetCart()` in `cart/store.ts`. The function removes the cart's items, so step 3 would empty the cart on each address change.
2.  The developer opens the plan in an editor, e.g. with `Ctrl+G` in Claude Code, and deletes step 4, which the request does not need.
3.  The developer replaces step 3 with "Recalculate the shipping cost and keep the cart unchanged."
4.  The plan's only test checks the address, so the developer adds a step to test that the cart keeps 2 items.
5.  The developer approves the plan, and the agent changes 4 files, including one test file, and reports that its tests pass.
6.  The developer compares the diff with the plan, then runs the checkout on a staging copy. The cart keeps its 2 items.

The plan review stopped the cart bug before any code existed, but only a run shows what the checkout does. This example is simplified. A real plan would also cover the payment step, which reads the saved address.

## What should you check in a plan?

A reviewer checks seven parts of the plan:

-   **The goal.** The plan's summary of the request matches what the person asked for.
-   **The choices.** Where the request said nothing, the plan picks a default, e.g. whether the address can change after payment. Each choice gets a person's approval or goes back as a question.
-   **The claims about existing code.** A step can rest on what a function does, e.g. that `resetCart()` reloads the shipping cost. The reviewer opens that function and checks the claim.
-   **The scope.** The listed files cover the task and nothing else. A step that touches unrelated code becomes an [out-of-scope edit](https://specstory.com/learning/verification/out-of-scope-edits), and it is cheaper to delete from a plan than from a diff.
-   **The risky steps.** Steps that are hard to undo, e.g. a database migration, are named so that a person can approve them separately.
-   **The checks.** The plan names [acceptance criteria](https://specstory.com/learning/ai-coding/acceptance-criteria) that a test can check, not only "tests pass." It can also put a failing test first, as in [test-driven development](https://specstory.com/learning/testing/test-driven-development).
-   **The finish line.** The last step matches the team's [definition of done](https://specstory.com/learning/verification/definition-of-done-for-coding-agents), e.g. running the changed feature once in a browser.

A plan that is too long to read tends to get approved unread, which is a [rubber-stamp review](https://specstory.com/learning/glossary#rubber-stamp-review) at the planning step.

## Does plan review replace code review?

Plan review does not replace [code review](https://specstory.com/learning/code-review/code-review), because a plan describes the code the agent will write, and code review reads the code it wrote. The two reviews check different things:

| Aspect | Plan review | Code review |
| --- | --- | --- |
| When it happens | Before any file changes | After the agent edits files |
| What it reads | The approach, the files, and the planned checks | The diff and its tests |
| What it can catch | A wrong goal, wrong scope, or missing check | Bugs in the code and changes the plan did not list |
| What it misses | Mistakes made while writing the code | Behavior that shows only when the software runs |

An approved plan is text in the agent's context, not a rule that the tool enforces. The agent can depart from the plan when a step fails, and its final summary may not say so. A reviewer compares the diff with the approved plan, which is easier when the plan file sits next to the code.

Plan mode also blocks less than its name suggests. Claude Code lets the agent run shell commands during planning and screens those outside a read-only set with a classifier or a permission prompt. Claude Code's [permission docs](https://code.claude.com/docs/en/permission-modes) also say that plan mode's blocks do not apply in an interactive terminal session that can switch to bypass permissions mode. There, the model is only instructed not to edit.

## How is plan mode different from spec-driven development?

Plan mode is a setting in one agent session, while [spec-driven development](https://specstory.com/learning/ai-coding/spec-driven-development) is a way of working built around a reviewed spec. A plan says how the agent will build one change. A spec says what the software should do and why, usually with acceptance criteria.

A plan usually serves one task and stays outside the repository. A spec is a file, often in the repository, and later changes to the feature can start from it.

The two combine. In spec-driven development, a plan step follows the spec, and plan mode is one way to produce and review that plan.

## How does SpecStory help with plan mode?

The approved text shows where the planning ended, not how it got there. The questions, answers, and rejected options stay in the session.

SpecStory keeps the conversations behind your code. It keeps the prompts and decisions from your coding agent sessions, so you can reuse them when the next task begins. Your sessions become local Markdown files you can read, search, and keep alongside your code. Saving a conversation with SpecStory does not itself test the software.

[Get SpecStory →](https://specstory.com/specstory)

## FAQs

### When is plan mode worth the extra step?

Plan mode is worth the extra step when a wrong approach would cost more to undo than the plan costs to read. For a fix whose diff a person could describe in one sentence, the plan usually costs more time than it saves.

### Can an agent change its plan after you approve it?

An agent can change its plan after you approve it, because the approved plan is text in its context, not a rule that the tool enforces. You find the change by comparing the diff with the approved plan in code review and asking about each difference.

### What should you do with a plan that is too long to read?

A plan that is too long to read should go back to the agent with a request for a shorter version. The shorter plan lists only the decisions, the files, and the checks. If it stays long, split the task into smaller tasks, each with its own plan.

### Should a plan be saved with the code?

A plan is worth saving with the code when reviewers will compare the diff with it. By default, Claude Code keeps plan files in the home directory, outside the repository. A team that wants plans next to the code can point the plan folder at the repository.

---

Source: [What is plan mode? | Plan review vs. code review | SpecStory](https://specstory.com/learning/ai-coding/plan-mode)