What is spec-driven development, and how does it work with coding agents?

Summary

• Spec-driven development (SDD) means writing a spec before writing code with AI. The spec becomes the source of truth for the human and the AI.
• Specs are structured documents written in natural language, usually markdown, not formal schemas. Spec Kit moves from a constitution to a spec, a plan, tasks, implementation and convergence. Kiro uses requirements, design and tasks files.
• Birgitta Böckeler describes three levels: spec-first, spec-anchored and spec-as-source. Every SDD approach she found is spec-first.
• Agents don't always follow every instruction, and the same spec can produce different code, so SDD still needs tests and human review.
• On Databricks, Genie Code reads AGENTS.md and CLAUDE.md files, and Unity Gateway governs the coding agents that implement the tasks.

What is spec-driven development, and how does it work with coding agents?

Spec-driven development means writing a spec before writing code with AI. The spec becomes the source of truth for the human and the AI. In practice you define what and why first, turn that into a plan and a task list, hand them to a coding agent, and check the result against the spec.

What does the workflow look like?

Spec Kit is an open-source toolkit (MIT licensed) that gives coding agents structured processes and templates. It needs Python 3.11 or later, uv and a supported coding agent, including Claude Code and Codex:

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

You then run its skills in the agent's chat, one at a time, and review each result before continuing.

Phase	Purpose	Spec Kit skill
Principles	Establish or update project principles, once per project	/speckit-constitution
Specify	Define requirements and user stories	/speckit-specify
Plan	Create the technical implementation plan	/speckit-plan
Tasks	Break the plan into actionable tasks	/speckit-tasks
Implement	Execute the tasks	/speckit-implement
Converge	Assess the implementation against the spec, plan and tasks, then append remaining work as new tasks. Repeat implement and converge until it reports Converged	/speckit-converge

Optional quality gates resolve ambiguity, generate checklists and check consistency. Codex invokes the same skills as $speckit-<command>. Kiro has a similar shape: requirements.md holds user stories and acceptance criteria, design.md holds technical architecture, and tasks.md holds discrete, trackable tasks.

What does a spec look like?

A spec is written in natural language. Böckeler defines it as a structured, behavior-oriented artifact, or set of related artifacts, that expresses software functionality and serves as guidance to AI coding agents. In her test of Kiro, each requirement was a user story with acceptance criteria in GIVEN, WHEN, THEN form. An illustrative requirement:

Requirement 1: Order total
User story: As a shopper, I want the order total to include every line item, so that I am charged the right amount.
Acceptance criteria:
1. GIVEN an order with three line items, WHEN the total is calculated, THEN it equals the sum of the line item amounts.
2. GIVEN an order with a negative amount, WHEN it is submitted, THEN it is rejected with an error.

What are the three levels of spec-driven development?

Level	What it means
Spec-first	A well thought-out spec is written first and used in the AI-assisted workflow for the task at hand
Spec-anchored	The spec is kept after the task is complete, for evolution and maintenance of the feature
Spec-as-source	The spec is the main source file over time, and only the spec is edited by the human

Böckeler found that all SDD approaches and definitions she saw are spec-first, but not all aim for the other two levels.

Where does spec-driven development struggle?

Böckeler ran her experiments in September 2025 and cautions that the tools evolve fast. She reported three problems:

• Review overhead: Spec Kit created many repetitive markdown files for her to review.
• Instruction drift: she frequently saw the agent not follow all the instructions, even with larger context windows.
• Non-determinism: generating code several times from the same spec gave varying results.

GitHub's post on Spec Kit, which she quotes, says your role is not just to steer but to verify. Spec Kit's own guidance for a large feature is to implement in stages and verify each stage before moving on. Keep tests and human review in the loop.

How do you give a coding agent the spec?

Keep project-wide context, which applies across sessions, in a file the agent loads. AGENTS.md is a README for agents, and Codex reads AGENTS.md files from the project root down to your working directory. Claude Code can read an AGENTS.md in place of a CLAUDE.md. Genie Code automatically discovers and reads AGENTS.md and CLAUDE.md files in your workspace.

How do you govern agents that work from specs?

Route the implementing agents through Unity Gateway by launching them with ug claude or ug codex. EXECUTE on a model service controls who can use which models, rate limits cap volume per service or user, monthly budgets can alert or block at per-user thresholds, and system.ai_gateway.usage records requests by requester.

FAQs

How does spec-driven development relate to test-driven development?

People often draw analogies between SDD and TDD or BDD. Böckeler adds a parallel to model-driven development, where the models were the specs but were not written in natural language.

Do I need a tool like Spec Kit?

Not necessarily. Böckeler writes that the spec-first principle is valuable in many situations, and that she often spends time crafting some form of spec first to give to the coding agent. Spec Kit and Kiro are two ways to structure that spec.