Spec-Driven Development: A Practical Guide (2026)

Spec-driven development is a methodology where a detailed specification is authored and agreed upon before development begins, and that spec serves as the single source of truth for what to build.¹ That definition predates AI by decades. What changed is who reads the spec: it used to be people, and now it's also the agent writing most of your code.

That shift is the whole reason the idea came back. A coding agent will happily produce something plausible from a one-line prompt. What it won't do is tell you which of your unstated assumptions it guessed wrong. The spec is where you stop guessing.

What spec-driven development actually is

The core move is boring and old: decide what you're building before you build it, write it down, and get agreement. The interesting part is what "written down" now buys you.

Microsoft's framing for the practice is that it's "version control for your thinking," and that it's explicitly not waterfall, because the decisions are meant to be reviewable and evolvable rather than frozen.² The failure it targets is stated well in the same write-up: if you don't decide what you're building and why ahead of time, the codebase becomes the de-facto specification.²

That last bit is worth sitting with, because it's true whether or not you adopt anything. Every project has a spec. The only question is whether it's a document you can read and argue with, or 40,000 lines of code you have to reverse-engineer to find out what the system is supposed to do.

Why it matters more with agents

You could ignore all of this in 2019 and mostly get away with it, because the person writing the code was also the person holding the context. They'd hit an ambiguity and ask. That feedback loop was slow but it was reliable.

Agents break it in three ways.

They don't ask. Given an underspecified request, an agent produces something rather than stopping. Ambiguity that a human would surface as a question comes back to you as a confidently wrong implementation.

They don't remember. Decisions made in turn 12 of a session are gone when the session ends. If the durable record of "we decided not to support nested albums" is a chat transcript, the next session doesn't have it, and the agent will cheerfully build nested albums.

They're fast enough to outrun review. An agent can produce a week of wrong direction in an afternoon. The cost of a bad premise scales with how quickly it gets built on.

A spec fixes all three at once, not because it's clever, but because it's a file. It sits in the repo, it gets read at the start of every session, and it can be reviewed before any code exists. This is the same principle behind lean instruction files and anti-drift workflows: the artifacts that survive the session are the ones that actually govern behavior.

Spec-driven development vs vibe coding

Vibe coding isn't the enemy here and this isn't a morality tale about discipline. Exploration genuinely benefits from not writing things down, because the cost of changing your mind is a sentence. The switch happens when the work stops being exploratory: the moment you'd be annoyed to lose it, the transcript is the wrong place for it to live.

The spectrum: three levels of commitment

The most useful thing in the literature is that this isn't one practice. A commonly used taxonomy splits it into three levels.¹

Spec-first. Write a thorough spec before generating code. Ship the feature. Don't necessarily maintain the spec afterward. Lowest commitment, and it still captures most of the rework reduction, because the value was in the thinking, not the upkeep.

Spec-anchored. The spec evolves alongside the code. When requirements change, the document changes, and review keeps them in sync. This is where most multi-person teams land.

Spec-as-source. The spec is the primary artifact humans edit; code is generated or regenerated from it. Highest commitment, and the version people mean when they say "specs as contracts."

Start at spec-first. Moving right should be something the cost of drift forces on you, not something you adopt because it sounds rigorous. Every step right adds maintenance that has to be paid on every change, forever, and the failure mode of an unmaintained spec-anchored process is worse than spec-first, because now the document lies and people still trust it.

The loop, using Spec Kit as the reference

GitHub's Spec Kit is the reference implementation, and it's the fastest way to see the shape of the practice. Its own one-liner is "Define what to build before building it," and it describes itself as an open source toolkit for building high-quality software with any AI coding agent, shipping a ready-to-use process you can also replace with your own.³

It's MIT licensed and free, sitting at roughly 130,000 stars as of August 2026, created in August 2025 and still actively developed.⁴ It works with 30+ AI coding agents.³

The core loop is spec, plan, tasks, implement, wrapped in a few commands:³

