Most teams already write something down before coding — a requirements doc, a design doc. The problem isn't that this doc doesn't exist. It's that once coding starts, the doc stops being maintained, the code quietly becomes the real source of truth, and nobody goes back to update the doc to match. Spec-driven design keeps the spec live: it stays the source of truth the whole way through, and code, tests, and docs get built and re-checked against it — not just once at the start.
Why this matters now
AI coding agents write code fast — sometimes too fast. Without a clear spec, an agent (or a developer) fills gaps with guesses. Spec-driven design closes those gaps before anyone starts typing code, so everyone — human or AI — is building the same thing.
The 4-step flow
- Spec — plain-language description of what you're building and why. No implementation detail yet.
- Plan — the technical blueprint: architecture, constraints, tech choices.
- Tasks — the plan broken into a concrete, ordered checklist.
- Code — the actual implementation, written against the tasks.
Then you validate: does the code actually satisfy the spec? If not, loop back — fix the spec or the code, not just the symptom.
Spec-driven vs. traditional documentation
Traditional approach: a requirements or design doc gets written up front, then filed away. Coding starts, reality diverges from the doc — an edge case here, a scope change there — and the doc doesn't get updated to match. Within a sprint or two, the doc and the system have quietly drifted apart. Anyone new has to read the code to find out what's actually true.
Spec-driven approach: the spec isn't a one-time artifact, it's the thing everything else is checked against, continuously. When the plan or code needs to diverge from the spec, the spec gets updated too — so it never stops being accurate.
Where this shows up
GitHub's Spec Kit is an open-source toolkit built around exactly this Spec → Plan → Tasks → Code flow, designed to work with AI coding agents like Copilot, Claude Code, and Gemini CLI. It's a good reference if you want to see the pattern in practice rather than just in theory.
At enterprise scale: BAs and architects don't disappear
In a big org, "just write a spec" isn't one person's job. A business analyst gathers requirements. An architect makes technical decisions. A developer builds. QA tests. Spec-driven design doesn't remove these roles — it changes how they hand work to each other.
How the roles change
| Role | Traditional flow | Spec-driven flow |
|---|---|---|
| Business analyst | Writes a requirements doc, hands it off, often not consulted again until UAT | Co-owns the spec; reviewable in plain language, kept live as the source of truth |
| Architect | Writes a design doc separately, sometimes after the BA's doc is already stale | Writes the "Plan" directly against the spec — one less translation step |
| Developer | Interprets two documents, fills gaps with assumptions | Works from tasks generated straight from the plan — fewer assumptions to make |
| QA | Tests against whatever the code turned out to be | Tests against the spec itself — validation checks code matches intent, not just "does it run" |
Pros and cons at enterprise scale
| Pros | Cons |
|---|---|
| Auditability — a clear trail of who decided what, useful for compliance and governance | Overhead — writing specs, plans, and tasks is real work; not worth it for a one-line fix |
| Reproducibility — same spec, same result, less "it depends who built it" | Specs can become decorative — if nobody reviews them, they're process without value |
| Less rework — gaps get caught in the spec, not three sprints later in QA | Most popular SDD tools (GitHub Spec Kit, Amazon Kiro) assume you're starting from scratch |
| Knowledge spreads — junior staff and AI agents work from the same context senior architects used to hold in their heads | Enterprise reality is brownfield — legacy systems, existing architecture, years of business rules the tools don't account for out of the box |
The catch: brownfield vs. greenfield
Most spec-driven tools were built for new projects. Enterprise teams rarely get that luxury — they're extending systems with existing schemas, established patterns, and stakeholders who need to sign off. Adopting SDD there means adapting the workflow: start at the feature level within your existing architecture, not a full rewrite of specs for a system that already works.
One takeaway
Before your next feature, write one paragraph: what you're building and why. That's the whole habit. In an enterprise, that paragraph is what BA, architect, developer, and QA all point to instead of four separate documents. Start there — one feature, one spec — before rolling it out wider.
