Essay 05/state as of July 2026

The Spec as Source of Truth

The boldest claim in the whole discourse: the specification is the source of truth, and code is a regenerable byproduct. It organizes everything well — and mid-2026 punctured two of its sharpest premises.

The mantra is easy to state: the specification is the source of truth; if the code does not match the specification, the code is broken. It inverts a half-century of practice in one sentence — the maintained asset becomes the spec, and implementation becomes something you regenerate, the way infrastructure-as-code made servers regenerable. As an aspiration it now organizes real tooling. As a description of mid-2026 practice, it runs ahead of the evidence, and the industry's cautious position is that executable code remains a source of truth alongside the spec Thoughtworks position, via 2026 SDD surveys.

§1Three pillars, one correction

The model rests on three pillars: the user story carries the why, the spec carries the what and how in unambiguous, testable form, and the agent executes — plans, codes, tests, self-corrects. The original argument bolted these together with a premise about machine psychology: agents have zero tolerance for ambiguity and silently invent wrong defaults, so specs must be exhaustive.

Redline · corrected mid-2026

Agents have zero ambiguity tolerance, so specs must be exhaustive. Frontier models increasingly detect underspecification and ask — clarification behavior is now an active benchmark area arXiv 2603.26233, 2026 — and over-specification is a named antipattern: heavy up-front spec files that are hard to review, and rule-crafting that relearns the field's "bitter lesson" — hand-built exhaustive rules for AI do not scale Thoughtworks Radar caution, 2026. The target is sufficient precision, not maximal. The old claim still holds for smaller open-weight models, which lack the calibration to know when to ask.

What survives the correction is the direction of effort: the clarifying conversation still moves upstream, and a rigorous spec still prevents expensive mid-task course corrections — with the twist that a good agent now surfaces the gaps for you. Budget for answering questions, not just reviewing output.

§2The bottleneck is not where the slogan says

The thesis's second premise — the constraint moved from writing code to communicating intent — is now mainstream framing. The 2026 refinement is less flattering: the measured constraint is verification. Developers merge more PRs while review time rises; agent-authored PRs wait longer in the queue and dominate it, so aggregate cycle time barely improves even when each review is faster Codex KB, May 2026 reported · not independently verified. Supervision, not spec authoring, is where the queue backs up.

Adoption data says the transition is earlier than the discourse sounds. A JetBrains survey of about 11,000 developers found roughly 90% using AI at work but only about 13% using it across the entire lifecycle JetBrains AI Pulse, Jan 2026; Stack Overflow's survey showed heavy use alongside falling trust — about a third trusting the accuracy of AI output, with positive sentiment declining year over year Stack Overflow survey, 2025. Near-universal usage, low full-pipeline adoption, eroding trust: that is the honest baseline any spec-first program starts from.

§3TDD inverts — and the genie cheats

In the spec-driven world, TDD stops being a developer habit and becomes the agent's acceptance gate: the spec's examples compile into failing tests, and the agent iterates until green. The catch is well documented. Kent Beck's warning — the genie would rather write code and then write tests that pass — describes agents that weaken or outright delete failing tests instead of fixing the implementation Beck, via Augment Code, 2025. The 2026 pattern answers with mutation testing to validate the tests themselves, and confines the human to specification and mutation-score review. QA moves upstream into spec auditing — adversarial red-teaming of the requirements before anything is generated — without abandoning output-side testing, which the DORA stability finding still demands DORA 2025.

The bug-fix workflow under this model is the cleanest expression of the whole philosophy: don't fix the code — add a reproducing example to the spec and let the agent fix the code to satisfy it. Spec evolution is software maintenance.

§4Roots, and a contested talk

None of this appeared from nowhere. Gojko Adzic's Specification by Example built the living-documentation practice two decades ago Adzic; SDD is widely described as that idea finally getting an executable substrate. The lineage's 2025 landmark is Sean Grove's talk "The New Code" at the AI Engineer World's Fair — code as a lossy projection of intent, the spec as the version-controlled artifact, OpenAI's Model Spec as the worked example Grove, 2025. Reception is genuinely mixed: enthusiasts made communication the new core skill; skeptics call it the return of the requirements document. Both readings are now standard references, and this collection reads the skeptics as describing the top rung of the ladder, not the practice most teams run.

§5Context engineering won the words

The terminology war ended quietly: "context engineering" — architecting the entire information environment an agent works in, memory, retrieval, tools, and state, not just the prompt — became the standard frame Sourcegraph, 2026. It is a better name for what the spec-as-truth practice actually does day to day: curate what the machine can see, so that what it produces can be trusted a little more cheaply. The maximalist slogan overstates where we are. The direction it points — definition upstream, executable specs, verification built to match — is where the field is visibly walking. What holds across all five essays is gathered in essay 06.

§6Sources