Skip to content

engineer@aine:~/book/chapters$ cat 05_spec-driven-development.md

CHAPTER 05Spec-Driven Development

Agents do not ask for clarification. They resolve ambiguity from training data instead of from your system's constraints, and they do it fast enough that misalignment compounds. This chapter makes the case for writing intent down first, and shows the three levels of SDD maturity.

  • 24 sections
  • 9k words
  • ~43 min
  • 4 figures
key takeaways7 points
  • 01Agents don't ask for clarification. They resolve ambiguity using training data patterns.
  • 02You already write specs: PRDs, ADRs, RFCs, user stories.
  • 03Writing a spec is a discovery process, not a documentation exercise.
  • 04Specs are durable artifacts that survive tool changes.
  • 05SDD makes human oversight practical at scale.
  • 06Not every task needs a spec.
  • 07Plan Mode is the accessible first step toward SDD.

inside this chapter

  • The Root Problem: Why Do We Need SDD?
  • Garbage In, Garbage Out: At Scale
  • The Compounding Problem
  • The Human Parallel
  • You Already Write Specs
  • When These Documents Are Missing
  • The Case for Spec-Driven Development
  • The Power of Learning by Writing a Spec
  • Uncovering Unclear Requirements with a Spec
  • The Economics of Writing Specs
  • When SDD Is Not the Right Fit
  • Specs as Durable Artifacts That Survive Tool Changes
  • Specs and Organizational Knowledge
  • SDD and Human-in-the-Loop
  • Why Engineers Resist Writing Specs
  • Plan Mode: The Bridge Between Vibe Coding and SDD
  • Plan Mode in Practice
  • Plan Mode and Spec-Driven Development
  • Three Levels of SDD Maturity
  • 1. Spec-First: Writing Specs Before Implementation
  • 2. Spec-Anchored: Keeping Specs During Evolution
  • 3. Spec-as-Source: The Spec as Primary Artifact
  • What Good Specs Look Like
  • Summary

figures

fig 5-1
The contrast between vague prompts and spec-driven input to an AI coding agent.
The contrast between vague prompts and spec-driven input to an AI coding agent.
fig 5-2
The Spec-Driven Development loop with human checkpoints.
The Spec-Driven Development loop with human checkpoints.
fig 5-3
From vibe coding to full SDD: a spectrum of approaches ordered by structure and reliability.
From vibe coding to full SDD: a spectrum of approaches ordered by structure and reliability.
fig 5-4
The three maturity levels of Spec-Driven Development: Spec-First, Spec-Anchored, and Spec-as-Source.
The three maturity levels of Spec-Driven Development: Spec-First, Spec-Anchored, and Spec-as-Source.

vocabulary introduced here

man aine →

read this chapter

Chapter 5 is in the Early Release.

The code ANSE2026 gives you 30 days of free access to the O'Reilly platform, which covers this book and everything else on it.

Read it free ↗View on O'Reilly ↗