The experiment
The spec that couldn't build itself
In March 2026, Gabriella Gonzalez ran the experiment the whole industry had been arguing about instead of running. She took SPEC.md from OpenAI's Symphony, a flagship spec-driven project written by people with every incentive to make it work, and tried to build an implementation from it. Field-by-field schemas. A literal backoff formula. A section labelled, without irony, “This section is intentionally redundant so a coding agent can implement the config layer quickly.”
She couldn't get a working implementation out of it. The failed attempt is public.
Her conclusion reads more like a proof than an opinion: “If you try to make a specification document precise enough to reliably generate a working implementation you must necessarily contort the document into code or something strongly resembling code (like highly structured and formal English).” The quieter detail is arithmetic. Symphony's spec is roughly a sixth the size of the Elixir implementation shipped alongside it. Everything in the other five sixths was decided by somebody, just not in the spec.
Hacker News gave it 652 points. r/programming gave it 538, and the top comment there, at 391 points, was a working engineer saying the quiet part.
Getting a detailed spec from the client is the hardest work I do. But somehow everybody thinks the hard part is writing bussines code.
Both audiences landed on the same point, and it kills the strong version of spec-driven development. The spec was never the easy half.
The split
Two bets, opposite directions
The industry is not converging on this. It is splitting.
In May 2026 Amazon stopped accepting new signups for Q Developer and put the product on a clock: paid subscriptions reach end of support on April 30, 2027. The replacement is Kiro, whose premise is spec-driven development. Amazon did not add a spec-driven mode to its existing assistant. It is retiring that assistant in favour of one built around specs.
Weeks earlier, spec-driven development dropped off the Thoughtworks Technology Radar. Not demoted. Dropped. It entered in November 2025 at Assess, and when Volume 34 landed in April 2026 it was gone, the blip page noting only that it is not on the current edition.
Blips drop off the radar for all sorts of reasons, and Thoughtworks published no verdict, so read it as a loss of interest rather than a ruling. Still, one of these organisations is betting a product line on the technique and the other stopped tracking it.
The measurements
More spec, worse output
“Constraint Decay,” published May 7, 2026, ran 80 greenfield and 20 feature-implementation tasks across eight web frameworks against a unified API contract, layering on the structural requirements a real spec pins down: architecture, database, object-relational mapping. Performance fell as the layers accumulated. “Capable configurations lose 30 points on average in assertion pass rates from baseline to fully specified tasks, while some weaker configurations approach zero.” Agents also did worse in convention-heavy frameworks like Django and FastAPI than in minimal ones like Flask.
Spec-driven development promises that pinning things down produces better output. Pinned down on the axis this paper measures, the output got worse.
- Fully specified vs baseline
- −30
- points of assertion pass rate, capable configurations, Constraint Decay, May 2026
- Repository context files
- +20%
- inference cost, with no general improvement in task success rate
- Requirements as checkpoints
- 17%
- best published pass rate on SlopCodeBench, Opus 4.6, July 2026
A February 2026 evaluation of AGENTS.md files by a team including ETH Zurich's Martin Vechev found the adjacent result: “providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average.” Explicit instructions do get followed. It is the descriptive repository overview, the part of a spec that explains what the system is, that buys nothing.
Requirements rarely arrive as one upfront document anyway. SlopCodeBench delivers them as sequential checkpoints, and its published numbers are grim: Opus 4.6 passed 17 percent, GPT-5.4 11 percent. Running three hand-picked problems through Opus 5, Dex Horthy got four of seventeen checkpoints. A spec works right up until it changes.
The best case
The steelman, and it is a good one
None of that has stopped serious people, and the strongest version of the case deserves better than the strawman.
In February 2026 StrongDM's co-founder and CTO described running a production security product under two rules: code must not be written by humans, and code must not be reviewed by humans. Specs and scenarios were the only input. The clever part is not the agents, it is the holdout: scenarios deliberately withheld from the coding agents, imitating an external QA team, plus digital twins of Okta, Jira, Slack and Google so agents can run thousands of scenarios an hour. Their stated economics: “If you haven't spent at least $1,000 on tokens today per human engineer, your software factory has room for improvement.”
A month later, Andrey Breslav, who created Kotlin and so does not need the attention, launched CodeSpeak on the premise the article you are reading attacks: the spec is the source of truth and code is disposable output. His answer to the objection above is the interesting one. He agrees English cannot carry a specification, so he built a structured language that stays mapped to the code as the system changes.
The best rebuttal came from his own thread, and it is the whole cycle in two lines: “We built LLMs so that you can express your ideas in English and no longer need to code. / Also, English is really too verbose and imprecise for coding, so we developed a programming language you can use instead.”
The most honest pro-spec argument belongs to Addy Osmani, writing in July 2026 about what he calls comprehension debt: “the widening gap between how much code exists and how much any human still understands.” He argues for specs on review grounds rather than generation grounds. “The fundamental constraint in a software factory isn't how much code we can churn out: it's how quickly we can verify it.” The payoff, in his words: a spec “turns a long, frustrating code review into a quick read of a two-hundred-line plan.”
It is a good argument. It depends entirely on somebody reading the 200 lines.
The reading problem
Nobody reads the 200 lines
In June 2026 a study used eye tracking to watch developers review code labelled as LLM-generated. The label changed how long they looked. It did not change how well they looked. Some reviewers, told a model wrote the code, used the prompt to steer the review instead of working from the code itself. It is a lab study, and a prompt is not a spec.
Even in a room built to measure attention, the written intent starts to stand in for the code it describes.
Faros AI ran the population-scale version, comparing low- and high-AI-adoption cohorts inside the same organisations across two years of telemetry from 22,000 developers and 4,000 teams. Under high adoption: “31% more PRs are merging without any review.” Five times the median review time. Three times the incidents per PR. Ten times the code churn. Handle this one carefully: it measures AI adoption broadly, not spec-driven workflows specifically, and Faros sells engineering analytics. It does not prove specs caused the review collapse. What it does show is that the review step this whole methodology rests on is failing at scale.
The community version is blunter. When r/cscareerquestions asked in April 2026 whether anyone was still reviewing their own code, the top reply ran to 221 points: “Just let it rip and let the next employees after you're laid off handle it. Cycle repeats until the company eventually goes belly up from AI slop.”
When r/ClaudeAI asked in June whether people read the long plans their agent writes, the thread drew 365 points and 127 comments. The top answer, at 167 points, was someone insisting they do: “I read it. That's why all my Claude AI projects work well. It involves effort and intense focus.”
Read that as the pro-spec position, because it is the honest one. Spec-driven development works exactly as far as a human actually reads the spec, and not one line further.
The missing evidence
Nobody has the receipt
In July 2026, Dex Horthy asked StrongDM on Hacker News for a retrospective at the five-to-six-month mark: what was right, what did they get wrong. The StrongDM AI Lab answered: “We are working on new articles to share our latest findings, so stay tuned! Overall our outlook continues to be bullish.”
An outlook is not a number.
This is the pattern across the field. The best measured case for specification discipline is a May 2026 paper reporting lead time down, hotfixes down, rollbacks down. The sample: 14 engineers, three projects, one organisation, studied retrospectively, no control group, over a period in which the underlying models also got better. The author says all of this himself. The paper calls itself an illustrative pilot study and states that precise effect sizes cannot be claimed. That is the strongest evidence I could find, which is the point.
METR, the group behind the widely-cited developer-slowdown result, published something braver in February 2026. Their late-2025 numbers put AI at −18% speedup for returning developers and −4% for new ones, both confidence intervals crossing zero. And developers self-select which tasks to hand over so heavily that METR is now redesigning the study around it. One participant: “I found I am actually heavily biased sampling the issues.”
DORA, surveying nearly 5,000 professionals, reports a J-curve with an early productivity dip, and cites Stanford research putting gains at 35–40% on simple tasks and 10% or less on complex legacy code. None of that is about specs. That is the honest backdrop: the ground everyone is arguing on has not been measured either.
The keepers
What survives
Strip out everything unsupported and a short, unglamorous list is left. None of it is a document.
Freeze a slice, not a spec. A 93-point r/ClaudeAI comment from June 2026: “Freeze the contract before code. Not the whole spec; just the acceptance slice for this pass: inputs, outputs, files allowed to change, tests that must pass, and behavior that must not change.” That is scope control rather than requirements capture, and it is the version that works.
Expect to deviate, and know that is the job. A game developer of twenty years shipped a production multiplayer game in thirty days from a hand-written PRD, in a 445-point writeup that was precise about the caveat. The documents were “locked”: “Heavy emphasis on the quotations. Many of the decisions in those docs actually shifted as the build surfaced assumptions I'd gotten wrong, and recognizing when to deviate was where my expertise mattered most.” The spec did not save him from a shipped bandwidth leak that no AI review flagged, either.
Treat the spec as a hypothesis. Unmesh Joshi, writing on martinfowler.com in July 2026, argues for structured specification, which makes the concession worth more: “A specification is at best a starting hypothesis: the real constraints, trade-offs, and edge cases are discovered iteratively, as we proceed with the implementation.”
Watch the clock, and the invoice. Dex Horthy ran a fully automated factory from July 2025 and gave up that November, after repeated incidents ended in a from-scratch rewrite: “an agent-built codebase starts to struggle after maybe three to six months.” And Simon Willison, on StrongDM's economics: “If these patterns really do add $20,000/month per engineer to your budget they're far less interesting to me.”
The spec was never going to be the source of truth, because the source of truth is whatever you can run. What a spec can be is the place you do your thinking before you spend an agent's afternoon and your own. Gonzalez's proof cuts both ways. If a spec precise enough to generate the system is code, then the useful spec is the imprecise one: the short document that captures intent, gets argued over by people, and is expected to be wrong somewhere.
Which puts the whole industry's bet on a single unfashionable variable. Not context windows, not harnesses, not how many phases your pipeline has. Whether anybody read it.
Full disclosure
We build one of these
Having spent seven sections arguing that specs rot, it would be dishonest not to mention that we ship a product for keeping them alive. It's called CrystalSpec, and it exists because of the failure mode above: a folder of Markdown is a second codebase with no tooling. So CrystalSpec doesn't store prose. It stores versioned structure: flows, data models, roles, and test cases, with the AI drafting and a human approving rather than the other way round.
That addresses the half of the problem that is addressable. Structure can be diffed. Versions can be compared. A spec that knows what a role or a test case is can tell you when the product moved and it didn't, which is more than a Markdown file will ever do.
It does not fix the other half, and after everything above we would be the last people to pretend otherwise. No tool makes anyone read. Whatever you use, ours included, the question in the title is still the one that decides whether any of it was worth writing.