TDD Solved Testing. Nobody Solved Speccing.
Test-Driven Development changed how a generation of engineers thought about code quality. Write the test first. Let it fail. Write the code. Watch it pass. Red, green, refactor. It was a methodology — not a tool, not a framework, but a way of thinking that improved outcomes across every team that practiced it.
We need the same thing for specifications.
Not a template. Not a "PRD best practices" blog post. A methodology — a coherent model for how specs get written, validated, connected to code, and maintained through the life of a feature. Because the tools changed, and the methodology didn't keep up.
AI coding tools made implementation 3-5x faster. The bottleneck moved upstream — from "how do we build this" to "what exactly should we build." And the answer to that question is still a Google Doc someone wrote on Monday morning, reviewed in a meeting nobody paid attention to, and forgotten by Wednesday.
Spec-Driven Development is the methodology that fills that gap.
What Spec-Driven Development Actually Is
Spec-Driven Development (SDD) is a practice where the specification is the source of truth throughout the entire development lifecycle — not just at the start. The spec isn't a kickoff artifact. It's infrastructure.
Three principles define SDD:
The spec comes first, and it's executable. Before any code gets written, the spec exists as a structured, machine-readable document. Not a wall of prose — a document with clear acceptance criteria, technical constraints, and scoping decisions that an AI coding agent can consume directly.
The spec stays connected. The spec links to the codebase it describes. It generates the board items that track its execution. It knows when tickets complete. It flags when pull requests diverge from its assertions. The spec is not an island — it's a node in a live graph.
The spec evolves with the code. When implementation decisions change the plan — and they always do — the spec absorbs those changes. Not by silent rewriting, but by surfacing the delta. The spec becomes a record of intent AND reality, tracking the decisions that shaped the shipped product.
The Convergence
This isn't a methodology someone invented in a vacuum. It's a pattern that emerged independently across dozens of teams, and the industry is now naming it.
GitHub's Spec Kit lets you define behavior specs that GitHub Actions validate against pull requests. Amazon's Kiro IDE built spec-driven workflows directly into the development environment. The OpenSpec initiative is pushing for standardized, machine-readable spec formats. Teams are committing PRD.md files directly into repositories and using tools like the Specify CLI to validate code against spec assertions.
The trigger is obvious: when AI agents write 41% of new code and PR volume doubles, you need something upstream that keeps the work coherent. The spec is that thing. But only if the spec is more than a document — only if it's connected to the code it describes.
SDD vs. What You're Doing Now
Most teams practice what we'd call Document-Then-Forget Development. The spec gets written, reviewed, and immediately begins decaying. By the time the feature ships, the spec is historical fiction.
| Practice | Traditional | Spec-Driven |
|---|---|---|
| Spec lifecycle | Written once, forgotten | Living, updated through implementation |
| Code awareness | None — spec doesn't know the codebase | Spec reads the repo before generating requirements |
| Board relationship | Manual copy-paste into tickets | Board auto-generates from spec sections |
| Drift detection | None — discovered weeks later | Flagged on every PR before merge |
| Agent compatibility | Agent reads spec once, works from memory | Agent queries spec via MCP, always current |
| Post-ship state | Spec is fiction | Spec reflects what actually shipped |
The difference isn't effort — it's tooling. Traditional workflows decay because the tools don't support connectivity. The spec lives in Notion, the board lives in Linear, the code lives in GitHub. Every boundary between tools is an information loss event.
SDD works when those boundaries don't exist. When the spec, the board, and the code are part of the same system.
How to Practice SDD Today
You don't need to wait for perfect tooling. Here's how teams are practicing Spec-Driven Development right now, with varying degrees of sophistication.
Level 1: Spec in the repo
Commit a spec.md file alongside the code it describes. Reference it in your PR template. When the PR changes behavior that contradicts the spec, update the spec in the same PR. This is the minimum viable version of SDD — the spec and the code travel together.
Level 2: Spec as agent context
Use MCP (Model Context Protocol) to expose your spec to AI coding agents. When Claude Code or Cursor starts a task, the agent reads the relevant spec sections, not just the code. This eliminates the "I read the spec once and now I'm working from memory" failure mode.
Level 3: Spec generates the board
Instead of writing tickets and rationalizing them into a spec, write the spec first and generate tickets from it. Each ticket traces back to a specific spec section. When the spec changes, the board reflects it.
Level 4: Spec detects drift
A GitHub App or CI check compares PRs against spec assertions. Different API shape than what was specced? Missing edge case? Architectural deviation? The drift surfaces before merge — not in a retrospective three sprints later.
Why This Matters More Than You Think
Andrew Ng reported teams considering 2 PMs per 1 engineer — a ratio inversion that would have been absurd two years ago. The PM role is splitting: Drew Breunig predicts a bisection into Application PMs (hybrid engineer-PMs building alongside customers) and Foundation PMs (platforms, compliance, QA).
Both halves need specs that actually work. The Application PM needs a spec that generates from customer signal and stays connected to the codebase. The Foundation PM needs a spec that enforces constraints across multiple teams and catches drift before it compounds.
SDD isn't a methodology for PMs or for engineers. It's a methodology for the system — the workflow that connects what you decided to build with what actually got built. The methodology that treats the spec as infrastructure, not a deliverable.
Ethan Mollick called the defining skill of the AI age "delegation documentation" — the ability to write clear specs that serve as effective AI prompts. Every spec, every shot list, every military Five Paragraph Order is really the same thing: attempts to get what's in one person's head into someone else's actions. SDD is the methodology that makes that work at scale, across humans and agents alike.
The Spec Is the Product
Here's the uncomfortable realization: in an AI-native workflow, the spec IS the product. The code is an artifact of the spec. The board is a view of the spec. The shipped feature is the spec, materialized.
If your spec is wrong, the code is wrong — faster than ever before. If your spec is disconnected, the code drifts — silently, until someone notices in production. If your spec is static, it becomes fiction — usually within 48 hours.
Spec-Driven Development isn't a new idea. It's the old idea — "know what you're building before you build it" — updated for a world where AI agents do the building. The methodology just needed tooling to catch up.
It's catching up now.