Todos los artículos

The Spec Is the Source of Truth Now (Mostly)

1 de julio de 2026

#AI#Software Engineering#Spec-Driven-Development#ai agents#engineering leadership
The Spec Is the Source of Truth Now (Mostly)

This month three of the bigger toolmakers landed on the same idea at roughly the same time. GitHub's Spec Kit, AWS's Kiro, and Claude Code all now support a workflow where you write a structured specification, an agent generates the code from it, and the spec — not the code — is the thing you maintain. The framing making the rounds is "spec-as-genotype": the spec is the DNA, the code is a phenotype expressed from it, and if a better model shows up you regenerate the phenotype instead of rewriting it by hand.

I think the core of this is right, and I also think it's about to get oversold. Both can be true. Let me separate the part I'd build a business on from the part I'd put an asterisk on.

The real part first. For most of the history of software, the code was the source of truth and the documentation drifted away from it until the two had nothing to do with each other. Spec-driven development flips that. The spec becomes the artifact you keep clean, and the code becomes downstream of it. That flip matters because of where the economics have gone — when a decent model can turn a clear contract into a working implementation in minutes, the implementation stops being the precious, expensive thing. The expensive thing is the part that actually says what the software is supposed to do, and that's the spec. So a sloppy spec stops being a documentation problem and becomes a defect that gets compiled straight into the product.

This is the part Heavy Chain plants its flag on, and I'll be upfront that I'm talking my own book here. The durable, defensible work is authoring and maintaining the specification, and building the harness that checks the generated code against it. The generation itself — turning a contract into code — is getting cheaper every month and is on its way to being a commodity. Microsoft's new MAI-Code-1-Flash is a good tell: a 5-billion-parameter coding model that reportedly beats Claude Haiku 4.5 on SWE-Bench Pro while burning 60% fewer tokens. When the thing that writes the code is small and cheap and getting better, you don't want your value tied to it. You want your value in the spec.

Now the asterisks, because the marketing around this is already running ahead of the reality.

There's a "three-tier maturity scale" going around — Spec-First, Spec-Anchored, Spec-as-Source — presented like it's an established industry standard. It isn't. It's a useful way to think about how tightly your spec and your code are coupled, and I'll use the vocabulary, but nobody should quote those tiers like they came down from a standards body. They're a coinage. Treat them as a mental model, not a certification.

The bigger asterisk is on the purest version of the pitch: humans only ever touch the spec, and the code is fully generated and never hand-edited. That's a real goal and it's mostly aspiration right now. The moment someone hand-patches the generated code to ship a fix on a Friday and doesn't fold it back into the spec, the spec is fiction again and you're back in the old world where the code is truth. Spec-as-source only holds if the discipline holds, and the discipline is the hard part, not the tooling.

And one that's easy to miss in the excitement: a spec is only a source of truth if it's precise enough to actually generate from. A paragraph of prose describing what you want isn't a contract — two people, or two runs of the same agent, will read it differently and build different things. If your "spec" is just vibes with section headers, spec-driven development doesn't remove the ambiguity. It just moves it one step upstream and lets the agent resolve it however it feels like that day.

So what do I actually take from the tooling going mainstream this month? Mostly that the good teams were already doing a hand-rolled version of this — writing tight requirements, keeping a real source of truth, validating against it — and the tools are now making that discipline the default path instead of the thing only the disciplined teams bothered with. That's genuinely useful. And the cheap small coding models make the headline promise real in at least one concrete way: when a better generator shows up, regenerating the system from the spec starts to look like a recompile instead of a migration project.

I sell this, so weight my enthusiasm accordingly. But I'd believe it even if I didn't, for the boring reason that it's just good engineering hygiene with better tools around it — write down what you mean, precisely, keep that as the source of truth, and check what gets built against it. That's not a new idea, and it'll outlast whatever we end up calling it this year.