Agreeing what an agent will do before it does it prevents the most expensive failure in agentic coding: a long, confident run in the wrong direction that you then pay to unwind, having first paid to review it. A good spec has three parts: where the change goes, what must not change, and what done means. Plan mode is that discipline formalised, with the agent doing the drafting and the edits blocked until you approve. Correcting a plan costs one message; correcting an implementation costs the run, the review, and the revert.
- The expensive failure is a wrong direction discovered late, after you have paid to review it.
- A spec costs minutes. Unwinding a confidently wrong implementation costs hours.
- Three parts: where, what must not change, what done means.
- The middle part is the one people omit, and it is why two-file tasks become nine-file diffs.
- Plan mode is this formalised, it is free, and both major CLIs ship it.
- A spec that keeps being true belongs in a project memory file, not in a message.
Why the leverage moved
The argument for specs used to be a management argument, and it lost most of the time because writing code was the expensive step and specs did not make it cheaper. Both halves of that changed.
What each phase costs, before and after.
| Phase | Before agents | With agents |
|---|---|---|
| Deciding what to build | Moderate | Now the bottleneck |
| Writing the code | The bottleneck | Cheap |
| Reviewing it | Moderate | Expensive |
| Fixing a wrong direction | Painful | Very expensive |
There is a second, less obvious cost. You do not discover the wrong direction for free: you discover it by reviewing the diff, which means you paid full review price for work you are about to throw away. Anthropic makes the same point in its own cost guidance, recommending plan mode for complex tasks specifically to prevent expensive re-work when the initial direction is wrong.
What a good spec contains
Three parts. Not a document, not a template with fourteen headings, three sentences that answer three questions.
- Where. The files and symbols involved. This alone removes the exploration phase, which is the most expensive part of any agent task and the main driver of turn count.
- What must not change. The constraint clause people omit, and the reason a two-file task becomes a nine-file diff.
- What done means. A test that passes, a behaviour you can check, a command that exits zero. Something the agent can verify without asking you.
Add retry with exponential backoff to the HTTP client in
src/lib/http.ts. Cap at 30 seconds, five attempts, only for 5xx
and network errors.
Do not change the public signature of request(). Do not add a
dependency.
Done when src/lib/http.test.ts passes, including a new case that
asserts the cap is respected.A template worth keeping in a snippet
Goal: <one sentence, the outcome not the method>
Where: <files, functions, symbols>
Constraints: do not change <public API / schema / behaviour X>;
do not add dependencies; do not touch <dir>
Done when: <command that exits zero, or behaviour you can check>
Out of scope: <the adjacent thing it will be tempted to fix>The last line does more work than it looks like it should. Agents are drawn to adjacent improvements, and naming the one you can see coming ("do not refactor the logger while you are in there") converts a predictable argument into a non-event.
Plan mode formalises it
Both major CLIs ship a read-only mode where the agent investigates and proposes an approach without editing anything. It is the same discipline with the agent doing the drafting, which matters because the agent knows things about the codebase you do not.
| Step | What happens |
|---|---|
| Enter plan mode | The agent can read and analyse, and edits are blocked |
| It investigates | Reads the relevant code, finds the real constraints |
| It proposes | A plan you can correct before anything is written |
| You correct it | The cheapest correction available |
| You approve | It exits plan mode and executes an agreed plan |
The exact mechanics, as of August 2026
- Claude Code: press
Shift+Tabto cycle into plan mode, or prefix a single prompt with/plan. Start there withclaude --permission-mode plan, or make it the project default with"permissions": {"defaultMode": "plan"}in.claude/settings.json. - Editing the plan:
Ctrl+Gopens the proposed plan in your editor so you can change it directly rather than describing the change in prose. - Approving: you pick how it proceeds, either approving edits individually or handing it more autonomy. "No, keep planning" is a first-class option and is the one to use when the plan is 80% right.
- Codex CLI: the equivalent is running under the
read-onlysandbox while you agree the approach, then switching toworkspace-writeto execute it. Inside a git repository Codex starts onworkspace-writewithon-requestapprovals, and OpenAI recommendsread-onlyfor a folder that is not version controlled.
Where the spec lives afterwards
A spec for one task belongs in the prompt. A constraint that will be true next week belongs in a file, because a constraint stated in a conversation has the lifetime of that conversation and can be summarised away by compaction.
| Kind of statement | Where it goes |
|---|---|
"Do not change request() in this task" | The prompt |
| "Never add dependencies without asking" | CLAUDE.md or AGENTS.md |
"src/gen/ is generated, edit the proto" | Project memory, near the top |
| "Backend rules differ from the web app" | A nested memory file in that directory |
"Never push to main" | A deny rule. Not a sentence |
AGENTS.md is the cross-vendor version of the same idea: an open format for agent-facing project instructions, supported by more than twenty tools including Codex, Gemini CLI, Cursor, Zed, Aider, Jules, and Copilot, and used by more than 60,000 open-source projects according to the specification site. Nested files resolve nearest-first, so a monorepo can give each subproject its own rules; OpenAI own repository carries 88 of them. Both claude and codex ship an /init command that drafts a first version from the repository.
When to skip it
Specs are not free and the discipline collapses if you apply it uniformly. The rule is proportional: spec when the cost of a wrong direction exceeds the cost of writing three sentences.
| Task | Spec first? |
|---|---|
| One-line fix you can describe exactly | No |
| A mechanical edit with a complete rule | No |
| A change across more than about three files | Yes |
| Anything in unfamiliar code | Yes |
| Anything touching data, schemas, or migrations | Yes |
| Anything you intend to run unattended | Yes |
| Exploration where you do not know the answer | Plan mode, which is exploration as spec |
Does it actually pay off
The comparison people make is spec-then-implement against implement, which specs lose. The comparison that matters is spec-then-implement against implement, review, discover, unwind, re-implement, review again.
The same medium task, both ways.
| Path | What you spend |
|---|---|
| No spec, right direction | One run, one review. Fastest possible outcome |
| No spec, wrong direction | One run, one full review, a revert, a second run, a second review |
| Spec, right direction | Ninety seconds, one run, one faster review because you know what to expect |
| Spec, wrong direction | Ninety seconds, one message to correct it, then as above |
The second row is the one that decides it, and its frequency is not low. Three signals tell you the habit is working: fewer turns per task, smaller diffs per task, and a review that starts with "is this right" rather than "what is this".
Questions people ask
Agreeing what the agent will do before it does it: which files, what must not change, and what done means. It prevents the most expensive failure, which is a wrong direction implemented quickly and completely.
For anything beyond a few files, yes. A spec costs minutes; unwinding a confidently wrong implementation costs hours, and you have to review the wrong version at full price first in order to discover that it is wrong.
Where the change goes, what must not change, and what done means. The middle one is most often omitted and is what stops a small task becoming a large diff. Give a verification target rather than an adjective.
It is the same discipline with the agent drafting. It investigates and proposes without editing, so you correct a plan for the price of one message rather than correcting an implementation. Press Shift+Tab in Claude Code, or start with --permission-mode plan.
The equivalent is running under the read-only sandbox while you agree the approach, then switching to workspace-write to execute it. Inside a git repository Codex starts on workspace-write with on-request approvals, so read-only is the setting you reach for deliberately.
A task constraint belongs in the prompt. A constraint that stays true belongs in CLAUDE.md or AGENTS.md, because anything stated only in a conversation can be lost to compaction. A rule you must never break belongs in a deny rule.
One-line fixes you can describe exactly, and mechanical edits with a complete rule. Anything unfamiliar, multi-file, touching data, or intended to run unattended is worth the ninety seconds.
It slows the start and speeds up everything after it. It also makes your review faster, because you arrive knowing what the diff should contain rather than reconstructing the intent from the code.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.