Spec-Driven Development with AI Coding Agents: The 2026 Playbook

What you need to know

• The 2026 problem is drift, not speed. Coding agents generate working-looking code in seconds. The failure mode that costs you a sprint is the agent confidently building the wrong thing, beautifully, because the intent was never written down.
• Spec-driven development makes the spec sovereign. SDD treats a structured specification as the primary artifact from which implementation is derived, verified and governed. The code becomes a derivative; the spec is the source of truth.
• A good spec defines six elements. Outcomes, scope boundaries, constraints, prior decisions, task breakdown and verification criteria. Leave any one out and the agent fills the gap with a plausible guess.
• You already do a version of this. A CLAUDE.md or AGENTS.md context file is the low-tech form of SDD — markdown the agent reads each session. SDD scales that idea from persistent context to per-feature specs.
• Use it where it pays. SDD for production code, multi-month projects and anything multiple people maintain. Skip it for throwaway scripts. The winning pattern is vibe-code a spike, distil a spec, then spec-drive the production build.

If you have shipped anything with a coding agent this year, you know the feeling. You describe a feature, the agent writes a few hundred lines in under a minute, the tests it wrote for itself pass, and the diff looks immaculate. Then you read it properly and realise it solved a subtly different problem from the one you had in mind — it handled the happy path you mentioned and invented its own interpretation of everything you did not. The code is not buggy. It is worse than buggy. It is confidently, plausibly wrong, and it sailed through review because it looked so finished.

This is drift, and it is the defining failure mode of agentic coding in 2026. The generation problem is solved. Models write fluent, idiomatic code in any language you ask for. What they cannot do is read your mind about the requirements you never stated. Spec-driven development — SDD — is the discipline that closes that gap, and it has gone from a niche idea to the way serious teams in Bengaluru and London now structure their agent work. This guide is the practical playbook: what a spec actually contains, when the discipline earns its keep, the tools shipping their own flavour of it, and templates you can paste into a repo today.

What spec-driven development actually is

Spec-driven development is an engineering discipline that treats a structured specification as the primary, sovereign artifact from which implementation is derived, verified and governed. Read that sentence twice, because the word that matters is sovereign. In ordinary agentic coding, the code is the thing that exists and the intent lives in your head, a Slack thread, a half-remembered conversation. In SDD, the spec is the thing that exists, version-controlled and reviewed, and the code is generated from it. When the two disagree, the spec wins and the code gets regenerated — not the other way round.

Martin Fowler and his colleagues have written about this as a shift in what we consider the source of truth, and the framing is worth borrowing. For seventy years the source code has been the canonical description of a system; everything else — diagrams, docs, requirements — has been a lossy, perpetually out-of-date shadow of it. SDD asks whether, in a world where a model can regenerate the code from a precise description in minutes, the precise description should be the canonical artifact and the code the disposable output. You do not have to fully accept that to benefit from the discipline. You only have to write the intent down before the agent runs.

The reason this works is mechanical. A coding agent is a function from context to code. If the context is thin — a one-line prompt — the agent has enormous latitude to interpolate, and interpolation is exactly where drift enters. If the context is a tight spec that pins down outcomes, boundaries and constraints, the latitude shrinks and the output converges on what you actually wanted. You are not making the agent smarter. You are removing the room it has to be wrong.

You are already doing the low-tech version

If the term SDD feels new but the idea feels familiar, that is because most developers already practise its entry-level form without naming it. Every CLAUDE.md or AGENTS.md file in a repository is a specification — a markdown document the agent reads at the start of each session that carries project context, conventions and constraints. "Use British spelling in user-facing copy." "All database access goes through the repository layer, never raw SQL in handlers." "We target the AWS London region for UK data and Mumbai for India data." That is a spec. It is persistent, project-level, and it constrains every piece of code the agent writes.

Structurally, a per-feature spec is the same artifact pointed at a smaller target. The context file says "here is how this codebase works in general"; the feature spec says "here is exactly what this one change must achieve and how I will know it did." Teams that adopt SDD deliberately are not learning an alien practice. They are taking the instinct that produced their context file and applying it with discipline to each unit of work. The AGENTS.md standard — now read by Cursor, and broadly compatible with the way Claude Code consumes CLAUDE.md — is the connective tissue that makes this portable across tools.

