Spec-Driven Development

In one sentence

Spec-driven development is an approach where a written specification of intended behavior is the primary artifact that drives both code generation and verification, so the code becomes an output of the spec rather than the place where intent secretly lives.

Origin

The idea is not new. It echoes model-driven engineering, where diagrams and models generated implementation, and behavior-driven development, where plain-language scenarios (Given/When/Then) described what a feature should do before anyone wrote it. Both tried to lift the source of truth above the code. Both struggled because keeping a separate model in sync with hand-written code was expensive, and the model usually rotted.

AI coding agents changed the economics. When an agent can read a specification and produce the implementation directly, the spec stops being documentation you maintain on the side and becomes the input the agent actually consumes. GitHub's Spec Kit, open-sourced in 2025, formalized this into a four-step loop (Spec, then Plan, then Tasks, then Implement) where each phase produces a markdown artifact that feeds the next and works across 30-plus coding agents including Claude Code, Copilot, and Gemini CLI. The spec is treated as a living, executable artifact, not a static document.

Why it matters for AI-native teams

When a person writes code by hand, the code and the intent live in the same head at the same time. When an agent writes the code, that link breaks. The agent had intent (yours, expressed in a prompt), produced code, and moved on. If the only durable record is the code, the next reader has to reverse-engineer what the change was supposed to do.

A written spec restores the link. It gives the agent structured context instead of an ad-hoc prompt, which is why teams using Spec Kit report less guesswork and more reliable output: the agent knows exactly which part of the spec it is implementing, so it makes fewer tangential mistakes. Smaller, spec-scoped tasks produce higher-quality code than a vague one-shot request.

The verification half

Here is the part most spec-driven workflows underweight. A specification that generates code is only half of the loop. The other half is checking that the generated code actually matches the spec. Without that check, a spec is a hope, not a contract. You have moved the source of truth to a document, but nothing enforces that the code still obeys it.

This is why specification and verification increasingly travel together in AI-native engineering. Researchers describe a future development lifecycle where machine-checkable specifications and verification artifacts become the primary basis for trust, because AI-generated code fails differently from human code: it is often syntactically correct but semantically wrong, quietly diverging from the intent it was built to satisfy. Only a verification step that references the original intent catches that divergence.

Shiplight is the verification half in practice. It plugs into your coding agent and, after a change, has the agent verify the behavior in a real browser against what the change was supposed to do, then author E2E tests written from that same intent. The tests are readable YAML expressing what the feature should do, not brittle selector scripts, so the specification of behavior and the test that enforces it stay legible to the same reader. A spec becomes real when something checks against it on every change.

Where spec-driven development fits

Spec-driven development sits at the front of the pipeline, upstream of implementation. It pairs naturally with intent-based testing, where tests describe expected behavior rather than encoding a specific implementation, and with agent-native QA, where the coding agent itself runs verification through tools it can call. Closing the loop, PR-time verification confirms the spec still holds at the moment a change is proposed for review.

The through line is simple. Write down what the software should do. Let the agent build it. Then prove, continuously, that the build still matches the writing. Spec-driven development supplies the first and second steps; a verification layer supplies the third, and the third is what keeps the first from decaying into wishful documentation.