Plan Mode and Agent-Sized Tasks for Coding Agents
ZarifThe expensive mistake with a coding agent is a correct implementation of the wrong idea. It shows up as a 600-line diff that compiles, passes the tests it wrote for itself, and solves a slightly different problem than the one you had. Planning before editing is how you catch that while it costs one paragraph to fix instead of one afternoon.
Both Claude Code and Codex have a plan mode for this. The mode is the easy part. The skill is knowing when to use it and cutting the work into pieces an 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 is useful because it measures the thing that matters: whether you already know what the right change looks like. If you do, a plan is ceremony. If you don't, the agent will pick an approach for you, and you'll first see its choice in the diff.
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
Plan mode lets Claude read files, run exploratory shell commands, and write a plan, but not edit your source until you approve (permission modes). You can enter it three ways:
- Press
Shift+Tabuntil 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 how to proceed. You can approve and move into auto mode, approve and review each edit by hand, or keep planning and say what to change. Press Ctrl+G to open the plan in your editor and rewrite it directly before approving. When a plan is nearly right, editing it yourself is usually quicker than describing the change in another prompt.
The recommended loop in the docs has four phases: explore, plan, implement, commit. Explore and plan 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 the chat into plan mode, optionally with the request inline, for example /plan Propose a migration plan for this service (Codex slash commands). The docs note that /plan is unavailable while Codex is already working, 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? Out-of-scope lines prevent the drive-by refactor.
- 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 revised plan. That exchange costs a few hundred words of context. A wrong implementation costs a revert and a fresh session.
Cutting a feature into agent-sized tasks
A task is agent-sized when it ends in one check that passes or fails, and you can review the diff in a single sitting. A useful rule of thumb is one layer of the stack per task: schema, then data access, then API, then UI.
Here is an illustrative feature: add saved searches to a Next.js app, so a signed-in user can save a search query, list 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 authorization test on purpose. That is the bug a reviewer is most likely to miss in a UI diff, so it gets its own check at the layer where it lives.
Two practices make the table work:
- Write the plan to a file. Ask the agent in plan mode to write the breakdown to
PLAN.md, then start each task with "do task 2 from PLAN.md." The plan survives a/clearin Claude Code or a/newin Codex, and 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 point to reset 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 review the diff against PLAN.md, checking that every requirement is implemented and nothing outside scope changed. The page warns that a reviewer asked to find gaps will usually report some even when the work is sound. It suggests limiting the reviewer to gaps that affect correctness or the stated requirements.
Where planning costs money
Plan mode reads files, and reading files consumes tokens. On a subscription that comes out of your plan allowance. On an API key it's billed directly. A plan that reads half the repo to change one function is a cost, not diligence. Scope the exploration in the prompt ("read src/search/ and src/db/schema.ts"), and use /context in Claude Code or /status in Codex to see how full the window is. To put a monthly number on this, the coding agent cost calculator compares API token cost 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 signals to stop sending prompts and open the files:
- Two corrections didn't land. Anthropic's docs name this pattern and prescribe
/clearand a better first prompt after two failed corrections. The context is now full of the 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 testing its own assumptions. Tests written in the same session as the code can simply encode whatever the code 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. The next step is checking what it actually changed, which is a different skill. For the context features that make a plan carry across sessions, see Claude Code features that matter after the first demo. 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 Code features that matter after the first demo. Next: Reviewing a coding agent's diff.