SDD: The Trap the Gurus Are Selling You

Spec-Driven Development. Write an exhaustive specification, hand it to the agent, receive the system. They sell it as the method that professionalizes working with AI. What it professionalizes, in several cases I’ve seen, is the production of documents nobody reads.

Let me be clear before somebody quotes me out of context: specifying is part of the job and always was. My problem isn’t the specification. It’s the “driven”.

We’ve seen this movie

Waterfall, 1970. Write everything first, build afterwards. It failed for a reason that hasn’t changed: the complete specification of a system doesn’t exist before you build it, because building it is precisely what reveals the requirements nobody knew they had.

SDD is waterfall with markdown and an LLM at the end. The same assumption —that you can know it all up front— with better typography.

The three symptoms

The 40-page spec. Written for the agent, unreadable for the team. Nobody updates it after the third requirement change, so within a week the code and the spec disagree, and since the spec doesn’t compile, the one lying is the document.

Ceremony without verification. The spec gets approved in a meeting, the thing gets generated, and nobody defined how you check that what was generated matches what was specified. If your acceptance criteria aren’t executable, you wrote a wish with bullet points.

The template salesman. Five folders, twelve files and a naming convention, all before writing a single line. The process sells itself because it produces visible artifacts fast, and visible artifacts have been confused with progress since PowerPoint existed.

What does work, without a catchy name

Minimal, executable specification. Acceptance criteria as tests, not as prose. “Returns 429 after 100 requests per minute” is a test; “the system must be resilient” is a horoscope.

Contracts where there’s a coordination cost. The API schema, the event format, the migration contract. Specifying up front pays for itself there, because the error is caught between teams and not inside one.

Write the spec for the next piece, not for the whole system. A short cycle: I specify this, I build it, I learn something, I adjust the next one. Yes, it’s iterative. Yes, it’s what we’ve been saying for twenty years. No, it doesn’t need a new name.

Document decisions, not intentions. A three-paragraph ADR explaining why one thing was chosen is worth more than forty pages describing what’s going to be done. The code shows the what; only the document can keep the why.

How to spot the guru

Quick questions: how do you automatically verify that the implementation matches the spec? What happens when the requirement changes halfway through? Can I see this working in a repo with five years of history and real debt, not in a brand new project?

If all three answers include the word “discipline”, they’re selling you a process problem disguised as a methodology. Discipline is what gets invoked when the method can’t take reality.

The summary

Specify just enough, make it verifiable, iterate. That isn’t a methodology: it’s the job.

And if somebody sells you a five-letter framework that promises to turn requirements into software without the uncomfortable part of thinking in between, you already know which product category it belongs to. The bottles in the photo sold just as well.