Three optional commands do the quality work, and they're the ones people skip: /speckit.clarify resolves underspecified areas before planning, /speckit.analyze checks consistency across artifacts after tasks and before implementation, and /speckit.checklist generates validation checklists that the docs describe as "unit tests for English."³

Getting going is two commands:

uv tool install specify-cli
specify init my-project --integration copilot

Swap the integration for whichever agent you use. Most agents expose the workflow as /speckit.* slash commands, though Codex CLI and Command Code in skills mode use $speckit-* instead.³ For a proper walkthrough of the tool itself, including where it's awkward, we have a full Spec Kit review.

The separation worth stealing even if you never install it: specify is about what and why, plan is about how. Keeping the stack out of the spec is what lets you review intent without arguing about Postgres versus SQLite, and it's the single most common thing people get wrong when rolling their own.

What a spec needs to contain

You don't need a toolkit to do this. A spec that actually steers an agent needs four things, and most homegrown ones are missing the last two.

1. What you're building and why. The user-facing outcome, in plain language.
2. Acceptance criteria. How anyone can tell it's done. This is the part that gives the agent a checkable definition of finished instead of a vibe.
3. Non-goals. What this explicitly does not do. Agents fill silence with invention, and an explicit "albums are never nested" prevents a whole category of confident wrong work.
4. Constraints and edge cases. The things that are obvious to you and invisible in the code.

Non-goals are the highest-leverage line per word in the entire document. Everything you don't rule out, something will eventually rule in.

Here's the whole thing at a size you'd actually write:

# Photo albums

## What and why
Users organize photos into albums so they can find a trip or an event
without scrolling a single undifferentiated timeline.

## Acceptance criteria
- An album can be created, renamed, and deleted
- Photos can be dragged between albums on the main page
- Albums display in date order by default, and that order can be changed
- Deleting an album asks for confirmation and does not delete its photos

## Non-goals
- Albums are never nested inside other albums
- No sharing, no permissions, no public links in this version
- No upload; we operate on photos already on disk

## Constraints and edge cases
- Metadata in local SQLite; photos are never uploaded anywhere
- An empty album is valid and must render
- A photo may belong to exactly one album
- Undo for drag-and-drop is out of scope, so the move must be confirmable

That's under 200 words and it forecloses a dozen wrong turns. Notice what isn't in it: no framework, no component names, no file layout. Those belong to the plan phase. If you find yourself writing "use React Query here" in the spec, you've merged two documents that are much more useful apart, because now nobody can review the intent without also reviewing the architecture.

Notice also that the acceptance criteria are checkable. "Albums should feel snappy" is not a criterion, it's a wish. "Deleting an album asks for confirmation and does not delete its photos" is something an agent can implement and you can verify in ten seconds.

Solo versus team

The mechanics are identical. What changes is where the value comes from, and teams that miss this adopt the ceremony without the benefit.

Solo, the spec is a message to your future self. You are the only reviewer, so there's no approval step and no negotiation. The value is almost entirely in the forcing function: writing acceptance criteria surfaces decisions you were postponing, and non-goals stop the agent inventing scope while you're not watching. Keep it short, skip anything resembling process, and don't maintain the document past the feature unless you want to.

On a team, the spec is where disagreement happens cheaply. The value shifts to the review step before implementation. Two engineers arguing about whether albums nest is a five-minute conversation on a paragraph, or a rewrite three days later. That argument is the product, not overhead.

The common failure is adopting spec-anchored, generating the documents dutifully, and having nobody read them before implementation starts. That's the worst of both: full maintenance cost, zero review benefit. If your team won't read a spec before the code exists, stay at spec-first and save yourself the bookkeeping.

What we found auditing our own specs

We run spec-driven development on this site, so rather than take the practice on trust, we traced one shipped feature end to end: spec, plan, task list, and the code that actually landed.

