The practice guide · Specs before code
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, the numbers that make the case, how teams adopt it with GitHub Spec Kit, and the pitfalls that turn specs into ceremony.
of new production code industry-wide is AI-generated
constitution → specify → plan → tasks — the Spec Kit workflow
individual task output with AI assistants — org delivery stays flat unmanaged
task-level gains on well-scoped, spec'd work with clear acceptance criteria
The teams that build with Deop
What is spec-driven development?
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
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
Why it works
+21% individual output, roughly flat org delivery — the gains die where intent isn't shared. A written spec is the cheapest way to move gains from the individual to the system.
Autocomplete accelerates typing, not delivery
Gains pool in individuals, not in flow
Org-level lift requires process redesign
This gap is the entire adoption problem
Agents are dramatic on well-scoped, verifiable work with clear success criteria — which is precisely what the specify and tasks phases manufacture.
Test backfills and coverage lifts
Documentation and doc-drift repair
Dependency bumps and mechanical migrations
Small features against a written spec
The honest program-level number for a managed first year — and it compounds fastest where specs and deterministic gates mature together.
Grows with delegation share, not seat count
Compounds through failure-clinic discipline
Leading indicators move first: review latency, PR size
Scale decisions belong on your data, not benchmarks
With this much AI-authored code, reviewers need written intent to review against — a spec turns “looks fine” into “meets the acceptance criteria.”
Review latency is the new bottleneck
One review bar for human and agent code
Provenance and audit trails in regulated work
Change failure rate is the safety gate
Getting started
Delivered with
+
1
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
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
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
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
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
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.
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.
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
DORA: lead time, deploy frequency, change failure rate, MTTR
DX: speed, effectiveness, quality, impact — baselined before rollout
individual-level metrics — team scorecards only
“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 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.
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.
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.
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.
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.
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.
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 →