Spec-driven development is a way of building software where you write the acceptance criteria before the code, and you decide whether a task is done by executing the code against those criteria, not by a passing build.
The name points at the order of operations: the spec comes first, the code second, and verification by execution last. The build passing is not the finish line. The criteria executing as written is.
Why it exists
A passing build tells you the code agrees with itself. It says nothing about whether it does what you asked. Measured across 120 runs and four models, a raw one-line request shipped a genuine correctness bug in 40% of cases with the build green. Handing the agent the acceptance criteria up front dropped that to 0%.
The model wasn’t the variable. The spec was.
How it works
- Write the acceptance criteria for the task, in plain language, before any code. Each criterion is a checkable statement about behavior: what the code must do, on what input, with what result.
- Implement the change (you, or a coding agent).
- Gate on execution. Re-apply the change to a clean checkout, run the code, and assert every criterion. If one fails, the task isn’t done, no matter how green the build is.
The criteria travel with the change and outlive the session, which is what keeps a system coherent instead of locally correct but globally incoherent.
Spec-driven development vs. TDD
TDD also writes tests first, and the two are close cousins. The difference is emphasis: TDD is a developer rhythm (red, green, refactor) focused on unit-level design. Spec-driven development treats the acceptance criteria as the contract for “done” at the feature level, and makes execution against that contract the gate for merging, especially when an agent wrote the code and you didn’t watch every line.
Spec-driven development vs. vibe coding
Vibe coding is the opposite: prompt, eyeball the result, ship if it looks right. It works until it doesn’t, and on a non-deterministic system you can’t tell which run you got without executing. Spec-driven development replaces “looks right” with “ran and passed.”
Where it pays off
The harder and less trivial the task, the more it matters: even the strongest frontier model, run raw, ships a real bug on a complex feature one in three times, non-deterministically. Writing the criteria once and gating on execution is what makes the result trustworthy, and it lets a cheaper model match an expensive one.
Doing it by hand on every task is the tedious part, and it’s what PaellaDoc automates.
FAQ
Is spec-driven development the same as TDD? No, but they overlap. TDD is a unit-level coding rhythm; spec-driven development is about feature-level acceptance criteria and gating “done” on execution against them.
Does it slow you down? Writing criteria costs minutes. Shipping a green-but-wrong feature costs hours or days downstream. On the measured tasks it removed the genuine-bug rate entirely.
Do I need a tool? No. You can do it by hand. A tool helps when you want the criteria and the execution gate on every task without remembering to.