The headline is that it works. All twelve functional requirements were implemented, the unit tests pass, and the resolution logic matches the spec's edge cases line for line, including the awkward ones about dropping bad entries rather than failing the build. If you want evidence that a decent spec produces faithful implementation, that's it, and it held up better than we expected.

What we'd flag isn't a problem with the method. It's what happens once you run several agents, sessions, workflows and skills over the same repository: the spec is honoured by the workflow that read it, and invisible to every other one.

Our case was concrete. The spec established a rule about a shared file format. A different workflow broke it the next day, when a routine content refresh rewrote one article and dropped the block the spec had just added. Nothing was concurrent and nothing errored. The refresh simply had no idea the rule existed, because the rule lived in the spec that created it.

This part is well documented by other people, which was reassuring to find. Practitioners running parallel agents report the same shape: one agent's changes silently overwrite another's, each agent works in its own context with no visibility into what the others changed, and configuration files and registries behave as collision hotspots precisely because many features touch them. Skills and commands conflict the same quiet way, with nothing surfacing as an error.⁵ The usual mitigation offered is git worktrees, which is a good answer to simultaneous writes and no answer at all to ours, since our collision was a day apart. The prescribed fix that does apply is the boring one: every fact lives in exactly one place, and everything else points at it.⁵

The detector worked, for what it's worth. The feature shipped a report that names offending files, and the moment we ran it, it named them. It had been sitting there, correct and silent, for weeks, because the spec deliberately made it advisory so it could never fail a build. The safety decision and the silence were the same decision.

One smaller observation, offered without a diagnosis: the task list still reads as untouched, all 23 unchecked in every commit, while the feature is live. Nothing consumes that file after the work ships. We can't tell from the artifacts whether the marking step was skipped or never ran, so we won't pretend to know.

The part worth generalizing: a spec governs the workflow that reads it, and nothing else. If it sets a rule about shared artifacts, that rule needs enforcement where the other workflows run, or the next unrelated process to touch the file wins by default.

One feature, one repo, our own configuration. Treat the mechanism as the finding, not the frequency.

The honest case against it

Most guides on this topic read like they were written by the toolkit vendor. There's a real body of criticism and it deserves airtime, particularly since the whole premise of the practice is thinking before committing.

Specs go stale faster than code. This is the critique that's hardest to dismiss, and it doesn't need a citation to land. Code is forced to stay honest because it runs. A document has no such pressure, so it drifts silently, and a confidently wrong spec is worse than no spec because people trust it. Our own audit above is a small version of this: the code stayed correct, the task list didn't. If you want the argument made at length, it's the subject of Isoform's The Limits of Spec-Driven Development and Yuval Yeret's Is Spec-Driven Development a Step Forward or Back for Product Development?⁶

It's waterfall with better tooling, say some. Gojko Adzic framed the question directly as whether SDD is the revenge of waterfall or BDD taken to a new level.⁶ Proponents answer that specs are meant to be evolvable rather than frozen,² which is a real distinction, but it's a distinction that depends entirely on teams actually revising them. In practice plenty don't.

It degrades on exploratory work. When you don't yet know what you want, writing a spec is writing fiction. You'll produce a confident document about a design you haven't validated, then feel committed to it. Thoughtworks and others have gone further into where the practice fits and where it doesn't.⁶

None of this makes SDD wrong. It makes it a tool with a domain. Notice that the criticisms cluster on one side of the spectrum: spec-first survives all of them, because a document you never promised to maintain can't rot and can't lie to you. It's the levels to the right that carry the risk, and they're the ones marketed hardest.

Pitfalls that cause drift anyway

The tell that your spec isn't working is the agent producing something reasonable that you didn't ask for. That's almost always an unstated assumption rather than a model failure, and the fix is a sentence in the document, not a longer prompt.

To be clear about the ceiling: this reduces drift, it doesn't remove it. Agents misread clear specs. Specs contain contradictions nobody noticed. Anything you leave unsaid still gets invented. Anyone promising elimination is selling something.

Getting started

