The practice guide · Specs before code

Spec-driven development, explained

Spec-driven development is the practice of writing an executable specification before any code — so humans and AI agents build from the same written intent instead of from guesswork. This page is the practical guide: the constitution → specify → plan → tasks workflow, why specs change what agents deliver, how teams adopt it with GitHub Spec Kit, and the pitfalls that turn specs into ceremony.

Microsoft Solutions Partner — Cloud & AI Platforms — Specialist: Agentic DevOps with Microsoft Azure and GitHub
GitHub Verified Partner

1 spec

one committed source of intent for humans and agents

4 phases

constitution → specify → plan → tasks — the Spec Kit workflow

Any agent

Copilot, Claude Code, Cursor — the same spec drives all of them

0 code

before the spec is approved — intent first, implementation second

The teams that build with Deop

Globys
iMDsoft
Volaris Group
Vela Software Group
Intellicene
Optimal Blue
Trisura

What is spec-driven development?

The spec becomes the source of truth

In spec-driven development, requirements stop being a document someone wrote once and start being the artifact everything else is generated from and verified against: user stories with acceptance criteria, a technical plan that honors your architecture, and a task list scoped for execution. The spec lives in version control, gets reviewed like code, and outlasts the chat window it was drafted in.

Why it matters now: AI agents amplify clarity and punish ambiguity. A vague issue handed to a coding agent produces a confident, wrong pull request — while a written spec turns the same delegation into an engineering practice. That's why spec-driven development has become the highest-leverage habit in the agentic era, and why GitHub built Spec Kit, an open-source toolkit, around exactly this workflow.

The workflow

Constitution → specify → plan → tasks

1 · Constitution

Your engineering non-negotiables

Quality bars and coding standards

Written once, versioned forever

Every spec inherits these guardrails

Stops scope drift at the root

Reviewed like code, because it is

→

2–3 · Specify & plan

Specify — requirements become an executable spec: user stories, acceptance criteria, explicit boundaries

Plan — a technical plan generated against your actual stack, architecture, and constitution

Both artifacts are committed to the repo — reviewed, diffed, and owned like any other change

→

4 · Tasks

✓ Plan decomposed into agent-sized tasks

✓ Each one scoped, bounded, verifiable

✓ Humans or agents execute — same spec

✓ Review against acceptance criteria, not vibes

The artifacts live in version control —

constitution · spec · plan · tasks

— so intent survives the chat window it was drafted in

Where specs fit in the whole lifecycle: the AI SDLC guide →The spec’s companion file: the AGENTS.md guide →

Why it works

Why specs change what agents deliver

Clarity in, quality out

Agents amplify clarity and punish ambiguity. A vague issue produces a confident, wrong pull request; a spec with acceptance criteria produces work you can actually verify.

Vague issue → confident, wrong PR

Acceptance criteria → checkable output

Boundaries stated up front, not in review

Fewer rework loops per feature

Review moves up a level

Instead of reviewing every diff from scratch, teams approve the spec once — then review pull requests against criteria that are already written down.

Approve intent before code exists

Review diffs against acceptance criteria

Disagreements surface in the spec, not the PR

Smaller, task-sized pull requests

Intent outlives the chat

Prompts vanish when the session ends. A committed spec, plan and task list stay in the repo — diffable, reviewable, and readable by the next engineer or agent.

Specs versioned next to the code

Plans that honour your architecture

Onboarding from the repo alone

An audit trail of why, not just what

Portable across agents

Spec Kit's artifacts are plain Markdown in your repo, so the same spec drives GitHub Copilot, Claude Code, Cursor or the next agent — the practice outlasts any one tool.

No lock-in to one coding agent

Same spec for humans and agents

Pairs with AGENTS.md for repo conventions

Works in brownfield and greenfield repos

Getting started

How teams adopt spec-driven development

Delivered with

Microsoft

+

GitHub

1

Install Spec Kit

GitHub's open-source toolkit (github/spec-kit) adds the workflow as slash commands — /constitution, /specify, /plan, /tasks — inside Copilot, Claude Code, and other coding agents. One afternoon to set up.

2

Write the constitution

