Spec-driven development (SDD) is a way of working with AI coding agents in which structured, version-controlled specifications are the project's single source of truth, and code is a product generated from the spec rather than the other way around.
The slogan version: specifications no longer serve the code; the code serves the specifications. In a traditional flow, the requirements document is written, filed away, and drifts out of date as the code moves on. SDD inverts that — to change behavior, change the spec first, then have the agent regenerate the plan and the implementation.
Grab It in One Sentence First
SDD means writing down what to build and what "done" looks like before letting AI write the code, instead of steering conversationally as you go.
A renovation analogy. Vibe coding is standing in an unfinished room telling the contractor "that wall looks off, move it left" — fast for small changes, but by the twentieth adjustment nobody remembers why that opening was left in the first place. SDD is drawing plans first, with dimensions, materials, and acceptance criteria, then building to them and revising the plans when something changes. The first works for one room; the second is for a whole house.
The Three Problems It Targets
Proponents typically frame SDD as a response to three characteristic coding-agent failures.
Intent drift. Over many turns, the implementation gradually diverges from what was originally wanted, and nobody can point to where it went wrong — because there is no written baseline to compare against.
Context decay. Once a codebase outgrows the context window, the agent stops remembering earlier decisions and either reinvents things or violates established conventions. That's fundamentally a context engineering problem, and SDD's answer is to freeze key decisions into documents that can be reloaded every time.
Unjudgeable output. Without explicit acceptance criteria, "is it done?" can only be answered by a human reading everything. With criteria written down, the agent can assess itself against them and generate matching tests.
The Typical Flow
The constitution is a project-level document of durable rules: language and framework, testing requirements, accessibility and security floors, dependency policy. It usually sits at the repository root — the same family of artifact as AGENTS.md — under version control.
The spec answers only what, why, and what counts as done, deliberately omitting implementation detail. What matters here is that acceptance criteria are decidable. Teams commonly use sentence templates like EARS (Easy Approach to Requirements Syntax) — "when [trigger], the system shall [observable behavior]" — because that structure parses easily for both humans and models.
The plan is where technical choices enter, tasks break the plan into independently completable and verifiable steps, and only then comes implementation. GitHub's open-source Spec Kit is one concrete tooling of this flow, exposing each stage as a slash command.
Versus Neighboring Practices
Versus vibe coding. Vibe coding is driven by immediate conversational feedback and suits exploration, prototypes, and throwaway scripts. SDD is driven by written specification and suits multi-module, stateful systems that will be maintained. Neither is wrong; the dividing line is scale.
Versus a traditional requirements document. A traditional PRD is written for humans and decouples from the code the moment it's filed. An SDD spec is a living document used by humans and agents alike, and since changing requirements means changing it first, it doesn't go stale.
Versus harness engineering. Harness engineering is about building the whole operating environment for an agent — tools, feedback loops, verification. SDD is the part of that environment concerned with how intent is expressed and made durable.
Versus agent skills and AGENTS.md. AGENTS.md tells an agent what this project is; skills tell it how to perform a capability; the spec tells it what this particular piece of work should become. Three different granularities of context supply.
Where People Get It Wrong
"SDD is just writing longer prompts." The difference is persistence and versioning. A prompt is one-shot; a spec goes into the repository, through review, and evolves with the code as an asset you can trace and diff.
"More detailed specs are better." Push the spec down to implementation detail and you're writing code in prose — slow, and prone to conflicting with the actual implementation. A spec should stop at what and acceptance criteria, leaving how to the plan stage and the agent.
"With SDD you don't have to read the code." Generated code still needs review. A spec guarantees direction and the definition of done; it guarantees nothing about implementation quality, security, or performance.
"It suits every project." It doesn't. For a one-off script, a typo fix, or a weekend prototype, SDD's overhead plainly exceeds its benefit. Its zone is multi-module, stateful projects involving permissions and data models that will be maintained over time.
When It's Worth Using
A practical test: if handing this change to another person would require explaining it properly, it's worth a spec. If you can finish and verify it yourself in ten minutes, skip the ceremony.
The usual way to start is with the lightest layer — a project rules file at the repository root covering the stack, how to run tests, naming conventions, and off-limits areas. That costs almost nothing and pays immediately. Once the team is used to having the agent read the rules before acting, add "write a spec first" per feature. Rolling out the full process on day one is much harder to sustain.