Spec-Driven Development

Updated 2026-04-05: Added OpenSpec catalog cross-reference following dedicated review.

What It Does

Spec-Driven Development (SDD) is an emerging software development pattern where structured specification documents (PRDs, architecture specs, user stories, technical designs) are written before code and serve as the primary input and constraint for AI coding agents. Rather than prompting AI tools with ad-hoc natural language instructions (“vibe coding”), SDD practitioners create explicit, versioned documents that define what should be built, how it should be architected, and what constraints apply. AI agents then generate code that implements these specifications.

The pattern addresses a fundamental problem with unstructured AI-assisted development: without explicit requirements, LLMs fill ambiguity gaps with hallucinated assumptions, producing code that appears functional but may not meet actual business needs. SDD inverts the traditional “code is the source of truth” assumption, making documentation the authoritative source with code as a downstream derivative.

The pattern has two major variants: static-spec tools (BMAD Method, GitHub Spec Kit, OpenSpec) where specs are written upfront and maintained manually, and living-spec platforms (Intent, Kiro) where specs automatically synchronize with code as agents work.

Key Features

Documentation-first workflow: requirements, architecture, and design documents must be created and approved before implementation begins
Specification artifacts serve as persistent context for AI agents, reducing hallucination by constraining the solution space
Versioned specs enable traceability from business requirements through architecture to implementation
Agent instructions derived from spec documents rather than ad-hoc prompts, improving reproducibility
Separation of planning (human-driven) from implementation (AI-assisted), with specs as the handoff interface
Pattern is tool-agnostic: implementable with any AI coding assistant that accepts system prompts or context documents
Two variants: static-spec (manual maintenance) and living-spec (automatic synchronization)

Use Cases

Greenfield product development: Teams starting new products where upfront architecture prevents costly rework downstream. Specs force requirements clarity before AI-generated code proliferates.
Regulated industries: Organizations in healthcare, finance, or defense where audit trails and traceability from requirements to implementation are mandatory.
Distributed AI-assisted teams: Teams where multiple developers use AI tools independently and need shared specification documents to maintain alignment and prevent divergent implementations.
Non-technical stakeholder collaboration: Projects where product managers or founders define requirements in structured documents that AI agents then implement, creating a clear division between “what” and “how.”

Adoption Level Analysis

Small teams (<20 engineers): Lightweight implementations fit well. Simple Cursor rules files, GitHub Spec Kit templates, or minimal PRD documents provide meaningful structure without excessive overhead. Full-weight implementations like BMAD are overkill for small teams.

Medium orgs (20-200 engineers): Strong fit. The coordination benefits of shared specification documents increase with team size. Medium orgs have enough process maturity to maintain specs without them becoming stale, and enough complexity that unstructured AI coding creates alignment problems.

Enterprise (200+ engineers): Natural fit for organizations already practicing requirements engineering. Commercial tools like Intent and Kiro provide the governance, access control, and integration features that enterprise teams expect. The spec-driven pattern maps well onto existing enterprise SDLC processes.

Alternatives

Alternative	Key Difference	Prefer when…
Ad-hoc prompting (“vibe coding”)	No specifications; direct natural language instructions to AI	You are prototyping, exploring, or working on throwaway code
TDD-first AI development	Tests (not specs) serve as the primary constraint on AI output	You have well-defined interfaces and prefer executable specifications
Agent Harness Pattern	Focuses on runtime architecture (tools, sub-agents, memory) rather than input specification format	You need to solve orchestration problems, not requirements problems

Evidence & Sources

Notes & Caveats

Spec drift is the primary risk. Static specs diverge from implementation over time, creating false confidence. Living-spec tools (Intent, Kiro) address this but add vendor lock-in and cost. Manual spec maintenance requires discipline that many teams lack.
Not all work benefits from specs. Bug fixes, small features, and exploratory work often do not justify the overhead of specification documents. The pattern works best for greenfield development and complex features.
Waterfall risk. Critics accurately note that “specify everything before coding” can feel like waterfall development relabeled. Effective implementations use iterative specification refinement, not big-upfront-design.
Spec quality bottleneck. The output quality is bounded by spec quality. Poorly written or ambiguous specs produce poor code regardless of the AI model used. The pattern shifts the skill requirement from “writing good prompts” to “writing good specifications” — a related but different competency.
Token economics. Multi-document specifications (PRD + architecture + stories + tech spec) consume substantial context window space, requiring expensive large-context models for effective use.
Rapidly evolving landscape. As of April 2026, the tool landscape is fragmented across 30+ frameworks. Expect significant consolidation as AI IDEs build spec-driven features natively. Committing heavily to any single tool carries platform risk.