AI can write you 38 pages of specification in 4 minutes. You won’t read them.
You’ll skim the headings. Maybe check one section. Then you’ll say “looks good” and let it build.
That’s not engineering. That’s theater.
This theater predates AI
Let’s be fair: this did not start with LLMs.
Developers have been asking for “more requirements” for years. More detail. More edge cases. More acceptance criteria. More certainty before work starts.
But software never worked like that.
The Agile Manifesto is old enough to drink and already made the tradeoff explicit: working software over comprehensive documentation and responding to change over following a plan.
Behavior-driven development was supposed to move us even closer to execution. Dan North’s original BDD write-up argued that requirements are behavior too and that acceptance criteria should be executable. Cucumber still describes the result as an unambiguous executable specification that also documents how the system actually behaves.
That was the good idea.
Somewhere along the way, many teams kept the headings and lost the execution.
The comfort of comprehensive documentation
Now AI arrives and makes the old ceremony almost free.
Before the AI writes code, it must write:
- a spec
- a design document
- an architecture overview
- acceptance criteria
- edge case analysis
The AI obliges. It produces beautiful, comprehensive documentation. 38 pages. Every edge case covered. Every decision justified.
Nobody reads it.
But everyone feels safer. The spec exists. The process was followed. If something goes wrong, there’s a document to point at.
Absicherungsmentalität—the German instinct to cover yourself with paperwork. We’ve been doing this in enterprises for decades. Now we’re teaching it to AI.
The Trust Paradox
Here’s the thing nobody wants to say out loud:
If you trust the AI enough to let it write your spec, why don’t you trust it enough to skip the spec?
Think about what you’re actually doing. The same model that you believe can correctly analyze requirements, identify edge cases, and document architectural decisions—that model, you say, needs to prove it understood the problem before you let it write code.
But you’re not checking the proof. You’re checking that proof exists.
That’s not verification. That’s a checkbox.
”I need all requirements” is the wrong reflex
This is the line that really makes me twitch:
“I can’t start until I have all requirements.”
No, you can’t.
You can have enough requirements to start. You can have enough constraints to avoid obvious damage. You can have enough examples to define success. But “all requirements” in complex software is fiction. A large part of the requirements only becomes visible when something real exists and people react to it.
That is exactly why short iterations exist.
And this is where AI is actually useful: it has an absurd willingness to try, propose, adapt, and keep moving. It will make assumptions, build a first version, and let you correct course. In other words: much closer to what agile software development was always supposed to be than to enterprise requirement theater.
What specs actually do
Specs have value. I’m not saying throw them away entirely. But let’s be honest about what they are and aren’t.
The useful part is not exhaustive narration. The useful part is setting anchors.
What actually needs to be written down?
- constraints that must hold
- decisions that should survive refactoring
- interfaces that matter
- non-negotiable behavior
- forbidden moves
That is a very different thing from trying to describe the whole terrain in prose.
For humans, documentation used to double as inventory. People needed help understanding what already exists. AI doesn’t. Give it a minute and it can sweep a large codebase, inspect the real state, and reconstruct what is going on far faster than any human reviewer.
That changes the bar completely.
Specs can be higher level now. Smaller. More durable. More like stakes in the ground than a narrated walkthrough of every branch and edge case.
And the smaller they are, the easier it is to keep them tied to the current state instead of letting them drift into fiction.
The Alternative Nobody Likes
Don’t try to pre-write the whole project.
Write a short plan. Make assumptions explicit. Set a few anchors. Let the AI build. Then verify the output.
And as the system changes, tighten the docs around the now-current state. Not as a giant retrospective spec refresh. As ongoing maintenance of a small, manageable set of truths.
Not with documentation. With execution.
Tests don’t lie. Tests don’t require you to carefully read 38 pages hoping to catch a subtle logical error in paragraph 17. Tests run. They pass or they fail.
I wrote about this with the Nagelprobe—automated verification at scale. The AI was perfect for 46 files, then drifted on file 47. Three localization keys missing. No spec would have caught that. A test caught it in milliseconds.
Code is executable truth. Tests are executable constraints. Everything else is Prosa—prose that makes you feel good but doesn’t protect you.
This is no longer just my personal preference, by the way. OpenAI’s current guidance for production systems explicitly recommends writing evals before prompts and iterating through an evaluation loop. That is much closer to executable specification than to “please generate a longer requirements document.”
The stale-spec problem
The longer these documents get, the faster they rot.
Martin Fowler recently put it bluntly in a piece about AI priming: a stale priming doc is worse than none. It teaches the AI outdated patterns.
That matches what I keep seeing in practice.
Once an AI sees:
- an old spec
- a newer behavior in code
- maybe a workaround added in between
it often tries to preserve all of them.
“Ah, legacy.”
So instead of cleaning the path, it builds:
- fallbacks
- compatibility branches
- dual solutions
- translation layers
All in the name of caution.
That is how regressions sneak in. Not because the AI is malicious. Because we trained it on the same instinct humans already have: nothing may break, so keep the old path alive just in case.
And once the spec and the system disagree, your “single source of truth” is gone.
When Specs Make Sense
I’m not a fundamentalist. Specs make sense when:
- You need to set anchors. Domain rules, architectural decisions, invariants, boundaries. Things that should still be true after the next 20 commits.
- You’re exploring, not building. Early-stage thinking where you need to see the shape before committing. Write a plan, not a screenplay.
- Regulatory requirements. Some industries need documentation. Fine. But don’t pretend that’s engineering rigor—it’s compliance.
For everything else, I want something much more boring:
- a short plan
- explicit assumptions
- a few anchored truths
- one current implementation path
- tests and evals around the behavior that matters
- fast iteration once reality teaches us something new
- docs small enough to stay maintainable and current
Plan + tests. Not spec + hope.
Vorschriftengläubigkeit—the belief that rules and documents create quality. They don’t. Execution creates quality. Documents create the illusion of control.
The Real Waste
The worst part isn’t the time AI spends writing specs. That’s 4 minutes. Whatever.
The worst part is the false confidence. Teams that spec-drive their AI work believe they’re being rigorous. They’re not. They’re being ceremonial.
Real rigor is: does the output meet the requirements? Not “did we document the requirements?”—did the output actually meet them?
That’s a test. Not a document.
This connects to The Knitting Machine Ate Your Job, the Kurskorrektur deep dive on validation, and the question behind Keeper Runtime: if giant specs are not the safety system, what is? My answer is boring on purpose: anchors, constraints, verification, and a runtime that keeps the AI on one current path instead of letting it preserve every ghost of the past.