What is Spec-Driven Development

Day 1 — The spec is the source, the code is the output

The first time an agent silently erases a fix you made by hand, it feels like a glitch in reality. It isn't. Once an AI agent can regenerate your code from a written spec, the code stops being the thing you own — the spec is. Miss that one shift and you'll keep losing work in ways that look like magic tricks. Get it, and half the confusing things about working with agents suddenly click into place.

1. The vanishing fix

Here's the moment almost everyone hits. You ask an agent to build a feature. It spits out a file. There's a small bug — an off-by-one, a wrong default, a missing null check. You fix it by hand in two minutes. Tests pass. You merge. Done.

A week later someone tweaks the spec and re-runs the generator. Your fix is gone. Not reverted in a diff you can see — just quietly overwritten by fresh output. You open the file and your two-minute patch simply isn't there. Sit in that 'wait, what?' feeling for a second, because it's pointing at something real.

2. Why it vanished

You edited the output of a process, not the input. The generator has no idea what the file said before — it produces the file fresh from the spec every time it runs. Your hand-patch lived in the output, so the next run flattened it.

Old-school analogy: it's like opening a compiled binary in a hex editor, flipping a byte to fix a bug, and being surprised that recompiling from source erased your change. Of course it did. You patched the artifact, not the thing the artifact is built from. Regenerating code from a spec is the exact same shape — the spec is the source, the code is the compile.

3. The inversion

For about twenty years the deal was simple: code is real, docs rot. The spec lived on a Confluence page nobody opened after sprint two. It drifted, went stale, and everyone quietly agreed the code was the truth. 'Read the code' was the honest answer to 'how does this actually work?'

Spec-Driven Development (SDD) flips which artifact is real. The spec becomes the thing you author and maintain; everything downstream — code, tests, sometimes docs and config — is generated from it. The spec is no longer a description trailing behind the code. It's the input the code is produced from. That's the whole inversion, and everything else in this series falls out of it.

4. What 'source of truth' actually means

'Source of truth' sounds abstract, so let's make it mechanical. In practice it's whatever artifact answers these three questions:

• ▹What do you review in a PR? (Where a human actually decides 'yes, ship this.')
• ▹What do you version in git and git-blame when you ask 'why is this like this'?
• ▹What do you regenerate from when things break — the thing you fix, then rebuild everything else off of?

For 20 years the answer to all three was the code. In SDD the answer to all three becomes the spec. That's not a slogan — it's a concrete relocation of where your attention, your review, and your git history need to point. If you're still reviewing and blaming the generated code, you're guarding the output while the real decisions happen upstream in a file you're not even watching.

5. What this changes on an ordinary Tuesday

This isn't philosophy. It changes two everyday habits right away.

• ▹A hand-patch to generated code is now a bug, not a fix. It looks like it worked — tests pass, it merges — but it's living in the output, and the next regen wipes it. If the fix belongs, it belongs in the spec, or in code the generator is told not to touch. Editing generated code directly is the new 'editing the binary.'
• ▹PR review shifts from 'is this logic correct' toward 'is this intent correct.' You stop line-reading the generated implementation as if a human wrote it, and start asking: does the spec capture what we actually want? Reviewing generated code line-by-line is often as pointless as code-reviewing your compiler's assembly output — the leverage moved upstream.

That second one is a big deal for teams. A lot of review effort right now goes into auditing AI-written code token by token. Some of that is necessary today, because our specs and generators aren't trustworthy yet. But the direction of travel is clear: the valuable review is on intent, not on output.

6. Two naive reads to kill right now

Before this hardens into a wrong mental model, two corrections.

• ▹SDD is NOT 'the AI writes everything and you never look.' You look harder — just at a different layer. The spec is where your judgment lives now. Less typing, more deciding.
• ▹The spec is NOT a magic, 100%-complete blueprint that removes all ambiguity. Specs are partial, leaky, and full of things left implicit. Regenerating from an incomplete spec means real decisions get made by the generator, silently. That gap — how complete a spec has to be, and what happens in the gap — is exactly the tension the rest of this series unpacks. Anyone selling SDD as 'write the spec, get perfect code' is skipping the hard part.

7. Close + the arc

If the spec is the new source code, then writing a good spec is the new core engineering skill — the way writing good code was for the last two decades. Not writing prompts. Not writing implementation. Writing the artifact that everything else is generated from, reviewed as, and rebuilt from when it breaks.

Which raises the obvious next question: what does a spec actually have to contain to be good enough to generate from? That's Day 2.

Extend your knowledge

• ▹Find a repo where an agent (Cursor, Claude Code, Copilot Workspace, Aider) generated a file. Deliberately hand-patch it, then re-run the generation from the same prompt/spec and watch what happens to your patch. Feel the vanishing fix firsthand.
• ▹Read GitHub's 'spec-kit' project and its writeup on spec-driven development with AI agents — a concrete take on treating the spec as the primary artifact.
• ▹Compare with a mental model you already know: infrastructure-as-code (Terraform) or generated ORM/protobuf code. Ask which of your three source-of-truth tests point at the spec vs the generated output today.
• ▹Pick one file in your own project that's partly AI-generated. Write down: if you had to regenerate it from a spec, what would the spec need to say that isn't written anywhere yet? That list is your Day 2 preview.