Spec-driven development with AI agents
The short answer
Spec-driven development means writing down what to build and how you'll know it's done before an AI agent starts, then keeping that short spec as the source of truth while it works. It isn't a long document. For most jobs it's a problem, the outcome, the files it touches and a few Done When lines.
Why it matters more with agents
A person who isn't sure asks. An agent that isn't sure often guesses, and guesses confidently. A short spec removes the guessing. The agent knows what to build, which files to touch and when it's finished.
What a spec has in it
- Problem. What the person experiences.
- What to build. The outcome first, then the direction.
- Files to touch. The parts of the code that change, checked against the repo.
- Done When. Lines in the form "Given a state, when an act, then something you can check". Each one gets checked on its own.
How short can it be?
As short as the job allows. A copy fix needs a line. A new feature needs a page at most. If a spec takes longer to write than the job takes to build, it's too long.
Spec-driven development vs vibe coding
Vibe coding is prompting and seeing what comes back. It's great for trying an idea. Spec-driven development is for work that has to be right and has to last, or that more than one agent will touch. Many founders do both: vibe code to explore, then write the spec for the version you keep.
Is it just waterfall?
No. Waterfall plans everything up front. A spec covers one job, and the next job's spec can change because of what this one taught you.
Doing it in Claude Code, Cursor, Codex and Grok
Any agent can work from a spec: paste it, link it or keep it in the repo. You can write it yourself, ask your agent to draft it from your notes, or ask a tool to draft it, then edit. What matters is that every agent on the job reads the same one. See spec-driven development in the glossary.
Copy this
Start each job from this, and keep it where every agent on the job can read it.
# <title: what becomes true>
## Problem
<1-2 sentences>
## What to build
<outcome, then direction>
## Files to touch
- <path> (new|modify)
## Done When
- Given <state>, when <act>, then <check>.
Where Annsa fits
Annsa keeps one spec per priority, written by you, your agent over MCP or Ask, from the customer evidence Annsa holds. Every agent reads the same spec, and each Done When line gets a receipt when it's checked. The spec · Writing a spec
See how it fits together in Direct your agents.