TL;DR
People who hand features to coding agents disagree about specs: some write them in full, others find a capable agent infers most of what it needs from the codebase. Each side is right about a different part of the job. Let the agent discover what the repository shows, and write down only what someone has to decide: who the feature serves, how it behaves, what it excludes and how you will check it. Add depth as risk grows, and judge the effort by the rework it prevents.
Specify the decisions and let the agent find the facts
An agent that can read your codebase does not need you to describe the codebase. It needs the decisions that are not in it yet, and the length of that list, not the length of a template, is how much specification a feature needs.
In August 2026 a Cursor user asked on the Cursor forum how much intent an agent needs once it can read an existing codebase. Given a few high-level categories for a large existing system, Cursor had inferred navigation, sections and how the new part should connect. A Cursor staff member replied that with stronger models the marginal value of his spec "goes negative". The poster answered that the context had not disappeared; the agent had retrieved it. Earlier in the year a Hacker News member asked whether people were still doing spec-driven development, particularly on existing codebases, or whether agent instruction files, skills and prompts had taken over that job.
Much of what a traditional spec contains is already in the code, where a capable agent can find it. The rest has never been written, because nobody has decided it yet. That part is what an agent needs from you.
Vendor guidance (checked on 1 October 2026) agrees. Claude Code's best practices say to skip the plan when you could describe the diff in one sentence, and to have Claude interview you and write a spec first for larger features. Codex's best practices say clear prompting is not required to get value but makes results more reliable, "especially in larger codebases or higher-stakes tasks."
What the code can tell the agent, and what it cannot
Comparison
| The agent can usually discover it | Someone has to decide it | |
|---|---|---|
| Placement | Files, modules and the layer that owns similar behaviour | Whether the feature belongs in this product at all |
| Construction | Framework, existing patterns, naming and test commands | Which of two reasonable designs to accept when they trade off |
| Users | Roles and permissions that already exist in the code | Which users get the feature, and who must not |
| Behaviour | How neighbouring features behave today | What should happen on failure, on empty input and at limits |
| Data | The current schema and how it is used | What may be stored, changed, migrated or deleted |
The left column is why the staff member's experience is plausible: an agent that reads the code first does not need it restated, and Claude Code's guidance lists "anything Claude can figure out by reading code" among the things to leave out of CLAUDE.md. The right column is why the Hacker News question keeps returning: reading cannot tell the agent what you intend where the code is silent.
One trap sits between the columns: code shows today's behaviour, bugs and stopgaps included, and an agent may extend them as if intended. When the feature depends on a rule the agent inferred, ask it to state the rule so you can confirm it. The article on getting a coding agent to reuse existing code covers pointing it at the examples you consider canonical.
The minimum a feature needs before building starts
For most features the decided part is short. Write it in a file the agent can read and you can review:
- Who it is for. The user or role, in the application's own words, and anyone who must not get it.
- The behaviour. What the user can do afterwards and sees, including the main failure case.
- What it excludes. Concrete behaviours you do not want, such as "does not email the customer"; agents fill gaps with plausible extras.
- Decisions already made. Any choice the code cannot reveal, with its answer.
- Open questions. Anything undecided, marked open, with the instruction to stop and ask rather than guess.
- Done when. The check that proves it works: tests, a reproduced scenario or a manual step.
Codex suggests a goal, context, constraints and a "done when" condition; Claude Code describes the most useful specs as self-contained, naming the files and interfaces involved, stating what is out of scope and ending with an end-to-end verification step. For a small correction this fits in two sentences; for a feature, usually under a page. A page that keeps growing is a prompt to ask whether the feature should be split, though some cohesive changes do need more detail.
Let risk and uncertainty set the depth
Size alone is a poor guide: a one-line change to a permission check is small and risky, while a new settings page can be large and routine. Two hypothetical requests:
Comparison
| Fix a typo in a sign-in error message | Let customers cancel a subscription mid-cycle with a prorated refund | |
|---|---|---|
| What the agent can find | The form, the message and its test | Billing code, subscription states and refund paths |
| What only you can decide | The corrected wording | Who may cancel, how the refund is rounded, what happens to add-ons, whether the customer is emailed, and what happens if the payment provider fails |
| Specification | The wording and "the existing test still passes" | A written spec with each decision answered, the exclusions and acceptance checks for amounts and failure paths |
| Cost of a wrong guess | A second small edit | Wrong refunds and a data fix |
Write the deeper specification when any of these holds:
Decision guide
- If the change moves money, alters permissions or touches personal data, answer every decision first.
- If it changes stored data or needs a migration that is hard to undo, write it down.
- If it changes a public interface or behaviour other code depends on, write it down.
- If you are unsure of the approach or unfamiliar with the code, ask the agent to plan and question you first.
- If the diff fits in one sentence and a wrong guess is cheap, a clear request with a "done when" line is enough.
Depth can also change mid-flight: if the agent's plan reveals a migration or contract nobody mentioned, deepen the specification before it continues.
Ask for the questions before the code
The quickest way to find the decisions is to let the agent hunt for them. Claude Code's guidance suggests a minimal prompt asking Claude to interview you with its AskUserQuestion tool and write a spec file, then implementing it in a fresh session. Codex suggests asking it to question you and challenge your assumptions, and Cursor's Plan Mode asks clarifying questions before it produces a plan.
Sort what comes back. A question the repository can answer goes back to the agent to look up. A choice between reasonable options is yours to answer in the spec. A question you cannot answer yet stays marked open, because an agent that meets an unanswered decision mid-build usually settles it by assumption, and you find out in review. The article on keeping a coding agent in planning until the plan is approved describes how to hold the build until those answers exist.
Check that the spec reduced rework
A specification earns its time only by preventing rework. Counting documents shows nothing about that; a simple record kept over a few weeks does:
- For each change, note roughly how long the specification took.
- When something is reworked after review or release, tag the cause: a missing decision, a wrong decision, the agent not following the spec, or an ordinary code defect.
- Note every question raised during implementation that the spec should have answered.
- Compare small and risky changes separately: keep specs light where they cause no decision-related rework, and add the recurring missing questions to the minimum where they do.
Only the first two causes say anything about specification depth. The third points at how the agent was instructed or checked, and the fourth at testing.
Paqad builds this sizing into its workflow on Claude Code and Codex CLI. A deterministic classifier places each change in a fast, graduated or full lane by complexity and risk; a feature request never lands in the fast lane. On the graduated and full lanes a source edit waits for a frozen specification, and the freeze refuses a spec with an unresolved open question or an acceptance criterion without a proof method. An optional pipeline, off by default, asks one batch of questions only when something is undecided. After the freeze, a change of goal or work that contradicts the spec opens a decision pause. The limits: a frozen spec has passed structural checks, not a test of whether the requirements are complete; the sign-off name is recorded, not authenticated; shell writes are not intercepted; and on Paqad's other supported tools these are instructions without blocking hooks. Paqad's page on the path from plan to frozen spec shows which steps a script checks and which wait for you.
Frequently Asked Questions
How much specification does an AI coding agent need before building a feature?
Enough to settle every decision the code cannot reveal, and no more. The amount also shifts over a project's life: in a young repository there is little for the agent to discover, so more has to be written down, while in a mature codebase with consistent patterns much of what a spec once carried can be left to the agent's own reading.
What is the minimum information for this feature's users, behaviour and exclusions?
Name the users in the application's own terms, describe the behaviour as something observable (given this state, when the user does this, they see that), and state each exclusion as a concrete behaviour. "Keep it simple" is not an exclusion an agent can test against; "no bulk cancellation in this change" is.
Which details can the agent discover from the code, and which require a product decision?
A useful test: if two competent engineers could choose differently and both choices would pass code review, it is a decision rather than a discovery. That includes cases where the codebase holds two conventions for the same thing; picking one is a decision, even though both are visible in the code.
How should specification depth change with risk, uncertainty and the size of the change?
Risk sets the floor, uncertainty sets the method, and size mostly decides how the work is split. A large but routine change may need a short spec and several smaller tasks; a small change near money or permissions needs every decision answered. High uncertainty with low risk is usually better served by a throwaway prototype than by a longer document.
How will we know that specification effort reduced rework rather than just produced more documents?
Judge the record over a set period, such as a month, rather than after one memorable failure. Watch for waste in both directions: rework tagged as a missing decision in risky changes means those specs are too thin, while spec sections that answered questions nobody needed show where the minimum can shrink.