When Agents Write the Code, the Spec Is the Source of Truth

Once a coding agent can regenerate an implementation on demand, the code is no longer the source of truth for AI-generated software. The durable artifact is the specification: the intent you wrote down, plus the verification that proves the current code still satisfies it. Code becomes closer to a build output, something you can throw away and rebuild, while the spec and its checks are what the team actually maintains.

That is a large claim, so let me be precise. A source of truth is the thing you go back to when two accounts disagree. For thirty years that was the code, because a human authored every line and the intent lived inside those decisions. When an agent writes the implementation from a prompt, the intent was never in the code to begin with. It was in the request. Keep treating the generated code as the record and you are treating the output as if it were the input, and you will lose the plot the first time the agent rewrites a module you thought you understood.

Why the code stopped being the record

The shift is not that code became worthless. It is that code became cheap to reproduce and expensive to trust. Sean Grove of OpenAI put a number on it in his talk "The New Code": the code you write is maybe 10 to 20 percent of the value you deliver, and the other 80 to 90 percent is the structured communication of intent, the part that says what to build and why. When that intent is captured well, the code is a rendering of it. When it is not, the code is a guess that happened to compile.

Researchers are formalizing the same idea. In "Bootstrapping Coding Agents: The Specification Is the Program," Martin Monperrus argues that "the specification, not the implementation, is the stable artifact of record," and that "improving an agent means improving its specification; the implementation is, in principle, regenerable at any time." GitHub's Spec Kit makes the same bet in tooling: it flips decades of practice where code was king so that specifications "become executable, directly generating working implementations rather than just guiding them."

I find this convincing, with one large caveat that most of the discourse skips.

A spec you cannot check is a wish

Here is where I part ways with the cleaner versions of this argument. A specification is intent, and intent alone does not tell you whether the code in front of you is correct today. It tells you what correct was supposed to mean. Those are different facts, and the gap between them is exactly where AI-generated code fails.

Agents drift. They hallucinate an API, satisfy the letter of a prompt while missing the point, regenerate a component and quietly change a behavior three screens away. A spec that lives only as prose in a markdown file has no way to notice any of that. You read it, you nod, and you still do not know if the running app matches it. Augment Code's team makes this concrete with what they call the rebuild test: delete your src/ directory, point a clean agent session at the spec, regenerate, and see if the result passes your existing tests and matches production. The interesting phrase there is "passes your existing tests." The spec proves nothing by itself. The tests are what turn it from a description into a claim you can defend.

So the real source of truth in the agent era is a pair, not a document. Intent tells you what should be true. Verification tells you whether it is true right now. Drop either half and you are back to guessing. The teams that will stay in control of AI-generated code are the ones that maintain both, together, in the same repo the agent works in.

What this looks like in practice

If the spec-plus-verification pair is the artifact, then verification cannot be a separate discipline that lives in a QA tool and a different vocabulary. It has to be written in the same language as the intent, sit next to the code, and survive the agent rewriting things underneath it. This is the whole reason we built Shiplight the way we did, and it is worth saying plainly because it is the part of my own view I am least neutral about.

Shiplight tests are authored from intent, not from selectors. A test says what a user is trying to do and what should be true at the end, in readable YAML, so it reads like a fragment of the spec rather than a brittle script. Those tests live in your git repo, get reviewed in pull requests, and run locally, so verification travels with the intent instead of sitting in someone's cloud. Because the agent that writes the code also verifies it in a real browser and maintains the tests, the checks self-heal when the UI moves for a good reason and surface as a reviewable diff, not a silent rewrite, when it moves for a bad one. The point is not the product. It is that the spec and the proof of the spec are one maintained thing, and the code between them is the disposable, regenerable layer.

I want to be honest about where this does not hold yet. Most teams do not have specs worth calling a source of truth. They have tickets, Slack threads, and a senior engineer's memory. Writing durable specs is real work, and outside of teams that have committed to spec-driven development it is rare and hard to sustain. Verification is the same story: coverage decays, tests rot, and the pair falls apart the moment either half is neglected. I am describing where the practice is heading and where it already works, not where most codebases are today. If your intent lives only in people's heads, the code really is still your source of truth, because it is the only written record you have. The move I am arguing for is to stop letting that be the case.

Where to start

The practical entry point is not a rewrite. It is picking your highest-value flows and making their intent explicit and checkable, then letting that pair be the thing you defend in review. We wrote about turning scattered team knowledge into checkable specs in tribal knowledge to executable specs, getting from written requirements to running coverage in requirements to E2E coverage, and the discipline of keeping intent executable in the executable intent playbook. The origin of why we think verification belongs inside the agent loop rather than after it is in why we built Shiplight.

The one-sentence version: when the agent can rewrite the code, stop maintaining the code as if it were the truth, and start maintaining the two things the code is only ever a rendering of.

Key Takeaways

• When an agent can regenerate an implementation on demand, the code is a build output, not the source of truth.
• The durable artifact is a pair: the spec (intent) and the verification that proves the code still satisfies it. Intent without checks is a wish; checks without intent are trivia.
• This holds cleanly for spec-driven teams and is aspirational for everyone else. Most codebases still keep intent only in people's heads.
• The starting move is to make your highest-value flows explicit and checkable, then defend that pair in review instead of the raw code.

Frequently Asked Questions

Are specs the source of truth for AI code?

For AI-generated code, the specification is the more durable source of truth than the implementation, because an agent can regenerate the code from the spec but cannot recover the intent from the code. The stronger version of this is that the real record is the spec paired with verification: the intent plus the tests that prove the current code satisfies it. A spec with no way to check it is not yet a source of truth, only a description.

If the code is regenerable, why keep it in version control at all?

Most teams still track the code because tooling, review, and deployment assume it is there, and regeneration is not free or fully deterministic. The shift is one of authority, not storage: when the spec and the code disagree, you fix the spec and regenerate rather than patching the code and hoping the intent follows.

What is the difference between a spec and executable tests?

A spec states what should be true and why. Executable tests state whether it is true right now. The spec is the intent; the tests are the proof. You need both, because intent alone cannot detect drift and tests alone cannot tell you what correct was supposed to mean. When tests are written from intent in readable form, they read like an executable slice of the spec.

Does this only work for teams already doing spec-driven development?

The pattern is cleanest for teams that have committed to spec-driven development, where intent is already written down and versioned. For everyone else it is aspirational, because intent still lives in tickets, chat, and memory. That does not make the code a good source of truth. It makes it the only written record you have, which is the situation worth changing.

How does Shiplight fit the spec-plus-verification model?

Shiplight tests are authored from intent in readable YAML, live in your git repo, and run locally, so verification sits next to the code the agent writes rather than in a separate tool. The coding agent verifies its own UI changes in a real browser and maintains the tests, which self-heal when the interface changes for a good reason and surface as reviewable diffs otherwise. Intent and its proof are maintained together, while the code between them stays disposable.