🌻 prg.sh

Spec-Driven Development

Dec 28, 20253 min read

Spec-Driven Development (SDD) inverts traditional software development: specifications drive code, not vice versa. The spec becomes the source of truth; code is its expression in a particular language and framework.

Core Concept

Instead of coding first and writing docs later, you start with a spec. This is a contract for how your code should behave and becomes the source of truth your tools and AI agents use to generate, test, and validate code. (GitHub Blog)

A spec is a structured, behavior-oriented artifact written in natural language that expresses software functionality and serves as guidance to AI coding agents. (Martin Fowler)

Three Implementation Levels

  1. Spec-first: Spec written upfront, used for the task at hand, then potentially discarded
  2. Spec-anchored: Spec maintained throughout the feature’s lifecycle; changes start with the spec, AI regenerates code accordingly
  3. Spec-as-source: Spec is the main source file; only the spec is edited by humans, never the code directly

Most tools target spec-anchored. Tessl is exploring spec-as-source. (Martin Fowler)

Historical Context

The roots stretch back to the 1950s. Daniel McCracken’s “Digital Computer Programming” encouraged tackling checkout problems before writing code. NASA engineers employed test-first techniques on the Mercury project in the 1960s. Modern formalization for AI-assisted development is attributed to John Lam and gained prominence in 2025 as an alternative to “vibe coding.” (Medium - Reza Azizi)

SDD Works Well For

  • Feature work in existing systems: Adding features to complex codebases. Forces clarity on system interactions. (Isoform)
  • Legacy modernization: Capture essential business logic in a modern spec, design fresh architecture, let AI rebuild without inherited debt
  • Stable contracts and well-understood domains: Production systems, enterprise applications, team collaboration, complex architectures
  • Compliance alignment: Specs map neatly into controls for ISO 42001, NIST RMF-AI, or SOC 2 evidence chains

SDD Might Not be for

  • Exploratory work: Research and prototyping work better with vibe coding (Thoughtworks)
  • Small fixes: “Using a sledgehammer to crack a nut” for bug fixes (Martin Fowler)
  • Evolving requirements: Context-driven approaches adapt better when requirements shift constantly
  • Maintenance tax: Keeping specs in sync with code creates burden that grows with system complexity (Isoform)

Key Limitations

  • Spec drift and hallucination: Inherently difficult to avoid
  • Non-deterministic regeneration: Each regeneration might produce slightly different implementations
  • Language/model dependence: Results vary dramatically depending on programming language and model training data
  • False confidence: Being too fixed to a static spec leads to less iteration and emergent solutions

(Isoform)

The Waterfall Critique

Gojko Adzic warns that SDD’s structure “could re-introduce some of the rigidity agile methods sought to escape” and cautions it might risk “bringing back the worst parts of Waterfall under a shinier name.” (Marmelab)

Tooling

  • GitHub Spec Kit: Most structured approach with constitutional framework and slash commands
  • Kiro (AWS): Simpler three-document structure, more IDE-integrated
  • Tessl: Spec-as-source approach, still in private beta
  • BMAD, OpenSpec, PromptX: Alternative frameworks

The Balanced Take

Most real-world projects need both: stable contracts at system boundaries, adaptive iteration within them. Vibe coding for exploration, spec-driven for production. It’s not binary. (Thoughtworks)

Graph View

Backlinks