Skip to content

Docs > Specs > Code ​

Delete the code. Keep the docs. Regenerate.

A vendor guide in June 2026 calls this the rebuild test: delete src/, point a fresh agent session at the specification files, regenerate, and see whether the test suite still passes. Treat it as a stress case, not a baseline. The check is safe only when the docs and tests are strong enough to catch regressions.

Now flip it. Delete the docs, keep the code, regenerate the docs.

The agent will infer: it can list routes, classes, and fields. What it cannot recover is why the retry count is three, why validation stayed in the controller, or which compromise should never have become the default. That is the difference between structure and intent.

Sources: Augment Code, "The Spec as Source of Truth: Why Codebases Should Be Rebuildable from Documentation" (April 9, 2026, updated June 18, 2026), vendor-authored rebuild-test framing; "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants" (arXiv preprint, January 30, 2026), spec-as-source as the strongest SDD form, and code as derivative.

The argument ​

In the 2025-2026 SDD material this chapter cites, code is increasingly treated as generated. Intent is authored.

Generated artifacts already have a familiar dependency rule. The compiled binary is downstream of the source code, the minified bundle is downstream of the modules, and the Docker image is downstream of the Dockerfile. Nobody treats the binary as the source of truth.

In agent-driven work, code starts to occupy the position the compiled binary used to. The authored intent above it lives in two places. The design, the decisions, and the reasons one option won over another live in docs. The testable behavior, the acceptance criteria, and the evidence belong to the spec.

This is why the chain runs in one direction. Docs shape the spec. The spec drives the code. Code is the artifact you are most willing to throw away.

This is the compiler move from the mindset chapter carried to its consequence: code becomes cheaper to regenerate, intent becomes more expensive to reconstruct, and the authored layer moves upward.

Sources: Fission AI, OpenSpec, change folders, delta specs, and archive into canonical specs; LeanSpec, spec files as intent, constraints, and success criteria for AI implementation; Rick Hightower, "Agentic Coding: GSD vs Spec Kit vs OpenSpec vs Taskmaster AI" (February 27, 2026), SDD tools treating specs as primary artifacts; "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants" (arXiv preprint, January 30, 2026), spec-first, spec-anchored, and spec-as-source spectrum; Dave Farley, "Modern Software Engineering" (Addison-Wesley, 2021), feedback loops and delivery of intent into production. The docs > specs > code ordering and compiler analogy are this book's synthesis.

Why this inverts the default ​

Before coding agents, modifying code was usually the expensive part. Writing the design down and then implementing from the design felt like duplicated effort. Code became the source of truth because code was the hard part.

The mantra is that code is self-documenting. It is not. Code tells you what it does, but not what was decided against, what assumptions it carries, or why the current structure won.

For bounded 2025-2026 agent-assisted changes, code modification is cheaper than it used to be. A small service, handler, or UI flow might fit in one agent session. Code that is inexpensive to replace should not outrank the documents that make replacement repeatable.

Farley's "Modern Software Engineering" argues for feedback loops and reliable delivery of intent into production. In this workflow, docs record the design decisions and the spec turns them into evidence obligations.

Sources: Dave Farley, "Modern Software Engineering" (Addison-Wesley, 2021), feedback loops and reliable delivery of intent into production; Augment Code, "The Spec as Source of Truth" (April 9, 2026, updated June 18, 2026), vendor-authored rebuild-test framing for bounded regeneration claims.

Who owns the ordering ​

The > is a rule the team writes down, not a property of the system. Whether an agent writes the code or drafts part of the spec, the agent does not decide which layer wins when they disagree.

The solid arrows run downward: docs shape the spec, and the spec drives the code. The dotted arrows point back up only when a developer acts on a mismatch the agent or the tests surfaced.

This rule has a direction. The machine moves down the layers, and only a person moves intent back up. If the docs are wrong, fix the docs. If the spec is wrong, fix the spec. If the code is wrong, regenerate or rewrite the code.

The rollback path ​

Generated code sometimes looks wrong in ways that compound. Reverting a bounded patch is often straightforward. Improving the spec takes another review, but it can prevent the same misunderstanding from appearing in the next proposal.

When the result is wrong, discard the code first. Improve what produced it, the spec when the behavior was underspecified, the docs when the design itself was wrong, and regenerate.

This is Brooks's plan-to-throw-one-away from the preface at a smaller scale. The cost of discarding an agent-generated patch depends on its integrations and the strength of the tests, not on generation speed alone.

Vibe coding is a special case: the specification is chat history, ephemeral and uncommitted, which suits exploration and mockups. The transition to production runs the sequence in reverse: write the decisions into docs and the behavior into a spec, discard the prototype code, and regenerate from them.

Sources: Frederick P. Brooks Jr., "The Mythical Man-Month" (Addison-Wesley, 1975; 20th anniversary ed. 1995), ch. 11 "Plan to Throw One Away", planned discard. Simon Willison, "Not all AI-assisted programming is vibe coding" (March 19, 2025), vibe coding as a distinct mode of AI-assisted work. The rollback and production-transition advice is this book's workflow guidance.

The bar a spec must clear ​

Not every document labeled "spec" earns this treatment. A spec trusted to drive code needs to be testable, traceable, small enough to read, and scoped to one change.

Testable: each acceptance criterion maps to an observable, verifiable outcome.

AC-tagged: each scenario has a stable identifier, such as [FEAT-001]. Tests reference the ID, not the prose.

Sized to be readable: the spec fits in a context window with room for the code.

Scoped to one change: one proposal with the delta specs its capabilities need. Not a quarter's worth of requirements.

Those bars are about behavior. The design behind the change, the why, and the alternatives weighed live in the ADRs and design docs under docs/.

Sources: "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants" (arXiv preprint, January 30, 2026), testable and verifiable specification qualities; LeanSpec, context economy, and spec files capturing intent, constraints, and success criteria; Cucumber, Gherkin tags, stable scenario tagging lineage; JUnit 5, test tagging as executable grouping. The AC ID format and minimum-bar checklist are this book's synthesis.

The hardest shift ​

Most developers reading this chapter are not convinced yet, and I sympathize. The intuition is that the code is what matters: the docs are overhead, the code runs in production, and the documents sit in a folder nobody opens.

The code runs. The docs do not. Both statements are true. The code shows what the agent implemented, while the docs and the spec show what the team asked for in the first place.

Stop treating code review as the only primary quality gate. In this workflow, spec review happens before or alongside code review. Read the spec for correctness before the diff for conformance.

This claim only holds if the spec is tied to something harder than intent: executable evidence that the implementation delivers it. Intent without evidence is still a document.

Sources: "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants" (arXiv preprint, January 30, 2026), SDD workflow checkpoints and spec-code alignment through tests; Dave Farley, "Modern Software Engineering" (Addison-Wesley, 2021), feedback loops and automated verification.