The project's non-negotiables: quality bars, architectural principles, what never changes without a human decision. Short, reviewed, versioned — every later spec inherits it automatically.

3

Spec one real feature

Not a toy — a mid-sized feature from the actual backlog. Run specify and plan, and judge the output the way you'd judge a design doc: would a new engineer build the right thing from this?

4

Approve the spec, delegate the tasks

The human review moves up a level: approve the spec, then let agents or engineers execute the tasks. Pull requests get reviewed against the acceptance criteria the spec already wrote down.

The toolchain

One practice, every agent

spec → agent → pull request

Spec Kit is agent-agnostic by design: the same committed artifacts drive GitHub Copilot's coding agent, Claude Code, Cursor, and whatever ships next — while an AGENTS.md file carries your repo conventions alongside the spec. The practice is the investment; the agents are interchangeable.

Author

/constitution and /specify turn intent into reviewed, committed artifacts

Execute

agents take tasks · humans take the judgment calls · same spec for both

Verify

acceptance criteria as tests · deterministic CI gates · one review bar

↻ Lessons from every feature flow back into the constitution — the spec system improves with use

The pitfalls

Where spec-driven development goes wrong

Specs as ceremony

If the spec isn't the actual input the agent executes from, it's just documentation with extra steps — and it will drift from reality like all documentation does. The spec earns its keep only when something builds from it and something verifies against it.

Over-specifying

The spec owns the what, the constraints, and the acceptance criteria — not every line of the how. Dictate implementation detail and you've re-invented waterfall with more Markdown; leave execution latitude and the agent (or engineer) can actually engineer.

No verification loop

Acceptance criteria that CI can't check are wishes. The discipline that completes the practice: move every checkable criterion into tests and gates, so “done” is something the pipeline decides — and reserve human review for the judgment the spec can't encode.

The operating rule

Write less, verify more

1 feature

the right first scope — never a whole system on day one

1 repo

constitution, spec, plan and tasks committed next to the code

1 review bar

the same acceptance criteria for human and agent work

“A spec an agent can execute and CI can verify beats a perfect document nobody reads. Scope it to one feature, commit it to the repo, and let the review bar do the enforcing.”

Plain answers

Spec-driven development: plain answers

What is spec-driven development?

Spec-driven development is the practice of writing an executable specification — user stories, acceptance criteria, a technical plan, and scoped tasks — before writing code, so humans and AI agents build from the same committed source of intent. The spec lives in version control and is reviewed like code.

What is GitHub Spec Kit?

Spec Kit is GitHub's open-source toolkit for spec-driven development. It adds four slash commands to coding agents — constitution, specify, plan, and tasks — that turn a feature idea into committed, reviewable artifacts an agent can execute against. It works with GitHub Copilot, Claude Code, and other agents.

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

They're complements at different altitudes. TDD starts from a failing test and drives implementation one unit at a time. Spec-driven development starts from written intent for a whole feature — and its acceptance criteria often become the tests TDD-style loops then drive against. Specs decide what to build; tests prove it was built.

Do I need spec-driven development to use AI coding agents?

No — agents will take vague issues happily. But delegation quality tracks input clarity: vague issues produce confident, wrong pull requests, while spec'd work is where agents post their best numbers. Teams usually adopt specs after their first few disappointing agent PRs — adopting them first skips that chapter.

What goes in a constitution file?

The project's standing rules: quality bars, architectural principles, security and compliance constraints, and the decisions that must never change without a human sign-off. It's deliberately short, versioned in the repo, and inherited by every spec — so the non-negotiables are written once instead of re-argued per feature.

How does spec-driven development relate to the AI SDLC?

It's the requirements stage of the AI SDLC — and the highest-leverage one, because everything downstream inherits the spec's clarity. In the agentic SDLC, where autonomous agents execute whole tasks, the spec is what makes delegation governable: agents build from written intent, and reviewers verify against it.

Ready to make your specs executable?

A two-week, fixed-fee assessment baselines your team, sets up Spec Kit and the instructions files, and specs one real feature end to end — a working practice, not a slide deck, yours to keep either way.

Book a discovery →