Don't adopt a methodology. Run one feature.

1. Pick a real feature, medium size, something you'd otherwise start by prompting.
2. Write the spec by hand first, even if you plan to use a toolkit. Four sections: what and why, acceptance criteria, non-goals, constraints. Half a page is fine.
3. Read it as if you were the agent. Every place you'd have to guess is a place it will guess.
4. Then generate. Point your agent at the spec and let it plan before it implements.
5. Count the rework. Compare against your last few features. That number is the only argument that matters.
6. Decide on the level afterward, not before. If the spec was useful once and never again, you're a spec-first shop and that's a legitimate destination.

If you want the tooling to enforce the sequence rather than relying on yourself, that's what Spec Kit is for, and the review covers whether it earns its place. The wider picture of how this fits with agent workflows lives in our AI developer workflows hub, and if the term itself is new to you, what agentic engineering means sets the context.

FAQ

What is spec-driven development? A methodology where a detailed specification is authored and agreed upon before development begins and serves as the single source of truth for what to build.¹ With agents, the practical difference is that the spec lives in the repo and the transcript doesn't.

How is it different from vibe coding? Vibe coding treats the conversation as the source of truth. SDD moves the decisions into a versioned document the next session can read.

What are the three levels? Spec-first, spec-anchored, and spec-as-source, in increasing order of maintenance commitment.¹ Start at spec-first.

Is GitHub Spec Kit free? Yes, MIT licensed, roughly 130,000 stars as of August 2026, and it supports 30+ agents.³⁴

Can I use it with Claude Code or Cursor? Yes. It's deliberately agent-agnostic, with an integration flag at init time and a generic fallback.³ Claude Code and Cursor are both covered.

What is a constitution? Project-wide principles that later phases get evaluated against, so rules you consider non-negotiable don't have to be restated in every spec.³

Does it eliminate drift? No. It reduces it. Agents still misread specs, and anything unstated still gets invented.

Do I have to maintain the spec forever? No, and pretending otherwise is why people bounce off this. Spec-first is a real level: write it, ship, move on.

When is it a bad fit? Exploratory work, throwaway prototypes, and changes small enough that the spec costs more than the rework it saves.

Where do the specs live? In the repository, next to the code. A spec in a wiki is a spec nobody reads at the moment it matters.

Where to land

The cheapest version of this practice is also most of the value: before your next agent session, write half a page covering what you want, how you'll know it's done, and what it must not do. You don't need a CLI for that.

If that half page saves you a round of rework, you've validated the idea on your own codebase rather than on a vendor's case study. Scale up from there only when the pain justifies it, and stay suspicious of anyone telling you the highest level of rigor is the destination.

Sources

Footnotes

1. What is Spec-Driven Development?, IBM, for the definition and the spec-first / spec-anchored / spec-as-source spectrum. ↩ ↩² ↩³ ↩⁴

2. Diving Into Spec-Driven Development With GitHub Spec Kit, Microsoft for Developers. ↩ ↩² ↩³

3. GitHub Spec Kit, including its README command reference and official documentation. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

4. Repository metadata for github/spec-kit, checked 2026-08-17: 129,664 stars, MIT license, created August 2025. ↩ ↩²

5. On multi-agent and multi-workflow collisions: How to Run a Multi-Agent Coding Workspace and Git Worktrees for Parallel AI Agent Execution (Augment Code), Parallel Agentic Development (MindStudio), Claude Skills Not Working? 5 Fixes That Actually Work on silent skill and command conflicts, and ATM: CID-Brokered Pre-Write Admission for Multi-Agent Code Co-Synthesis for the academic treatment. ↩ ↩²

6. Critical perspectives: The Limits of Spec-Driven Development (Isoform), Is Spec-Driven Development a Step Forward or Back? (Yuval Yeret), Spec Driven Development: revenge of Waterfall or BDD taken to new level? (Gojko Adzic), and Thoughtworks on unpacking the practice. ↩ ↩² ↩³