What Is Spec-Driven Development? A 2026 Guide

Spec-driven development is a way of building software where a written specification, not the code, is the primary artifact a team maintains, and an AI coding agent implements against that spec. Instead of describing intent in a chat prompt and hoping the generated code matches, you capture what the software should do in a structured, versioned document, then let the agent turn that document into a plan, tasks, and working code. The code becomes an output of the spec rather than the place where intent quietly lives.

The practice grew out of a specific failure. When developers prompt a coding agent conversationally, they often get code that looks right but does not quite work: compilation errors, half-finished features, architecture that drifts from what anyone actually asked for. GitHub's engineering team framed the shift plainly when it released its own toolkit: development is moving from "code is the source of truth" to "intent is the source of truth." Spec-driven development is the discipline of writing that intent down first, in a form both people and agents can read and act on.

This guide covers what it is, the loop it runs on, how it differs from writing code first, the tools that popularized it, its honest lineage, who it fits, and its trade-offs. One theme runs underneath all of it: a specification only earns its name when something can prove the built software matches it.

What spec-driven development actually is

At its core, spec-driven development treats the specification as a living artifact rather than a one-time document that goes stale the moment coding starts. In a traditional project, a requirements doc is written, half-read, and then abandoned as the code diverges from it. In spec-driven development, the spec stays authoritative: when behavior needs to change, you change the spec, and the implementation follows.

Three properties separate a spec-driven workflow from ordinary documentation:

• The spec is structured, not prose. It names user journeys, acceptance criteria, constraints, and success conditions in a form an agent can parse and act on, not a wall of paragraphs open to interpretation.
• The spec is versioned alongside the code. It lives in the repository, moves through pull requests, and carries the same review discipline as any other source file.
• The spec drives generation. The agent reads the spec to produce a plan and then code, so ambiguity in the spec shows up directly as defects in the output. Vague spec, wrong build.

When a literal-minded agent is the reader, the cost of a fuzzy requirement is no longer a hallway conversation. It is a rebuild, which is why teams treat spec quality as a first-class engineering concern.

The spec-driven development loop: specify, plan, implement, verify

Most spec-driven workflows run a repeatable loop. The first three stages, specify, plan, and implement, come straight from the toolkits that popularized the practice. The fourth, verify, is the one teams most often underinvest in, and it is where the method either holds up or quietly falls apart.

Specify

You describe what to build: the user journeys, the experiences, and the conditions that count as success. You deliberately avoid technical detail here. The output is a specification the whole team can read, including people who do not write code. This is the stage that turns a scattered set of intentions into a shared contract, the same move behind turning tribal knowledge into executable specs.

Plan

You add the technical context: the stack, the constraints, the architectural decisions, the non-negotiable principles. The agent reads the spec plus this context and produces an implementation plan. Some toolkits formalize the constraints into a separate governing document so the plan cannot wander outside agreed boundaries.

Implement

The plan is broken into small, reviewable tasks, and the agent executes them one at a time with focused, verifiable changes. Small tasks matter here: they keep each change readable in review and keep the agent from making sweeping edits nobody can audit.

Verify

Here is the stage that gets skipped. Specify, plan, and implement produce code that is supposed to match the spec. Verification is the step that actually checks it does. A spec is only real if something can test the built software against it. Without that loop, "spec-driven" describes how the work started, not what shipped, and the spec drifts back into being documentation.

This is the gap Shiplight is built to close. Shiplight is a verification layer that plugs into your coding agent and gives it eyes and hands in a real browser, so the agent can confirm a UI change actually looks and behaves the way the spec said it should, while the change is still being built. The same acceptance criteria then become maintained end-to-end tests: the agent walks the app, authors the tests, and keeps them working as the UI changes. The spec stops being a starting document and becomes an enforced contract, which is the point of turning requirements into living E2E coverage. The verify stage deserves its own name and discipline, which is why we describe it as verification-driven development.

How it differs from writing code first

The default way most software gets built, including most AI-assisted software, is code-first. A developer holds the intent in their head, or in a ticket, and writes code that encodes it. The code becomes the only precise, current statement of what the system does, and documentation trails behind. Spec-driven development inverts that order in three concrete ways.

