Plan Mode and Agent-Sized Tasks for Coding Agents

Picture a 600-line change from your coding agent. It compiles. It passes the tests the agent wrote for itself. And it solves a slightly different problem than the one you had.

That's the expensive mistake: the right code for the wrong idea. Asking the agent to plan before it edits catches it while the fix is one paragraph, not one afternoon.

Claude Code and Codex both have a plan mode for this. Turning it on is the easy part. The real skill is knowing when to use it, and cutting the work into pieces the agent can finish and you can check.

When to plan and when to just ask

Anthropic's best-practices page is blunt that planning has overhead. It says to skip it for small, clear-scoped fixes like a typo, a log line, or a rename. Plan when you're unsure of the approach, when the change touches several files, or when you don't know the code well. Its test: if you could describe the diff in one sentence, skip the plan.

The one-sentence test works because it asks the question that matters: do you already know what the right change looks like? If you do, a plan is wasted motion. If you don't, the agent will pick an approach for you, and the first time you see its choice will be in the finished code.

OpenAI's Codex best practices make the same call from the other side. They recommend plan mode for complex tasks so Codex can gather context and ask clarifying questions first. For ambiguous work, they suggest having Codex interview you before any code gets written.

Plan mode in Claude Code

In plan mode, Claude can read files, run commands to look around, and write a plan. It can't edit your code until you approve (permission modes). There are three ways in:

Press Shift+Tab until the status bar shows plan mode.
Prefix a single prompt with /plan.
Start the session with claude --permission-mode plan.

When the plan is ready, Claude asks what next. You can approve and let it work on its own, approve and review each edit yourself, or keep planning and say what to change.

Press Ctrl+G to open the plan in your editor and rewrite it before approving. When a plan is nearly right, fixing it yourself is usually faster than explaining the change in another prompt.

The docs recommend four phases: explore, plan, implement, commit. The first two happen in plan mode. Implementation starts when you approve.

If a whole project should start in plan mode, set defaultMode to plan in .claude/settings.json.

Plan mode in Codex

In the Codex CLI, type /plan to switch into plan mode. You can put the request on the same line, for example /plan Propose a migration plan for this service (Codex slash commands). The docs say /plan doesn't work while Codex is already busy, so switch before you send the task, not halfway through.

If you only want to talk through the work with no chance of edits, the Codex approvals docs suggest switching to read-only with /permissions (approvals and security).

What a plan should contain before you approve it

Don't approve a plan because it's long. Approve it when you can answer yes to these five questions:

Does it name the files it will change? A plan that says "update the auth logic" hasn't looked yet.
Does it state the approach in one or two sentences you agree with? If the approach surprises you, stop there.
Does it say what it won't do? A line about what's out of scope stops the agent from "tidying up" code you didn't ask it to touch.
Does it name the check? Which test, build, or command proves each step works.
Does it list open questions? A plan with zero questions on unfamiliar code is guessing somewhere.

If any answer is no, reply with the missing piece and ask for a new plan. That costs a few hundred words. A wrong implementation costs you undoing it and starting a fresh session.

Cutting a feature into agent-sized tasks

A task is the right size for an agent when it ends in one check that passes or fails, and you can read all of its changes in one sitting. A good rule of thumb is one layer of the app per task: the database tables, then the code that reads and writes them, then the API, then the screen.

Here's a made-up example: add saved searches to a Next.js app. A signed-in user can save a search, see their saved searches, and delete one.

Task	Scope	Check that ends it
1. Schema	Add a `saved_searches` table and generate the migration	Migration generates cleanly and typecheck passes
2. Data access	`createSavedSearch`, `listSavedSearches`, `deleteSavedSearch`, scoped to the user	Unit tests for each, including one user can't delete another's
3. API routes	POST, GET and DELETE handlers that call task 2	Route tests for success, unauthenticated and not-found cases
4. UI	A save button on the search page and a list with delete	Component test plus a manual click-through on the dev server
5. Cleanup	Remove any duplication the first four introduced	Full test suite and lint pass with no behavior change

Each row is one prompt, or one plan and one implementation.

Task 2 includes the "one user can't delete another's" test on purpose. That's the bug a reviewer is most likely to miss when looking at screen code, so it gets its own check in the layer where it actually lives.

Two habits make the table work:

Write the plan to a file. In plan mode, ask the agent to write the breakdown to PLAN.md. Then start each task with "do task 2 from PLAN.md." The file survives a /clear in Claude Code or a /new in Codex, so every session starts from the same agreed scope.
Commit between tasks. A commit after each row gives you a clean diff for the next one and a safe point to go back to. Git workflows get their own page in this series.

Anthropic's best-practices page also suggests a separate reviewer at the end. Ask a subagent to compare the changes against PLAN.md: is every requirement done, and did anything outside the plan change? The page warns that a reviewer told to find gaps will usually find some, even when the work is fine. So tell it to report only gaps that make the code wrong or miss a stated requirement.

Where planning costs money

Plan mode reads files, and reading files uses tokens. On a subscription, that comes out of your allowance. With an API key, you pay for it directly.

A plan that reads half the repo to change one function isn't being careful. It's being expensive. Tell it where to look ("read src/search/ and src/db/schema.ts"). Use /context in Claude Code or /status in Codex to see how much of the agent's working memory is used up.

To put a monthly number on it, the coding agent cost calculator compares paying per token with the subscription price.

When to stop and read the code yourself

An agent will keep going as long as you let it. These are the signs to stop prompting and open the files yourself:

Two corrections didn't land. Anthropic's docs name this pattern. After two failed corrections, they say to run /clear and write a better first prompt. By then the conversation is full of approaches that didn't work.
The plan changed shape mid-task. If step three of an approved plan suddenly needs a new dependency or a schema change, that's a new plan, not a detail.
The diff touches files the plan didn't name. Stop and ask why before approving anything else.
It's grading its own homework. Tests written in the same session as the code can just check that the code does whatever it does. If the only proof is a test the agent just wrote, read the test.
You can't explain the approach. If you couldn't defend the change in code review, you don't understand it well enough to merge it.

None of these mean the agent failed. They mean the task was bigger or vaguer than the prompt admitted, and the fix is a smaller task, not a longer prompt.

Where this fits

Planning decides what the agent should change. Checking what it actually changed is a separate skill, and the next page in the series. For the instruction files that carry a plan from one session to the next, see CLAUDE.md and AGENTS.md for coding agents. For a planning agent built from scratch, the course lesson on building an agent that plans and executes tasks shows the same plan-then-act split in code.

Previous in the series: CLAUDE.md and AGENTS.md: what coding agents read. Next: Reviewing a coding agent's diff.