TL;DR: Spec-driven development means writing down exactly what to build - behavior, constraints, acceptance criteria - before an AI agent writes any code, then implementing and reviewing against that document. It trades a slower start for work you can actually verify, and it is how teams get agent speed without agent chaos.
How it works
The workflow has three artifacts. First a spec: a plain-language document stating what the feature does, what it must not do, and how you will know it works. Then a plan: the agent (or the developer) breaks the spec into ordered, checkable steps. Only then comes implementation, where an AI coding agent works through the plan, and every diff is judged against the spec rather than against the reviewer's memory of a hallway conversation.
A concrete example: "users can export their data" becomes a spec that names the formats (CSV and JSON), the scope (only the requesting user's records), the limits (exports over 10,000 rows run as background jobs), and the acceptance tests. An agent handed that spec produces something reviewable: either the export honors the row limit or it does not. An agent handed only the one-line request produces something plausible - and plausible is where AI-written bugs live.
The approach is a direct response to the failure mode of vibe coding at scale: agents are fast, so underspecified intent turns into large volumes of confident, wrong code faster than humans can catch it. Writing the spec front-loads the thinking a careful engineer was doing anyway. It also plays to what models are good at - agents follow a precise written contract far more reliably than they infer an unwritten one, which is the same reason instruction files like AGENTS.md work.
The cost is real: specs take time, and for a throwaway prototype that time is wasted - vibe coding wins there. Specs also drift if nobody updates them when reality changes. The teams that make this work keep specs short, keep them next to the code, and treat "update the spec" as part of the change, not paperwork after it.
Where it sits in the AI stack
Spec-driven development is a process layer above the agent - it shapes what the agent is asked to do and how the output is judged, much like any structured agentic workflow:
Key tools and implementations
-
GitHub Spec Kit
An open-source toolkit that structures agent work into spec, plan, and task phases across popular coding agents.
-
Kiro
An IDE built around spec-first workflows, generating requirements and design docs before implementation.
-
Agent planning modes
Plan-before-edit modes in tools like Claude Code and Cursor, which draft an approach for approval first.
-
Design docs + ADRs
The pre-AI ancestors of the practice - lightweight written contracts that agents now consume directly.
Related entries
- Vibe coding Building software by describing intent to an AI and accepting code you judge by behavior rather than by reading it line by line.
- AI code review Using AI to read a code change and flag bugs, security issues, and style problems before or alongside human review.
- AGENTS.md A Markdown file in a repository that gives AI coding agents project-specific instructions, conventions, and commands.
- Agentic workflow A multi-step process that chains, branches, or loops model calls so an AI system can complete tasks too big for one prompt.