Spec-Driven Development Is a Document Expansion Movement, Not a New Paradigm
Teams adopting AI coding agents are being sold SDD as the disciplined path forward, but the workflow introduces governance costs that most projects cannot sustain and a documentation layer whose errors are harder to detect than buggy code. The risk is not just wasted effort — it's institutionalizing context decay under the brand of a source of truth.
SDD packages a reasonable impulse — clarify what to build before an agent starts coding — into a workflow that demands long-term Spec maintenance as a single source of truth. Birgitta Böckeler's analysis splits the practice into three layers: Spec-first (a structured prompt, discardable after the task), Spec-anchored (a living document requiring continuous governance), and Spec-as-source (code becomes a generated artifact from Spec). Most SDD tooling blurs these together, selling the low barrier of Spec-first while promising the grand benefits of Spec-as-source.
The core failure is that natural-language Specs add another knowledge carrier to a codebase that already has PRDs, ADRs, tests, schemas, logs, and Git history. Rather than replacing any of them, a long-term Spec becomes a seventh source that must be kept in sync — and when an AI agent both writes the Spec and writes the code, errors self-reinforce rather than get caught. Legacy projects face the worst of this: reverse-generating a Spec from existing code launders historical accidents into formal requirements.
What actually works is splitting knowledge by lifecycle: short-term task context in planning-with-files, long-term decisions in ADRs, executable constraints in tests and schemas, and product intent in owned requirement systems. SDD's real danger isn't wasted documentation effort — it's the false sense of control that comes from a full directory of Markdown files whose truthfulness no one can verify.
The article's central framing — that SDD substitutes 'write clearly' with 'write completely' — identifies a category error that most SDD advocacy papers avoid: clarity and completeness are orthogonal properties, and AI tools reward the latter while governance requires the former.
Böckeler's three-layer taxonomy (Spec-first, Spec-anchored, Spec-as-source) exposes that SDD marketing performs a bait-and-switch: the low-friction entry point and the promised end state are fundamentally different engineering regimes with different cost profiles.
The observation that natural-language Specs are 're-interpretable specifications' rather than executable ones is a precise technical objection that cuts through the industry's loose use of 'executable' to describe any Markdown file an agent reads.
The warning about legacy projects — that reverse-generated Specs perform 'cognitive whitewashing' by renaming historical accidents as formal requirements — names a failure mode that is both common and almost invisible until a downstream system breaks.
The recommendation to split knowledge by lifecycle rather than centralize it in a unified Spec is not a compromise position; it's a direct rejection of the premise that a single artifact class can serve humans, models, and automated tooling simultaneously.