Leadership Garden
One of my principal engineers sent me a link to spec-kit with the message, “Should we standardize on this?” I said I’d read it properly and get back to him. A few weeks later, an article on Specification-Driven Development came through my feed, and I read the whole thing, waiting to disagree with something.
Mostly I didn’t. Write down what you want before you build it. Review it with product and engineering in the same room. Keep it in version control. Turn acceptance criteria into automated tests. All fine, and all roughly what a careful team already does on a good week.
Then I looked at the diagram again. Specification at the top, four arrows down from it: implementation, testing, validation, and maintenance. The spec governs all four.
That is where the word “driven” is doing work nobody has audited.
If you run an engineering org, someone is going to ask you this quarter whether you’re “doing SDD.” This is what I told my principal engineer, eventually. Part of it is a practice I use every week and would defend to anyone. The rest is a positioning claim in a methodology costume, and telling them apart is worth an afternoon of your attention.
The defenders describe something the diagrams do not show
Start with the strongest version, because the weak version is easy, and I don’t want to spend a post beating up a LinkedIn article.
Marc Brooker works on Kiro at AWS and has written the best defence of SDD I’ve read. His line is that specs aren’t about pulling designs up-front; they’re about “pulling designs up”. You raise the level of abstraction from code to words, keep the artifact versioned and alive, and iterate on the spec rather than on the implementation. He’s right, and the sentence I’d underline in his piece is that you shouldn’t develop the whole specification upfront. Hold onto that one. It’s a concession the tools he’s defending have not made.
Birgitta Böckeler at Thoughtworks did the most careful hands-on evaluation I know of, and the useful thing she produced is a ladder. Spec-first: write it, use it, throw it away. Spec-anchored: it survives the change and evolves with the feature. Spec-as-source: a human never touches the code at all. I’d take the first rung happily, the second with a named maintainer, and the third not at all, for reasons I’ll get to. Note that almost everything marketed as SDD is sitting on rung one while quoting the brochure for rung three.
Yuval Yeret adds the sharpest diagnosis. The spec is a target for an adaptive loop, and the failure mode isn’t sequencing; it’s batch size.
Every one of those defenses describes a loop.
Now go look at any SDD marketing diagram. Specify, plan, tasks, implement. One direction, and no arrow comes back.
The people who understand this best describe a cycle, and the thing being sold draws a pipeline. That gap is the subject of this post, and better diagrams would not close it, because the pipeline is not a bad drawing of the practice. It’s an accurate drawing of the claim.
Böckeler has the right word for what’s happening to the term: it is already semantically diffused, Fowler’s name for a phrase that spreads faster than its meaning. Thoughtworks’ own Technology Radar now cites spec-driven development as a live example and says the hard part is telling a real methodology apart from ordinary use of a coding assistant. When the people who coined the vocabulary can’t draw that line, you should be slow to reorganize around it.
What “driven” is smuggling
Every “X-driven development” name makes the same kind of assertion. When two artifacts disagree, X wins.
Test-driven development gets away with it because the test lives inside the loop. It’s written minutes before the code; it fails first, and when it turns out to be wrong, you delete it without ceremony. Nobody escalates a deleted test. It never accumulates enough authority to be worth defending.
A specification does. It has been reviewed by product and engineering; it sits in the repo, and somebody’s name is on it.
So here’s the question I’d put to any team proposing this before the tooling conversation starts. When the running system and the spec disagree, which one is wrong?
Answer “the code, we regenerate it” and you have a governing document, along with every failure mode of the last fifty years of upstream-artifact processes. Answer “usually the spec, we go update it” and the spec isn’t driving anything. It’s documentation. Useful documentation is a fine thing to want, and most orgs are bad at it. But then there’s no methodology here, just a practice with an overclaiming name.
The best-practice list in that article gives the game away, and I don’t think its author noticed. Write specifications before implementation, says one bullet. Update specifications whenever requirements change, says another, two lines later. Both are reasonable advice. Together they concede that requirements will change after the spec is written, which is the fact the opening paragraph treats as a pathology to be engineered away.
If the spec has to chase reality, reality is the source of truth.
The spec doesn’t govern the agent either
There’s a second problem with “source of truth,” and this one isn’t philosophical.
A compiler is bound by its input. An LLM is not.
Böckeler ran spec-kit on a feature that built on existing code, and the tool did a research step that documented the classes already in the codebase. The agent then read those descriptions as new requirements and generated all of it again as duplicates. She saw the opposite failure too, where the agent followed one article of the constitution so eagerly that it went well past what anyone wanted. Bigger context windows have not fixed this, because putting something in the context is not the same as the model acting on it.
So the spec’s authority over the implementation is a probability, not a guarantee, and it decays as the document grows.
Thoughtworks put spec-driven development in the Assess ring of the Technology Radar in November 2025, which is roughly “interesting, go look at it.” What they wrote in the same entry is the part worth your time. The workflows are elaborate, the tools behave very differently depending on the size of the task, some of them produce spec files that are challenging to review, and when they generate PRDs or user stories, it isn’t always clear who those are for. Then they land on the actual worry: we may be relearning the bitter lesson, that “handcrafting detailed rules for AI ultimately doesn’t scale.”
That’s the sentence I’d put in front of anyone proposing an org-wide rollout. Not because it settles the question, but because the pattern it names has beaten every previous attempt to hand-author enough structure to make a model behave.
That matters more than it sounds, because it removes the one thing that would justify the ceremony. If the spec really did compile into the system, reviewing markdown instead of code would be a straight trade. It doesn’t, so you review the spec and then review the code anyway to find out whether the spec was honored.
Böckeler reaches for the German word: Verschlimmbesserung. Making something worse in the attempt to make it better.
Verification is not validation, and only one of them has an owner
The strongest practical claim for SDD is that acceptance criteria hand you tests almost for free. True, and worth having.
It’s also verification. Does this software obey the rules we wrote down?
Validation is the other question. Were those the right rules? You can have complete automated coverage of a perfectly specified system that nobody wants, and every test in that suite will pass while the product fails.
The objection I get here is that the criteria came from a stakeholder, so checking them is validation by proxy. It isn’t. A stakeholder signing off on a rule in February tells you what they believed in February about a system they had not used.
That’s a hypothesis with a signature on it, and treating a signature as evidence is how a good process turns into a bad one.
Most of what’s written about SDD uses those two words interchangeably, including the article I started with, which puts “validation” in its lifecycle diagram and then describes nothing but verification for three thousand words. Call that pedantry if you like. It’s the difference between building the thing right and building the right thing, and we are blurring the one distinction the discipline most needs to keep sharp.
The reason it matters to you and not just to essayists is that only one of those questions has an owner.
Verification does. It has tests, a pipeline, a definition of done, a QA function or a testing guild, and someone whose approval blocks the merge. Validation usually has nobody. It’s spread across a PM’s judgment, a designer’s instinct, and whether anyone remembered to look at the funnel three weeks after launch.
The most expensive quarter I’ve been part of ended with a feature that passed everything. Every acceptance criterion met, every test green, a clean launch. Adoption in month two told us what nobody had asked in month zero, and we spent the following quarter unwinding it.
Adopt a vocabulary that calls verification “validation” and you get an organization that believes the second question is handled because the first one is green.
Take the example that article uses, chosen to demonstrate the method’s strength. “Users can upload files” becomes a specification: 20 MB limit, PDF and PNG and JPG, virus scan before storage, reject encrypted files, store metadata, return a document ID, 30-second processing timeout. The article says this version leaves very little room for interpretation.
It leaves enormous room. Why 20 MB? Does the customer with a 25 MB PDF get an error, or does a support engineer quietly raise their limit? When the virus scanner is unavailable, do we fail closed, fail open, or queue and retry? What happens at second 31? And what do we do in six weeks when sales finds out that half the pipeline wants to upload DOCX?
Someone defending the example will say a better analyst catches those with more effort. I don’t think so. They’re questions generated by contact with reality, and contemplation doesn’t produce them in advance at any level of diligence.
Precision about the wrong answers is not an improvement over vagueness about them. You don’t escape that by specifying harder. You escape it by making the discovery cheap.
The economics moved, and the methodology went the wrong way
Every development process is an answer to one question. What does it cost to be wrong?
Big Design Upfront™ made sense when it was invented, and it annoys me how often that gets treated as a joke. Compiler time was rationed. A change meant a rebuild, a test cycle, and a release train you caught or missed by weeks. Under those numbers, paying six people to argue in a room for a month was cheap insurance against paying two hundred to build the wrong thing. Correct arithmetic, wrong century.
AI broke that arithmetic, and not slightly.
An agent can produce a working version of a feature in an afternoon. So the cheapest way to find out whether a requirement is right is no longer to argue about it in a document with five reviewers. It’s to build it, put it in front of somebody, and watch what they do with it. Prototypes are disposable now. Being wrong is truly cheap now, as long as you find out quickly.
Look at what SDD does with that. It takes the first change in our field’s history that makes feedback loops dramatically cheaper and spends the windfall on making the phase before any feedback exists longer and more ceremonial.
The observation underneath it is correct. Agents produce far better code from precise context than from vague prompts, and I run my own side projects this way and wouldn’t go back. The right conclusion is that small specs are an excellent artifact inside a fast loop. Hypothesis, small spec, implementation, contact with reality, revised hypothesis. Not that the spec belongs upstream of the loop governing everything downstream, which is the one position fifty years of evidence warns against.
Brooker and Yeret would both broadly agree with that paragraph, which is exactly my point.
The defensible version of this is iterative development with good context hygiene, and that is not what the word “driven” is claiming.
What it will cost your org
Start with review capacity, which is already your constraint whether or not you’ve named it as one. Faros AI spent two years watching telemetry from 22,000 developers across more than 4,000 teams, and their 2026 report is the least comfortable thing I’ve read this year. Under heavy AI adoption, median review time rose fivefold. Bugs per developer went up 54%. The incidents-to-PR ratio more than tripled. And the number that should stop you: 31% more pull requests merged with no human review at all, because reviewers could not keep pace and something had to give.
Böckeler’s account of spec-kit is that it produced a lot of markdown, repetitive with each other and with code that already existed. She’d rather review code than review those files. When she pointed Kiro at one small bug, it generated four user stories and sixteen acceptance criteria.
If human attention on the way out is your bottleneck, adding a review stage on the way in doesn’t help. It piles more work in front of the constraint. I’ve watched a design-doc review stage do precisely this. Genuinely good documents, thoughtful comments, and a median time from ticket to first deploy that got worse every quarter for a year, because nobody asked what the new stage was supposed to be subtracting.
Brownfield makes it worse, and brownfield is where you live. Almost every SDD tutorial builds an application from scratch, because that makes a clean tutorial, and Böckeler found the tools considerably more work to introduce into a codebase and product ecosystem that already exists.
Then there’s the fact that spec review has no failing state. A code review can say, “This doesn’t work.” You run it, it breaks, the argument is over. A spec review has taste, judgment, and whether the reviewer has the standing to push back on a document a PM wrote and a director already praised. In my experience, people approve specs. There’s no principled ground to reject one; rejecting it means the feature slips, and everyone in the room can do that math.
The last cost is ownership. If PMs write the acceptance criteria that agents build against, you’ve relocated a lot of technical judgment to people who don’t carry the pager. Yeret thinks expecting product managers to write the specs makes very little sense, and I agree with him. That doesn’t mean PMs stay out of it.
It means the person accountable for the system being correct has to be the person whose judgment ends up in the artifact the agent obeys.
What I’d actually do
I’m not against writing things down. I write a spec before I let an agent touch anything nontrivial, and the output is better for it. The disagreement is about where the artifact sits, and that resolves into a handful of concrete choices.
- Cap the spec by the thing it describes: one change, not one feature. If the spec takes longer to write and review than the change takes to build and try, you’ve picked the wrong artifact for the work in front of you. That’s a rule you can apply on a Tuesday without running a workshop about it.
- Measure time to first contradiction. Not cycle time, not spec coverage. How long from starting a piece of work to learning something that changes what you thought you were building. If that number lands in weeks, your spec is governing, whatever the diagram says, and if it lands in hours, then the spec is inside the loop, and you’re fine. It’s the only metric in this post I’d put on a dashboard.
- Give validation a name. One person per initiative, accountable for the question “Was this worth building,” with the standing to answer no and kill it. A named individual, not a team or a pod or a triad, because shared accountability for that question has never once produced someone willing to say the word no in a room with a director in it. If you can’t name them for your biggest current project, that’s the finding, and you can stop reading here.
- Keep the spec after the change only if someone maintains it. Böckeler’s spec-anchored level is genuinely valuable, and it’s also a commitment. An abandoned spec is worse than no spec because it misleads the next engineer with confidence and a git history to back it up. If nobody owns it, delete it when the change ships and write a decision record instead.
- And stop saying “driven” internally. Say, “We write a spec first.” Four words longer, accurate, and it doesn’t quietly assert that a document outranks a production system.
The question nobody asked
That article never asks the only question that matters in three thousand words. How much should we specify before building, and when do we stop specifying and start learning?
There’s no general answer, which is the problem with selling this as a methodology. Payroll rules, tax logic, a protocol implementation: specify heavily, because the what is genuinely knowable in advance and feedback won’t catch the mistakes in time. A new onboarding flow: specify almost nothing, ship something ugly on Thursday, watch what people do. Most of your work sits between those, and judging where is the job. It isn’t delegable to a process, which is precisely why processes sell so well.
Royce drew the single-pass diagram in 1970 and warned in the same paper that it invites failure because design flaws only surface through implementation. We took the diagram and left the warning. He had a better platform than I do, and it didn’t stick for him either, so I’m not expecting much.
Write the spec. Then keep it small enough that reality can overrule it.