Intent is explicit, not implicit. In code-first work, understanding what a feature is supposed to do means reading the implementation and reverse-engineering the intent. In spec-driven work, the intent is written down in a form you can review before a line of code exists, which is where expensive mistakes are cheapest to catch.

Review happens on the spec, not just the diff. Reviewing a large AI-generated pull request is slow, because you are inferring intent from the change itself. Reviewing a spec is faster and catches misalignment before the agent has built anything on top of it.

The agent gets a precise brief. Conversational prompting gives the agent a moving target; a structured spec gives it a fixed one. Output reliability tracks the precision of the brief, which is why spec-driven teams treat writing the spec as the real work rather than a formality.

None of this makes code-first wrong. For a throwaway prototype or a quick script, writing the spec first is overhead you will not recover. Spec-driven development earns its cost when the software has to keep working across many changes, many contributors, and an agent doing much of the typing.

The tools that popularized spec-driven development

The methodology moved from idea to practice in 2025 and 2026 on the back of a few concrete toolkits.

GitHub Spec Kit is an open-source toolkit that brings a structured spec-driven flow to existing coding agents. It ships a specify CLI that scaffolds a project, plus commands that walk through the loop: a constitution step to set governing principles, then specify, plan, tasks, and implement. It works with more than 30 coding agents, including GitHub Copilot, Claude Code, and Gemini CLI, so a team can adopt the workflow without changing the agent they already use.

Amazon Kiro takes the opposite architectural bet: rather than layering onto an existing agent, it is a standalone agentic IDE built around specs from the ground up. Kiro requires a structured specification before it generates code, running requirement unpacking, technical design, and task implementation as distinct phases while keeping traceability between a high-level requirement and the code that implements it. It also adds event-driven hooks that can update tests or docs when files change.

Both tools express the same claim: the specification is the source of truth, and the agent's job is to keep the implementation faithful to it. That claim is the reason intent-based approaches to testing, like natural language to release gates and YAML-based tests authored from intent, fit naturally on top of a spec-driven pipeline. For a closer look at one toolkit end to end, see our walkthrough of spec-driven development with Spec Kit.

An honest history: this is not a new idea

Spec-driven development is having its moment, but the core ideas are decades old, and it is worth being honest about the lineage instead of pretending the practice arrived fully formed.

The academic thread runs from formal specification and design-by-contract work in the 1970s and 1980s, which established that a contract and a test are both specifications and that a spec can be executable rather than decorative. The practitioner thread is more directly relevant. Test-driven development, popularized around 2000, was never really about testing: it was a design technique where you record intent as an executable expectation before writing the code, an ancestor worth reading about on its own terms in spec-driven development versus TDD. Behavior-driven development, which followed a few years later, introduced plain-language specifications that cross-functional teams could read, with Gherkin becoming a widely used format for exactly that.

There is also a cautionary relative. Model-driven development in the 2000s promised to generate code from high-level models and largely failed, because the models were harder to write than the code and the generators were rigid and brittle. Spec-driven development inherits that risk directly, and the honest answer to "why is this different now" is not that the idea is new but that three things changed: coding agents are flexible generators rather than brittle template engines, CI/CD maturity makes automated enforcement practical, and the AI consumer of the spec makes spec quality pay off immediately rather than in some distant maintenance cycle. The practice is old. The economics are new.

Who spec-driven development is for

Spec-driven development is not a universal upgrade. It fits some situations far better than others.

It fits teams building serious, long-lived software with AI coding agents in the loop. If an agent is generating a large share of your code, the spec is how you keep that generation aligned with what you meant, and how you review it without reading every line of every diff. This is the AI-native development model the tooling was designed for.

It fits cross-functional teams where product managers, designers, and engineers all need to agree on what "done" means. A readable spec is a shared contract those roles can each sign off on, which is much of why intent-based approaches have taken hold, as covered in our executable intent playbook.

It fits brownfield modernization as much as greenfield work: writing a spec for an existing feature forces the implicit behavior into the open, where it can be reviewed, tested, and safely changed.

It fits poorly for throwaway prototypes and exploratory spikes, where the goal is to learn fast and the spec would be obsolete before it was useful. For that work, conversational prompting is the right tool, and spec ceremony just slows the loop.

