Spec-Driven Development

A spec is not a PRD, a design doc, or a Jira ticket. Those describe intent. A spec describes behavior: the inputs, the outputs, and the invariants, the failure modes, and the tests that prove the system actually does what it claims. In a world where implementation is cheap and reversible, the constraint moves upstream. The spec is where you pay the intellectual price.

Why code stopped being the source of truth

Three shifts collapsed the old model. First, code generation crossed a quality threshold where a well-scoped module can be regenerated in seconds. Second, agents can now read specs, write code against them, and run the tests themselves. Third, the half-life of any specific implementation has shortened dramatically. Today's TypeScript service may be tomorrow's edge function may be next quarter's WASM module. What persists across all of it is the specification.

The five artifacts of a spec-first workflow

1. The behavior spec. A precise, human-readable description of what the system does. Written in plain English but structured enough that both engineers and models can reason about it. Includes edge cases, non-goals, and explicit invariants.
2. The interface contract. Types, schemas, and API shapes derived from the behavior spec. Machine-checkable. The single source that generates client SDKs, server stubs, and mocks.
3. The evaluation harness. A test suite that grades implementations, including AI-generated ones, against the spec. For traditional logic, this is unit and integration tests. For LLM behavior, it is a golden dataset with rubrics, regressions, and adversarial cases.
4. The implementation. The runtime code. It should be treated as disposable. If it drifts from the spec, the spec wins and the code is regenerated or refactored to match.
5. The runbook. How the system behaves in production: escalation, rollback, kill-switches, model swaps. Also spec-owned, not code-owned.

Spec-first for AI features specifically

Traditional software fails deterministically. AI features fail probabilistically. That single difference reshapes the whole workflow. A prompt is not a spec. It is one candidate implementation of a spec. Treating the prompt as the source of truth is how teams end up shipping features they cannot test, cannot compare, and cannot regress-test when they swap models. The spec-first fix is to write down what the feature must accomplish, encode that as evaluations first, and treat prompts, model choices, and tool wiring as tunable parameters below the spec.

Agent contracts

Autonomous agents make specs load-bearing in a new way. When an agent chooses which tool to call and in what order, the spec has to define not just outputs but permitted actions, budgets, escalation triggers, and what "done" looks like. This is the contract the agent operates under. A well-written agent contract answers: what can it touch, what must it never touch, what is the maximum blast radius of a single run, and how does it know to hand back to a human?

What a good behavior spec looks like

Concrete, complete, and short enough to be read in one sitting. It names the actor, the trigger, the observable outcome, and the conditions under which the outcome does not hold. It lists at least one worked example for the happy path and one for each failure mode. It says what is explicitly out of scope. And it commits to measurable acceptance criteria that a machine can grade, not "the summary should be good" but "the summary must preserve every named entity from the source and must not exceed 120 words."

Where teams get it wrong

• Writing the spec after the code. The spec is the design activity. Written last, it becomes a rationalization instead of a constraint.
• Confusing prose with rigor. A ten-page narrative without measurable criteria is a wish, not a spec.
• No evaluation harness. If the spec has no runnable tests, it will drift the moment the codebase moves.
• Overspecifying implementation. A spec should constrain behavior, not force a specific data structure. Leave the model, framework, and topology decisions to the layer below.
• Treating the spec as write-once. Specs are living documents. Every incident, every model swap, every scope change should update the spec before the code.

Why this matters for AI-native teams

The teams that will move fastest over the next few years are the ones that separate "what we want" from "how we build it" and let AI compress the second half. That only works if the first half is written down with enough precision that a model, a new engineer, or a future maintainer can act on it without ambiguity. Spec-driven development is the operating discipline that makes AI-native engineering sustainable instead of chaotic.

The bottom line

Ship the spec. Regenerate the code. Grade both against evaluations you wrote before you started. This is the workflow that will define serious engineering for the next decade, not because the tools demand it, but because the economics do.