There is a kind of document every programmer has learned to ignore. It has a title like Functional Requirements v3. It was written before anyone touched a keyboard, signed off by people in a meeting, and by the time the feature shipped it described a product that no longer existed. We stopped trusting those documents for good reasons. So it is a little strange to watch them come back.
They are coming back through a side door, wearing a new name. If you have handed real work to a coding agent in the last year or two, you have probably felt it. You describe what you want. The agent writes something. And the thing it writes is often clean, plausible, well organized, and wrong. Not wrong in the way a junior programmer is wrong, with a bug you can point to. Wrong in the way a genie is wrong. It built exactly what you said, which turned out not to be what you meant.
So here is the claim, and a lot of good engineers will want to fight it: once an agent does the typing, the code stops being where the thinking lives. The durable statement of what you want, the spec, becomes the real product, and the code becomes something closer to output you regenerate when the spec changes. If that is true, the scarce skill is no longer writing code fast. It is writing intent precise enough to survive contact with a machine. I think it is true. I also think it hides a trap that can hollow it out, which is where most of the cheerleading goes wrong.
To see why it is more than a slogan, start with the failure itself. When GitHub shipped a toolkit called Spec Kit in September 2025 to push exactly this idea, they were blunt about the diagnosis: "The issue isn't the coding agent's coding ability, but our approach." Their example was the prompt "add photo sharing to my app," which forces the model to guess at potentially thousands of unstated requirements. Who can see the photos. How big they can be. What happens when the upload fails. You never said. So the machine decided, and it decided the way a stranger would.
Now the tempting first explanation: this is just waterfall coming back, and we know how that ends. Big up-front documents, frozen before anyone learned anything, obsolete on contact with reality. We killed that for a reason.
Except that story is mostly a legend. The 1970 paper everyone blames for waterfall actually called its staged approach risky and said it invited failure, because the hard facts about timing and storage only show up late, during testing. Its author still wanted, in his words, quite a lot of documentation. What engineers came to distrust was never writing things down. It was documents that claimed certainty before anyone had earned it, that froze decisions before the feedback arrived, that let a team mistake a finished binder for finished software. That is a much narrower complaint than "specs are bureaucracy," and the difference is the whole point here.
So rule out nostalgia. The second explanation is the one I started with: the agents are simply weak, and this is a passing embarrassment on the way to models that read your mind. But look at what actually breaks. Microsoft, making the same pitch, tells a small story about a feature called notification preferences. The product manager pictures per-channel toggles. The backend engineer builds one global switch. The frontend developer assumes it hooks into the operating system. The designer mocks up a flow that would require rebuilding much of the user service. Four competent people, four reasonable readings, all incompatible. No smarter model fixes that, because the ambiguity is not in the model. It is in the request. Somebody has to decide what the feature is, and deciding is not a thing intelligence can do for you when you have not said what you want.
That leaves the third explanation, the one I think is right, and it is more mechanical than either of the first two. An agent's output is a function of the tokens you put in front of it. That is not a metaphor. It is how the thing works. A specification, stripped of ceremony, is just a durable and reviewable way to control what goes into that window before the code comes out. Which cuts both ways, and this is the part the cheerleaders skip: the same window a sharp spec steers, a stale or bloated or self-contradicting spec clogs. A bad spec is not neutral. It is bad context poured straight into the machine, and it fails the same way a wall of irrelevant search results fails, by crowding out the thing that mattered.
You can watch the good half of this in isolation. No controlled study has yet pitted a full spec-first workflow against plain prompting on real production software; that evidence is still thin, and anyone who tells you the method is proven is selling something. But the narrower claim, that structure moves outcomes, has a clean result behind it. One Microsoft Research project took the same model and the same context and added only a planning step that broke a repository-wide change into an ordered graph of edits. Five of six codebases then passed the automated checks. Without the plan, none did. Same intelligence. The only thing added was structure, and structure moved the outcome from nothing to almost everything.
Put it together and the anomaly resolves into something plain. What changed with agents is not that documents got better. It is that ambiguity got cheap to produce and expensive to miss. A human who misreads you usually shows it. They slow down, they push back, they come back and ask. Not always, but often enough that the confusion is visible before it is expensive. The agent's confusion is invisible. It turns your unstated assumption straight into code, a branch, a diff, overnight. The cost of being vague used to be paid slowly, in hallway conversations and puzzled looks. Now it is paid instantly, in volume, and it arrives wearing the face of work getting done. Which is why the team that built Spec Kit now says, out loud, that it is "moving from 'code is the source of truth' to 'intent is the source of truth.'"
I find this half true. The other half is where it gets interesting.
Because there is an old argument against exactly this, and it is stronger than the people quoting slogans want it to be. A programmer wrote in 1992 that programming was never really construction; it was design, and the only document that meets the bar of an actual engineering design is the source code itself. Everything else is a sketch of the design. The code is the design. A spec can claim the login is secure. Only the running system gets to decide whether it is. A spec describes behavior; the compiler, the tests, and the user encounter the behavior. Code can be ugly and unreadable and still it cannot lie about what the software does, in the way a document lies simply by growing old. The same writer noted that traditional projects burned time producing documents that were out of date days after coding began. Tests at least rot loudly, because they fail. Prose rots in silence.
And here is the part that should worry anyone cheering for specs: an agent generates a convincing document as fast as it generates convincing code. So a generated spec can launder ambiguity into cleaner prose. It can read as clarity while deciding nothing. You review it and feel the exact same false comfort you once felt skimming a thousand lines of code you did not really check. Worse, that spec then becomes the context the agent builds from, so a document that only looks decided poisons everything downstream. There is a public demo where someone pointed one of these workflows at a NASA ground-support system and asked for a read-only telemetry dashboard. The dashboard came up. It showed no data. The author's own writeup admits the spec was too thin and a validation step got skipped, so a networking bug surfaced only at runtime. Inside a full spec-driven process, a thin spec had turned back into a vague prompt. The ritual was performed. The thinking was not.
So where does it land? Not where the slogans want it to. The spec is worth more than the code only as long as it stays cheap and keeps getting dragged back to meet running software, fast and often. The old objection was not wrong. It was aimed at specs that had stopped being tested against reality. The moment your spec becomes a gate you complete rather than a claim you check, you have rebuilt waterfall in Markdown, and the code goes back to being the only thing that tells you the truth.
You are judged by the spec. You are saved, or caught, by the code.
Maybe the question itself is wrong. "Which is the real product, the spec or the code" assumes they are rivals. They are not, but they are also not equal partners, and it matters which way the weight falls. The spec is the thing you now make: the durable statement of intent you hand a machine that will do the typing. The code is the verdict on it, the one witness in the building that cannot be talked into agreeing with you. You are judged by the spec. You are saved, or caught, by the code. The gap between what you decided and what turned out to be true was always the actual work. Agents did not remove that gap. They made it cheap to open and easy to ignore.
For thirty years, "good engineer" mostly meant someone who could make the machine do what they said. That skill is getting cheaper by the month. The scarce one underneath it was always harder, and always easier to fake: knowing what you meant, precisely enough that it could be checked, and being honest about how far the result has drifted from it. We used to call an early, clumsy version of that skill "writing the spec," and we mocked it. Maybe we mocked it because, back then, nobody could run it.
That is the one thing that actually changed. The spec used to be a promise about software that had not been written yet, and promises like that were cheap because nobody ever collected. Now the promise gets kept, or broken, in minutes. Which means the hard question is no longer whether you can build what you described. It is whether you can still tell the difference between what you described and what you actually wanted.