When Spec‑Driven Development Becomes a Detour to Writing Code

A sufficiently precise spec is essentially code

Gabriella Gonzalez dissects OpenAI Symphony's SPEC.md and shows that the so‑called specification is filled with pseudo‑code, structured algorithms, field definitions, and even code‑shaped text. The spec lists data‑structure fields, type constraints, concurrency controls, retry strategies with formulas and thresholds, and adds a "Cheat Sheet" for faster model implementation. To make an agent reliably generate runnable code, the spec must approach code‑level precision, turning the activity into a different kind of programming rather than a lightweight pre‑description.

This echoes Dijkstra’s early observation that complex system collaboration relies on narrow interfaces; informal, loose expressions do not reduce labor but shift it to more communication and ambiguity. You cannot lower expression precision while expecting higher reliability.

SDD often drags teams back to waterfall

STRRL notes that after prolonged use of SpecKit, development becomes "design up‑front + mental simulation + one‑shot large delivery," resulting in massive PRs that nobody dares to merge. Contrary to the iterative, evolving nature of software, SDD tends to freeze the exploratory work into a deterministic document before the code is written. This premature freezing hides uncertainty, leading to a rhythm where a lot of time is spent writing specs, generating a large code chunk, then encountering concentrated failures later—essentially a modern façade of waterfall.

The boundary of a spec is the system's blind spot

Proponents claim that a good spec enables agents to deliver stably. In practice, the hardest engineering problems are the unforeseen ones. STRRL bluntly says that where the spec covers, execution is acceptable; where it does not, the result is a "pile of waste." Gabriella’s experiment with Claude Code generating a Haskell version from Symphony’s spec produced unreliable code that required many correction rounds. Similar issues appear with highly detailed YAML specs that still fail to match implementations.

The real issue is not whether a spec exists, but whether you acknowledge that a spec can never be complete, reserve rapid feedback mechanisms for the out‑of‑spec area, and base engineering quality on verifiable loops rather than the illusion of document completeness. Specs define boundaries but also create blind spots beyond those boundaries.

When spec also chases speed, it degrades into a "document‑shaped slop"

Ideally, writing a spec should be slower, more careful, and more abstract than coding. Under pressure for rapid delivery, specs become pipeline products: verbose, terminology‑heavy, and professionally formatted, yet lacking genuine design judgment and consistency. Gabriella criticizes parts of Symphony as "specification‑shaped sentences"—text that looks like a spec but lacks the necessary depth of thought.

Generating an initial "decent" spec with AI and then using AI to produce code from that spec involves two rounds of information compression and semantic drift. Each layer appears to refine the input, but the total information may be lost, resulting in a workflow that is effectively prompt‑driven documentation feeding prompt‑driven code, with humans only catching the final errors.

Don’t treat spec as a holy grail; put it back in the toolbox

The author now adopts a more conservative, pragmatic approach: critical systems still receive design documents, but only key decisions and constraints are recorded. Instead of striving for upfront completeness, the focus is on small, verifiable steps. Agents can generate quickly, but quality rests on testing, regression, and review loops. Documentation serves communication and decision‑making, not the fantasy of getting everything right in one go.

The author does not oppose specs; the problem is treating them as a silver bullet that can replace engineering judgment, iterative feedback, and long‑term maintenance experience. The most expensive cost in software engineering is not writing code but understanding problems, making trade‑offs, and bearing consequences—issues that SDD does not resolve.

When writing specs, consider whether they help clarify thinking or merely pad the input; the difference is significant.