Skip to content

Spec-Driven Development

A guide for technical teams that already know how to drive AI coding agents (Claude Code, Codex, Cursor, Copilot…) and have hit the wall: results are inconsistent, agents drift mid-session, refactors break files the agent never saw, and "write a better prompt" stopped working a long time ago.

This is the second guide in a trilogy: it comes after the fundamentals guide (what an agent is, how to use one) and before the harness engineering guide (how to engineer the system around the agent). SDD is the discipline in between: how to structure work so the agent can execute it well.

Premises

  • You can already drive an agent and have seen its limits in real projects.
  • You're not looking for a magic product. You're looking for a discipline.
  • You're willing to pay the cost of writing specs if it avoids the larger cost of rework, drift and invisible debt.
  • You want judgment, not dogma: you care about when SDD helps and when it's bureaucracy.

Central thesis

The bottleneck is no longer writing code. It is specifying intent clearly enough for an agent to execute it — and keeping that specification alive as the code evolves.

How to read this guide

Chapters are ordered problem → foundations → cycle → practice → bridge, but each one stands on its own. If you already have the "why", jump to whichever chapter solves a concrete problem. If you're starting fresh, read in order.

Two chapters are not optional even though they look negative: chapter 9 (the honest critique) and chapter 10 (code-embedded context as complement). Without them, this course is marketing. With them, it gives judgment.

Index

Chapter 0 — Entry point

Part 1 — The problem

Part 2 — Foundations

Part 3 — Lifecycle

Part 4 — Putting it to work

Part 5 — What's next

What you won't find in this version

  • Exhaustive tool comparisons. The ecosystem turns over every quarter; chapter 7 is a map, not a buyer's guide.
  • Production-ready spec templates. There are skeletons in chapters 3 and 9, but useful specs are written against your domain, not against a generic template.
  • Productivity promises. If someone promises you 10×, they probably haven't read chapter 9.

Sources