For eighteen months, “write the specification first” has been the sensible response to AI-generated code. Describe the API, define acceptance criteria, point the agent at the spec. Often it works. The code compiles, passes checks, satisfies every stated requirement.
Sometimes it builds something that meets the specification and still should not exist.
Spec-Driven Development Has Hit Its Ceiling
Specs gave agents boundaries. Without them you get enormous volumes of technically plausible slop. Guardrails are not judgement.
The argument now runs between people who think the spec is the product and people who think it is only an input. The second group is closer, but neither position explains what is actually missing.
Case Study from EveryCompany Ltd: Last quarter a team shipped an approvals workflow that matched its spec line for line. Every acceptance criterion passed. It also duplicated a capability another team had already built, on a different data model, with nobody owning the overlap. The existing capability had never been written down, so the conflict surfaced in production rather than in review. The spec was correct. The decision was not.
What a specification cannot hold
A spec defines inputs, outputs and failure modes. It says nothing about why anyone should trust the result.
Most of the context that matters never reaches the document. It stays in conversations, in assumptions nobody voiced, in decisions that moved after the spec froze. A technically correct implementation can still solve the wrong problem or quietly undermine an architectural direction nobody remembered to record.
The spec confirms compliance with stated expectations, not that those expectations were right or still relevant. It captures what you said, not what you meant. Anyone who has reviewed an agent’s output knows the feeling: exactly what you asked for, and wrong.
Spec-driven development automates syntax, not semantics. The agent grasps the structure of a request without grasping its significance. Software engineering already learned that Big Design Up Front fails in complex environments, because you cannot fully define a system before you learn from building and using it. An AI agent does not change that. It removes the implementation cost that used to force the conversation.
When implementation was expensive, weak intent was partially absorbed by the process. Engineers asked questions. PMs clarified. Architects challenged assumptions. That friction was frustrating, and it created room for judgement.
Now an agent can turn an incomplete idea into working software before the organisation has examined the idea. The weakness in the spec is the same. The fallout arrives sooner.
What sits above the spec
We still need specifications. We just cannot treat them as sufficient.
Above the spec we need something that says why a decision should be trusted: who owns it, and what would make them reverse it. Those two questions drag the rest along, the assumptions, the evidence, the open risks.
Unlike a spec, this layer keeps moving. It picks up what production teaches you: incidents, test history, how customers actually behave. A spec freezes at commit time, and trust cannot work that way. Confidence shifts as regulation and platform capability change. A design that looked sensible six months ago may look questionable today.
Teams should still be able to pivot without losing the reason they pivoted.
Where the ceiling actually is
Spec-driven development works at the layer it was designed for: interfaces, acceptance criteria, quality gates.
The ceiling appears because we automated those layers and left shared intent, ownership and runtime evidence as manual curation problems. Then we treated the rise in code production as progress. As AI-generated code proliferates faster than teams can understand or operate it, organisations fill their estates with technically compliant systems that nobody can explain.
The label for the missing layer is not settled. Trust infrastructure is the closest honest description: linked records of intent, ownership and production evidence that both humans and agents can query before code gets written.
So here is the question worth taking to your next architecture review: can we defend this decision six months from now, when nobody remembers why we made it? If the answer depends on someone’s memory, that is the gap.