The trade-offs

Spec-driven development buys alignment and reviewability, and it charges for them. The honest costs are worth naming.

Writing good specs is hard, and the method exposes that. A vague spec produces a wrong build, faster and more confidently than before. Teams new to the practice underestimate how much skill goes into a precise, unambiguous specification, and the tooling does not supply that skill.

There is real process overhead. Specify, plan, and review add steps before code exists. On small changes that overhead can exceed the payoff, which is why mature teams apply the full loop selectively rather than to every one-line fix.

The spec can still drift from reality. This is the trap the model-driven era fell into. A spec that is written, approved, and then never checked against the running software becomes exactly the stale document the practice was supposed to replace. The defense is verification: closing the loop so the built software is continuously proven against the spec, rather than assumed to match it. A spec-driven process without a verification stage is a slower path to the same uncertainty.

Key Takeaways

• Spec-driven development makes a structured, versioned specification the source of truth, and an AI coding agent implements against it, so the code is an output of the spec rather than the only record of intent.
• The loop is specify, plan, implement, and verify. The first three come from toolkits like GitHub Spec Kit and Amazon Kiro; the fourth, verification, is the stage teams most often skip.
• It differs from code-first development by making intent explicit, moving review onto the spec, and giving the agent a precise brief instead of a moving target.
• The ideas are old (design by contract, TDD, BDD) but the economics are new: flexible agents, mature CI/CD, and a spec quality that pays off immediately.
• It fits AI-native, cross-functional, and brownfield-modernization teams, and fits poorly for throwaway prototypes. Its main risk is a spec that drifts from the running software when nothing verifies against it.

Frequently Asked Questions

What is spec-driven development?

Spec-driven development is a software practice where a structured, versioned specification is the primary artifact a team maintains, and an AI coding agent implements against that spec. The specification names user journeys, acceptance criteria, and constraints in a form both people and agents can read, so the code becomes an output of the spec rather than the only place intent lives. It emerged as a response to conversational "vibe coding," which tends to produce code that looks right but does not quite work.

What are the phases of the spec-driven development loop?

Most workflows run four stages: specify (describe what to build and what success looks like), plan (add the technical stack, constraints, and governing principles), implement (break the plan into small tasks the agent executes one at a time), and verify (prove the built software actually matches the spec). Toolkits like GitHub Spec Kit formalize the first three with commands; the verify stage is the one teams most often have to add themselves.

How is spec-driven development different from test-driven development?

Both make intent explicit before code exists, and TDD is a direct ancestor. The difference is scope and altitude. TDD records intent as low-level executable tests written by a developer, unit by unit. Spec-driven development captures intent as a higher-level, cross-functional specification that an AI agent reads to generate a plan and code, with tests as one form of verification against it rather than the specification itself.

Do I need a specific tool to do spec-driven development?

No. Spec-driven development is a methodology, not a product. You can practice it with a plain markdown spec in your repo and any capable coding agent. Toolkits like GitHub Spec Kit and Amazon Kiro add structure, commands, and scaffolding that make the loop easier to run consistently, but the essential move, writing intent down first and keeping it authoritative, does not require them.

How do you keep a spec from drifting away from the actual software?

By verifying against it continuously instead of treating the spec as a one-time document. A spec is only real if something can test the built software against it. This is where Shiplight fits: its agent verifies UI changes against the spec in a real browser while you build, then turns the spec's acceptance criteria into maintained end-to-end tests that live in your repository and keep working as the UI changes. That verification loop is what stops a spec from decaying into stale documentation.

Related Reading

• The executable intent playbook
• From tribal knowledge to executable specs
• Turn requirements into living E2E coverage
• Spec-driven development with Spec Kit
• Spec-driven development vs TDD
• Verification-driven development

If you want to see verification in your own coding agent, Shiplight installs as an MCP server plus Skills in one line.

References: GitHub Spec Kit repository, Spec-driven development with AI (The GitHub Blog), Amazon Kiro, AWS Launches Kiro, a Specification-Driven Agentic IDE (Forbes), Where "Spec-Driven Development" Came From (Spec-Driven).