# AGENTS.md — project-level spec the agent reads every session

## Project
Payments service for a dual-market (IN + GB) marketplace.
Python 3.12, FastAPI, Postgres. Deployed to AWS (ap-south-1 Mumbai for
India data residency; eu-west-2 London for UK data residency).

## Conventions
- British English in all user-facing copy and docs. US English in code.
- All DB access via the repository layer in `app/repositories/`. Never
  write raw SQL in route handlers.
- Money is an integer count of the smallest currency unit (paise / pence),
  never a float. Currency is an explicit ISO-4217 enum (INR | GBP).
- Public functions get type hints and a one-line docstring.

## Constraints (do not relitigate)
- We use Stripe for GBP and Razorpay for INR. Do not propose alternatives.
- No PII leaves its region of origin. Cross-region calls are forbidden.

## Verification
- `make test` must pass. `make lint` (ruff) must be clean.
- New endpoints need a contract test under `tests/contract/`.

## Out of scope (ask, do not assume)
- Schema migrations — propose, never apply automatically.
- Anything touching the FCA-regulated lending flow.

Drop that file at the root of a repo and any compatible agent starts every task already knowing the rules it would otherwise have invented. That is SDD at the cheapest possible price of entry. Everything else in this guide is about scaling the same idea up to the size of a feature, an epic, or a multi-month build.

The six elements of a good spec

A spec is not a wall of prose and it is not a Jira ticket. A spec the agent can build from reliably defines six elements. Skip one and you have not saved time — you have handed the agent a blank it will fill with a confident guess, which is precisely the drift you were trying to avoid.

1. Outcomes

What does success look like, stated as observable results rather than implementation? "Users can reset their password via an emailed one-time link that expires in fifteen minutes" is an outcome. "Add a reset_token column" is not — that is a guess at the how, smuggled in before the what is agreed.

2. Scope boundaries

What is explicitly in, and just as importantly, what is explicitly out. The single highest-leverage line in most specs is the out-of-scope list, because it is the latitude you are deliberately removing. "This change does not touch the existing OAuth flow, does not add rate limiting (separate ticket), and does not change the email template system" stops three plausible tangents before they start.

3. Constraints

The rules the solution must respect — technical, regulatory, performance, security. Data residency in AWS Mumbai or London. A p95 latency budget. A library the team has standardised on. A compliance boundary like the UK's FCA-regulated flows or India's DPDP obligations. Constraints are where domain knowledge that the model does not have gets injected.

4. Prior decisions

Choices already made that the agent must not reopen. Without this section the agent will, in good faith, propose switching your ORM, your queue, or your auth provider every time it sees an opportunity, because it has no memory that the question was already settled. Writing "we use Razorpay for INR and Stripe for GBP; this is decided" saves you from relitigating architecture in a code review.

5. Task breakdown

The sequence of work, decomposed enough that each step is verifiable on its own. This is where SDD and good planning overlap — a spec with a clear task breakdown is most of a plan already. Decomposition also lets the agent (and you) check progress incrementally instead of judging a single giant diff at the end.

6. Verification criteria

How you will prove the work is correct. Tests that must pass, a contract the output must satisfy, a manual check, a benchmark threshold. Verification criteria are what turn the agent's self-congratulation ("done!") into something you can actually trust, because the agent now has an external standard to meet rather than its own opinion of completeness.

When to use SDD — and when to skip it

Spec-driven development is a discipline with a cost, and applying it everywhere is its own anti-pattern. The judgement call is about the lifespan and ownership of the code. Write a spec when the code will live a long time, be maintained by more than one person, or carry real consequences if it drifts. Skip the spec when the code is disposable.

