How to write a spec an AI agent will actually follow

A good spec is short

Precise enough that implementation can't silently diverge; short enough that a human actually reviews it. Skeleton:

## Intent        why this exists, in one or two lines
## Scenarios     concrete user journeys (who does what)
## Requirements  numbered, testable (EARS)
## Acceptance    observable criteria that define done
## Edge cases    the failure modes you care about
## Constraints   performance, compliance, stack bounds
## Non-goals     what this feature is NOT

If a requirement can't fail, it's a wish

Each requirement must be specific enough to point at the running system and say "satisfied" or "not satisfied" with no debate.

The two most-skipped sections

• Edge cases — agents handle the happy path unprompted; the edges are where unstated intent dies. State them.
• Non-goals — the difference between building what you scoped and building what the feature name vaguely implies.

Written with the agent, owned by you

Let the specify phase draft it — then cut, correct and sharpen. An unreviewed spec is paperwork, not alignment.

Free cheat sheet: the whole method on a few pages — the loop, spec anatomy, EARS, right-sizing — SDD Cheat Sheet.

Go deeper: the full reference — every phase, the tool landscape, three walkthroughs — Spec-Driven Development: The Complete Guide.

What's the one section you always forget in a spec? Mine used to be non-goals. 👇