Guide
What is spec-driven development?
Spec-driven development (SDD) is a workflow where a written specification, committed to the repo, is the source of truth for what gets built. People write and review the spec; AI coding agents implement against it. This guide covers where the practice came from, how the workflow runs, the tools involved, and how product teams manage a growing backlog of specs.
The definition
The spec, not the ticket, drives the work
In spec-driven development, every meaningful change starts as a spec: a markdown document that captures the intent, requirements, and acceptance criteria for a piece of work. The spec lives in the repository next to the code it describes. It is versioned in git, reviewed in pull requests, and readable by both people and machines.
GitHub's Spec Kit announcement describes it as flipping the script on traditional development: instead of code being king and specs being scaffolding you throw away, the spec becomes the contract that tools and agents use to generate, test, and validate code. Kiro's spec docs make the same move from the IDE side: specs are structured artifacts that bridge product requirements and technical implementation, approved by a human before an agent writes a line of code.
Why now
AI coding agents made the spec the unit of work
Coding agents can now implement large changes autonomously, but the quality of what they build is bounded by the quality of what they are told. A chat thread is disposable context; a spec is durable context. Anthropic's Claude Code best practices make this point from the agent's side: separate planning from implementation, and keep the instructions that matter in files the agent reads on every run rather than in conversation history.
The ecosystem has standardized around this idea. AGENTS.md gives every coding agent a predictable place to find repo-level instructions, with OpenAI Codex, Cursor, Jules, and others reading it before doing any work. The Model Context Protocol extends the same principle beyond the repo, letting agents read and act on structured project state. Specs are the natural next layer: durable, reviewable statements of intent that both your team and your agents build from.
The workflow
Specify, plan, break into tasks, implement
The core loop is the same across Spec Kit, Kiro, and OpenSpec, with human checkpoints between every phase.
Specify
Describe the feature in plain language: the intent, the user stories, the acceptance criteria. Tools like Spec Kit's /specify command or a Kiro spec session turn that into a structured spec file committed to the repo.
Plan
Turn the what into a how: architecture choices, constraints, and technical design. Kiro captures this as design.md; Spec Kit as a plan the agent must follow. You review and approve it before anything is built.
Break into tasks
The plan is decomposed into small, testable tasks an agent can execute one at a time. Each task is checkable against the spec, which keeps long agent runs from drifting.
Implement and review
Coding agents (Claude Code, Copilot, Codex, Cursor, Gemini CLI) implement against the spec, and the diff comes back as a pull request. The spec ships with the code that fulfilled it.
The toolchain
Three layers of spec-driven tooling
Authoring tools produce the specs, coding agents implement them, and open standards keep everyone reading from the same context.
Spec authoring
Tools that turn intent into structured, reviewable specs in your repo. Spec Kit writes specs/<feature>/spec.md; Kiro generates requirements, design, and tasks; OpenSpec manages specs as change proposals.
Coding agents
The agents that implement against specs. Each reads the spec and project instructions from the repo, plans, and executes tasks, whether it runs in a terminal, an IDE, or CI.
Shared context standards
Open standards that let people, tools, and agents share one view of the work: AGENTS.md for repo-level instructions, and the Model Context Protocol (MCP) for structured access to project state like a backlog.
The missing layer
Specs multiply. Someone has to run product across them.
Every tool above is feature-scoped: it takes one idea from intent to implementation. Adopt SDD for real and the specs multiply fast. Dozens of spec.md files across products and repos, each authored by a different mix of PMs, engineers, and agents. Then the product questions arrive: which specs do we build next? Who owns each one? What ships in the next release, and what does the roadmap look like by quarter?
Traditional trackers answer those questions by copying specs into a second system of record, which is exactly the duplication SDD was meant to end. Specboards answers them in place: it indexes the spec files already in your repo, then layers ideas, a prioritized backlog, a kanban board, a roadmap, and releases on top. And because it exposes that plan over MCP, the same agents implementing your specs can read priorities, update status, and write new specs back to git.
Further reading
Core material from the platforms
First-party docs and posts from the teams building spec-driven agentic development.
GitHub
Spec-driven development with AI: get started with a new open source toolkit
GitHub's announcement of Spec Kit, and the clearest statement of the core idea: the spec becomes the contract your agents use to generate, test, and validate code.
GitHub
Spec Kit documentation
The official docs for the specify, plan, tasks, implement workflow, with support for 30+ coding agents including Copilot, Claude Code, and Gemini CLI.
Kiro (AWS)
Specs: concepts and workflow
How Kiro structures a spec into requirements.md, design.md, and tasks.md, and runs agents against the approved plan.
Anthropic
Best practices for Claude Code
The agent-side case for specs: separate planning from implementation, and keep durable instructions in files the agent can read instead of chat history.
OpenAI
Custom instructions with AGENTS.md
How Codex discovers and layers AGENTS.md instruction files before doing any work, from global scope down to the repo.
agents.md
AGENTS.md: an open format for guiding coding agents
The cross-vendor standard (stewarded under the Linux Foundation) that gives every agent a predictable place to find project instructions.
Model Context Protocol
modelcontextprotocol.io
The open protocol that lets agents reach beyond the repo: read a backlog, update status, and act on structured project state.
martinfowler.com
Understanding spec-driven development: Kiro, Spec Kit, and Tessl
A critical, tool-by-tool comparison of the leading approaches, useful for understanding the trade-offs before you pick a workflow.
OpenSpec
OpenSpec on GitHub
A lightweight, agent-agnostic take on SDD: change proposals and specs as markdown in git, reviewed before any code is written.
Already writing specs? Add the product layer.
Specboards turns the specs in your repo into a backlog, board, and roadmap your team and your agents share.