The pattern teams converge on is a two-phase rhythm that gets the best of both. First you vibe-code a spike: prompt loosely, let the agent explore, throw away three versions, learn what the problem actually is by building a rough cut of it. Then you distil what you learned into a spec — now you actually know the outcomes, boundaries and constraints because you have seen them in the rough — and you spec-drive the production version from that spec. The spike is where you discover the requirements; the spec is where you pin them; the spec-driven build is where you ship something you can maintain.

Spec-drive it	Skip the spec
Production code that ships to users	A throwaway script you will run once and delete
Multi-month projects with evolving scope	A weekend prototype to test an idea
Anything multiple people maintain	An exploratory spike to learn the problem
Regulated or security-sensitive work	A data-munging one-liner for your own use
The second build, after a spike taught you the shape	The first build, when you do not yet know the shape

The 2026 tool landscape

By mid-2026 every serious coding-agent vendor ships its own flavour of SDD, which is the clearest signal that the discipline has crossed from idea to expectation. The mechanisms differ in name and ergonomics; the underlying move — write a structured spec, generate against it, verify — is the same everywhere. As of mid-2026, here is how the field lines up. Verify exact feature names against each tool's live docs, because this space moves monthly.

Tool	SDD flavour	Best fit
GitHub Spec-Kit	Open-source toolkit; a structured spec-then-plan-then-tasks process you drive from the CLI	Teams that want a tool-neutral, version-controlled process they own
AWS Kiro	Spec-centric IDE: requirements, design and tasks generated as first-class files	Teams standardising on AWS who want the spec baked into the editor
Claude Code	CLAUDE.md context plus plan mode — propose a plan, approve, then execute	Terminal-centric teams who live in the shell and value a plan gate
Cursor	Plan Mode plus AGENTS.md — agent drafts a plan you edit before it codes	IDE-first teams; the strongest fit if your work lives in the editor
OpenSpec	Open standard / format for writing portable specs agents can consume	Teams wanting tool-independent specs that outlive any one vendor
BMAD	Agentic method with role-based agents (analyst, PM, architect) driving the spec	Teams who want an opinionated, multi-role workflow out of the box
Tessl	Spec-as-source approach where the spec is the maintained artifact	Teams leaning fully into spec-sovereignty over code
Google Antigravity	Agent-first development surface with spec and plan artifacts	Teams in the Google ecosystem trying an agent-native workflow

The honest builder-angle takeaway is that the tool matters far less than the discipline. A team in London using Cursor Plan Mode and a team in Bengaluru using Claude Code with a tight CLAUDE.md are doing the same thing: writing intent down before code, gating execution on an approved plan, and keeping the spec in version control. Pick the tool that fits where your team already works — IDE, terminal, or a neutral toolkit like Spec-Kit — and put your energy into writing good specs, not into evaluating yet another vendor. If you want a deeper look at the plan-gate mechanics specifically, our guide on plan-first Claude Code workflows walks through approving a plan before any code is written, and the dynamic workflows with Opus 4.8 piece covers steering longer agent runs.

A spec template you can paste into a repo

Below is the six-element template rendered as a markdown file you can drop into specs/ and fill in per feature. The point is not the exact format — adapt the headings to your tools — but that every one of the six elements has a home, so none of them gets silently skipped. Keep these files in the repository, version them alongside the code, and update them when the design changes. A spec that lives outside the repo goes stale the day it is written.

# Spec: Password reset via emailed one-time link

## 1. Outcomes
A signed-out user can request a password reset by email. They receive a
one-time link that expires in 15 minutes and can only be used once.
Using it lets them set a new password and signs them in.

## 2. Scope boundaries
IN:  request endpoint, token generation + storage, email send, reset
     endpoint, single-use + expiry enforcement.
OUT: the OAuth login flow (untouched), rate limiting (separate ticket
     PAY-412), the email template engine (reuse existing), MFA.

## 3. Constraints
- Tokens are 256-bit, single-use, stored hashed (never plaintext).
- Email send is async via the existing queue; the request endpoint
  must return in < 300ms p95 regardless of mail latency.
- UK user data stays in eu-west-2 (London); India data in ap-south-1
  (Mumbai). No cross-region token storage.

## 4. Prior decisions (do not reopen)
- Email provider is the existing transactional service. Decided.
- Sessions use the current cookie-based scheme. Decided.

