On one project, the agent satisfied every written spec and still produced a shape nobody expected. The reason was not in the model: the specs were incomplete, and in places they conflicted with each other. Two later phases of the work existed only in my head and had never been written down anywhere the agent could read. The specs were updated, the implementation was regenerated, and the output matched.

Nothing about the agent changed.

Specs Are the Source of Truth and Code Is a Build Artifact

Code as a build artifact means the spec is the thing you maintain: when the output is wrong, you change the spec and generate again instead of editing the code you have. Two things follow from that.

The first is a triage question. If the spec is the source of truth, then every bug is one of two things. Either the code does not conform to the spec, or the spec itself is wrong: missing, conflicting, or incorrect. That is a more useful question than whose fault it was, because fault points at a person or a model, and neither of those is something you can go read, while conformance points at two artifacts you can put side by side.

Reconciliation at Write Time

The second is the one I find most convincing, and it is the part most spec-driven pitches undersell. Adding a new spec forces explicit reconciliation with every prior spec. Writing down the new behavior means deciding what it means for the behavior already described, because the prior specs are sitting right there in the repo and the new one has to agree with them or override them on purpose. A contradiction that would otherwise surface at runtime, or much later when someone notices the system does something nobody intended, comes up at the moment you write the second document instead.

That is the conversion: a class of defect that used to surface when the code ran becomes something closer to a compile-time error. Not literally, and the limit matters. But the class of mistake moves earlier, and earlier is where you want it.

Implicit Requirements

Implicit requirements are where the intent gap actually lives. Anything you did not write down, the agent is free to decide.

Mobile layout behavior is the cleanest example. You never said what it should do on a narrow screen, so the agent chose, and it chose reasonably, and it was still wrong, because the requirement it needed was in your head and nowhere else.

Before agents, implicit requirements got quietly absorbed by a developer who shared your context. Now the same gap gets filled by something that does not have the context you never wrote down, and the output still satisfies every spec you did write.

Where I Am on the Fence

I am not settled on whether this is the right way to build software, and three things keep me there.

  • The spec format is verbose, and that verbosity is recurring work rather than a setup cost you pay once.
  • Spec to code is non-deterministic. The same spec regenerates differently, which undercuts “source of truth” in a way advocates tend to skip past.
  • It is not how development actually works for most teams, and pretending otherwise makes the argument weaker instead of stronger.

Two more, from an earlier note of mine on the same question. A living spec directory is a maintenance commitment, and stale specs are worse than no specs, because they mislead the agent reading them. And specs of this kind are advisory documents. A build does not enforce them, which is well short of what a deterministic gate would give you.

What I Want to Try

I want to find out where the implicit assumptions actually live, on something small enough to throw away: a personal CLI or a small web app, specs written first with the GitHub spec kit, then generated. The rule I want to test, while the stakes are low enough to hold it, is that when the output is wrong I update the spec and delete the implementation rather than patching the code.

The point is not to prove the method works. It is to find out how much of what I meant was never written down.