In 30 seconds
- The spec, not the code, carries the intent.
- Good specs include examples, constraints and acceptance tests.
- Specs are versioned, reviewed and refined like code.
What a good spec contains
- The user and the goal, as in a user story
- Concrete examples, ideally Given-When-Then
- Constraints: performance, security, style
- Acceptance tests that define done
- What's explicitly out of scope
Not big design up front
Agile rejected huge specifications written months ahead. Spec-driven development keeps specs small and just in time, one story or slice at a time, refined in backlog refinement. It's closer to BDD than to waterfall.
Why it matters with AI
AI follows instructions literally. Vague intent gives plausible but wrong code. A precise spec plus automated checks lets AI do more of the building while humans own the intent. See user stories for AI agents.
Myth vs reality
Myth · Specs mean going back to waterfall.
Reality · Specs stay small, just in time and revisable.
Myth · The AI can write the spec.
Reality · AI can draft; humans must own intent and trade-offs.
Myth · Code no longer matters.
Reality · Code still needs review, tests and maintenance.
FAQ
Who writes specs?
The Product Owner and team together, as with stories.
Where do specs live?
Close to the code, versioned with it.
How detailed should a spec be?
Enough that a newcomer, human or AI, could build it correctly.