## 5. Task breakdown
1. Add `password_reset_tokens` table (migration — propose, do not apply).
2. POST /auth/reset/request — generate, hash, store, enqueue email.
3. POST /auth/reset/confirm — verify, enforce single-use + expiry, set
   password, start session.
4. Expire/cleanup job for stale tokens.

## 6. Verification criteria
- Contract tests for both endpoints under tests/contract/.
- Test: a used token is rejected on second use.
- Test: a token older than 15 minutes is rejected.
- Test: request endpoint returns in < 300ms with mail mocked.
- `make test` and `make lint` clean.

Hand that to a coding agent and the difference is immediate. There is no room for it to invent a thirty-minute expiry, store the token in plaintext, reach for a different email provider, or quietly add rate limiting you did not ask for — every one of those drifts is pre-empted by a line in the spec. The agent's job shrinks from "design and build a password reset" to "implement these four tasks against these constraints and prove it with those tests," which is a job models do extremely well.

The pitfalls, and how to avoid them

SDD has three failure modes, and all three are about how you keep the discipline rather than whether you adopt it. Naming them up front is the difference between a practice that sticks and one your team abandons after a fortnight.

Over-speccing trivial work

Covered above, but worth repeating because it is the most common killer. The moment writing the spec costs more than the bug it would prevent, you have over-specced. Match the weight of the spec to the weight of the work. For a one-line fix, a sentence in the commit message is the spec.

Specs that drift from the code

The mirror image of code drift. If the spec says one thing and the code has since evolved to do another, the spec is now actively misleading — worse than no spec, because people trust it. The fix is to treat specs as living documents: version them in-repo next to the code, update them in the same pull request that changes behaviour, and review them as part of the diff. A spec that is not maintained is technical debt with good intentions.

Treating SDD as waterfall

The biggest conceptual trap. A spec is not a contract you write once, freeze, and hand to a downstream team to implement over six months. SDD is iterative: you spec, the agent generates, you verify, and what you learn feeds back into a revised spec. The loop is tight — often minutes, not weeks. If your spec cannot change after the first agent run, you have reinvented the waterfall the industry spent thirty years escaping. The spec is sovereign, but it is also alive.

Done well, the rhythm feels less like documentation and more like a conversation with a very fast, very literal collaborator. You state intent, it builds, you check against your own criteria, you sharpen the intent, it rebuilds. The spec is simply the written record of that intent at any moment — the thing that keeps the agent and the team pointed at the same target. For larger builds where several agents work in parallel, that shared target becomes essential; our guide on multi-agent orchestration in production covers how a spec coordinates work across subagents, and if you are wiring agents to your own tools, the build-your-first-MCP-server guide shows how to give them capabilities the spec can then govern.

What you should actually do this week

Start small and let the practice earn its place. If you have no AGENTS.md or CLAUDE.md in your main repository, write one this week using the skeleton above — that alone removes a surprising amount of drift, because the agent stops reinventing your conventions on every task. Then pick the next non-trivial feature you would otherwise have vibe-coded and write a six-element spec for it first. Notice how much of what you would have caught in code review you instead caught while writing the spec, when it was a sentence to change rather than a diff to redo.

For exploratory work, keep vibe-coding — that is the right tool for discovering what the problem is. Just make the handoff explicit: when the spike has taught you the shape of the thing, stop, distil the spec, and rebuild the production version against it. And whichever tool you adopt — Spec-Kit, Kiro, Cursor Plan Mode, Claude Code, or any of the others — put the specs in version control and update them when behaviour changes. The discipline is the asset. The tool is just where you practise it.

Coding agents are not going to get less capable. They are going to get faster and more autonomous, which means the cost of pointing them at the wrong target keeps rising. Spec-driven development is how you make sure that when the agent runs — and it will run fast — it runs at the thing you actually meant. Write the spec. Make it sovereign. Keep it alive. The teams in Bengaluru and London that get this right in 2026 are not the ones with the cleverest prompts. They are the ones who decided, before the agent ever ran, exactly what "done" was going to mean.