2026-08-17

Spec-driven development: the spec is the source, not the chat log

“Vibe coding” gave a name to a problem anyone who has used an AI assistant for a larger change already knows: code that looks plausible and still drifts from the actual goal the longer a conversation runs. As a counter-movement, the industry has settled on the term spec-driven development — tools like GitHub’s Spec Kit or AWS Kiro turned it into a named pattern: the prompt history isn’t the source of truth, a versioned specification is, and plan and code are only derived from it.

The inversion that matters

The core difference is an ordering. In a classic chat history, the specification emerges after the fact — you can reconstruct it from the conversation, but it never stood fixed before the first line of code existed. Spec-driven development reverses that: first what should be built gets described, then that description gets checked, and only then — on the basis of the checked description — does an architecture emerge, and only after that, code. Every step rests on a fixed foundation the previous step laid, instead of a moving one that shifts with every new round of prompting.

Where that ordering already lives in Anvil Coder

Anvil Coder follows exactly this ordering, just under different names. In the REQUIREMENTS phase, the task description turns into a checked picture of requirements — open points aren’t quietly decided along the way, they get recorded as an assumption and stay visible for the rest of the run. That’s the specification, not a byproduct of the code that comes later.

Only after that comes ARCHITECTURE: structure, interfaces, and dependencies get fixed before a single line of code exists. That ordering isn’t a formality — it’s the precondition for breaking the actual implementation into small, independently checkable steps at all: a TaskSlice can only be built meaningfully against a fixed interface once that interface already exists.

The specification doesn’t stay without consequence

The difference from a specification that only exists as a document shows up at the end of the chain: every TaskSlice leaves its own commit, and a result arrives as a pull request draft — a human always merges it onto the main branch. Anyone who wants to check whether a step matched the specification doesn’t have to search a chat history for it; the trail is in the repository itself.

What a specification doesn’t replace

A checked specification prevents drift during implementation — it doesn’t prevent the specification itself from being wrong. Whether a requirement actually captures the real need stays a decision made before the first run, not during or after it. Spec-driven development doesn’t move that risk away from that point — it only makes visible exactly where a result deviates from its foundation, instead of hiding it inside a long conversation.