Spec-Driven Development: the spec is the source of truth
Most "AI-assisted" workflows treat the prompt as the artifact and the code as the truth. I flip that: the spec is the contract, and code is just its current implementation. That single inversion is what makes working with an LLM predictable instead of a slot machine.
The artifact flow
Every change — a feature, a fix, a refactor — walks through versioned artifacts before a line of code is written:
proposal → specs → design → tasks → apply → archive- proposal — why the change exists and what it touches.
- specs — what the system must do, as verifiable requirements/scenarios.
- design — how: decisions, alternatives, trade-offs.
- tasks — the ordered, ≤2h steps (with mandatory testing/verification).
- apply — implement against the spec; the spec is the acceptance test.
- archive — promote the deltas into the living specs.
Why it works
When the spec is explicit, the model isn't guessing intent — it's executing a contract. Reviews stop being "is this what we meant?" and become "does this satisfy the spec?". In practice that shortened my review cycles and let the N1 team resolve incidents autonomously, because the expected behavior is written down, not tribal.
If a change can't be expressed as a spec, it isn't understood well enough to build yet.
How I run it with Claude
I keep the specs in the repo (OpenSpec) and feed them as grounding. The model generates the proposal and spec deltas, I review the spec (not the diff), and only then we implement. Documentation is part of the same change — a change is incomplete if it leaves docs stale. Every project in my portfolio — platform-STALD, Fidello, VoltGrid, Trackion, Monitoreo-Cloud, dataMasterGK — is built this way, 100% SDD/OpenSpec.
Takeaway
Spec-Driven Development isn't ceremony; it's leverage. Write the contract first, let AI execute it, and verify against it. The spec is what survives — the code is replaceable.