How to Write a Spec an AI Agent Will Actually Follow

A good spec is not a long spec. It is a document precise enough that implementation cannot silently diverge from it, and short enough that a human actually reviews it. There is no mandatory template, but a handful of sections earn their place on almost every feature — because they map to the questions an implementer, human or agent, cannot answer alone.

Intent and Scenarios

Open with a sentence or two of intent — the user need this serves — then the concrete scenarios: who does what, and what happens. Write them as journeys, not abstractions: "a signed-in user pastes a URL and gets a shortened link" beats "the system provides URL shortening functionality" in every way that matters.

Requirements and Acceptance Criteria

The core is a numbered list of things the system must do, in testable language — each specific enough that you could point at the running system and say "satisfied" or "not satisfied" with no debate. Pair them with acceptance criteria: the observable checks that define done. If a requirement cannot fail, it is not a requirement, it is a wish.

The Two Most-Skipped Sections

Edge cases and non-goals look optional and are not. Agents handle the happy path unprompted; the edges — the empty input, the expired session, the concurrent edit — are exactly where unstated intent goes to die, so state them. And non-goals bound the scope: they are the difference between an agent building what you scoped and building what the feature name vaguely implies.

Written With the Agent, Owned by You

You rarely write a spec from a blank page — the specify phase drafts one from your description. But the draft is a proposal about what you might mean; your review pass, where you cut, correct and sharpen, is what turns it into a record of what you do mean. A spec you have not truly reviewed gives you the paperwork of alignment without the alignment.