The spec as the shared reference
Spec-driven development (SDD) works from a specification written first, with implementation, testing, and documentation all proceeding against it.
Instead of having an AI write code from conversation alone, you record what to build, what not to do, and what finished looks like, and both the AI and the people refer to the same document. The spec is not a document that ends when implementation starts — it is the shared standard for judgment throughout.
How it runs
- Clarify the purpose and the problem being solved
- Write the required behavior, constraints, inputs and outputs, and completion criteria
- Have a person review the spec and resolve ambiguity
- Have the AI or a developer implement from it
- Check the implementation and test results, updating the spec where needed
A spec does not have to be long. For a small feature, a few Markdown lines covering purpose, scope of change, constraints, and definition of done are already useful.
How it differs from vibe coding
Vibe coding conveys the feel of what you want and moves fast by looking at something running. Spec-driven development puts the criteria into words before implementation and checks against them as you go.
- Vibe coding: prototypes, personal tools, testing an idea
- Spec-driven development: features you will maintain, multi-person work, jobs where failure is costly
You do not have to pick one. Explore the shape with vibe coding, then write the spec and move to SDD once the direction is settled.
Why it matters with AI
AI can turn a vague request into plausible working code quickly. When the conditions the requester had in mind differ from the ones the model filled in, you get something that runs but is not what you wanted.
With a spec, you can split the work — organize requirements and design in one assistant, implement in another, review in a third — and still share the criteria. The spec stays with the project even as conversations and models change.
Watch for drift
The main failure mode is a spec that no longer matches the code. Update the spec when the implementation changes, and use tests and review to confirm the two agree.
SDD is also not about writing a perfect spec up front. Write small, feed back what implementation teaches you, and grow the spec and the code together.