What Is Spec-Driven Development? Definition and Example

Spec-driven development (SDD) is a way of working with coding agents where you first write a specification inside the repository: a document that states what the software must do and when it’s considered correct. The agent reads that document and generates the code from it. A coding agent is a program like Claude Code, Copilot, Cursor, or Codex that can read your files and write changes on its own.

To follow the rest, you just need to know what a git repository is and have asked an AI assistant to write you a function at least once.

The spec is stored in git alongside the code and reviewed in the same pull request as the change. That’s the whole difference from a prompt: the prompt evaporates the moment you close the chat.

What goes inside a spec

A spec states what goes in, what comes out, what can’t break, and how to verify the result works. It’s usually a short markdown file, about the size of a well-written ticket: like a ticket, it says what’s expected and how to check it, not how to implement it line by line.

# Spec: exportar facturas a CSV

Entrada: un rango de fechas.
Salida: un CSV con una fila por factura emitida.

Reglas que no se negocian:
- Las facturas anuladas nunca aparecen en el export.
- Los importes van con dos decimales y punto como separador decimal.

Criterios de aceptación:
- [ ] Un rango sin facturas devuelve un CSV solo con la cabecera.
- [ ] Una factura anulada dentro del rango no sale en el fichero.

Fuera de alcance: exportar a Excel.

Notice what’s missing: no function names, no libraries, no folder structure. Those decisions are left to the agent. What you fix are the behavior and the acceptance criteria — exactly the part the agent can’t guess.

And those criteria do double duty: they’re what you review, and they’re what the agent uses to know when it’s done. This is just what a spec looks like; what makes one good (and the typical mistakes that turn it into busywork) is covered in the full guide.

How it differs from just asking in chat

You can get the same invoice export by typing a paragraph in the chat, and it’ll work. The difference shows up in the second week.

	Prompt in chat	Spec in the repository
Where it lives	In the conversation, until you close it	In git, next to the code
Who reviews it	No one	Your team, in the pull request
When the agent gets it wrong	You explain it again from scratch	You fix the spec and the correction sticks forever
Six months later	The reasoning behind each decision is nowhere to be found	You read why it was decided that way

The agent starts every session with no memory of the last one. The spec is the only place where you can put what you decided in writing for it — and where you can reread it yourself once you’ve forgotten.

Where the term comes from

The term became popular during 2025, pushed by two things at once. Sean Grove, from OpenAI, gave a talk titled The New Code at that year’s AI Engineer World’s Fair, arguing that the artifact worth versioning is the written specification, not the generated code. His comparison: keeping only the code that comes out of the model and discarding the prompt is like versioning the binary and shredding the source code.

The tools arrived in parallel. AWS launched Kiro in July 2025, an IDE that generates the requirements.md, design.md, and tasks.md files before a single line of code is touched^[1]. GitHub open-sourced Spec Kit in September 2025^[2], with a command flow any agent can follow: /speckit.specify to describe the what, /speckit.plan for the technical approach, /speckit.tasks to break it down, and /speckit.implement to execute it^[3].

Neither of the two invented the idea of writing requirements before coding. What’s new is who reads them: the primary reader is now an agent that’s going to generate the code, not a colleague who’s going to interpret them.

When to write a spec — and when not to

Write a spec when the change contains decisions someone will need to understand later: business rules, contracts between systems, edge cases that aren’t obvious from reading the code. For renaming a variable or fixing an error message, a spec costs more than it saves.

If you want the full argument for why this practice works, with the data on perceived speed and generated-code quality, you’ll find it in the complete guide to spec-driven development. And since SDD is one concrete way of directing agents, it fits within the same patterns we cover in the agentic patterns course.

Sources

AWS Launches Kiro, A Specification-Driven Agentic IDE — Forbes — Kiro’s launch date and its requirements, design, and tasks workflow.
GitHub Open Sources Kit for Spec-Driven AI Development — Visual Studio Magazine — public announcement of Spec Kit in September 2025.
github/spec-kit, official repository — description of the toolkit and its workflow commands.

Frequently Asked Questions

What does SDD stand for?

SDD stands for spec-driven development. You’ll sometimes see it spelled out as “specification-driven development” in documentation and tools; they mean the same thing.

Is it SSD or SDD? (the common mix-up)

SDD. When typing it, a lot of people write “SSD” by mistake, which stands for solid-state drives — nothing to do with specifications or coding agents.

What is spec-driven development with AI?

It’s the same concept, with one nuance: the spec is no longer written for a colleague to read, but for an AI coding agent (Claude Code, Copilot, Cursor, Codex) to read and generate the implementation from. Before agents, a requirements document served to align people; now the primary reader is the model, and that changes what’s worth including: less prose for humans, more verifiable acceptance criteria the agent can check for itself.

Is spec-driven development the same as writing documentation?

They’re different things. Documentation describes something that already exists and is written afterward. A spec describes something that doesn’t exist yet and is written beforehand, because it’s the input the agent reads to generate the code. If you write it after the pull request has already been merged, what you’ve written is documentation.

Do you need a spec for every change?

No. For small, obvious changes — renaming a variable, tweaking an error message — writing the spec takes more time than making the change, and you end up with a file no one will ever read. For a change that does deserve one — say, changing how partial refunds are calculated — the practical test is: if someone’s going to ask “why was this done this way?” three months from now, it deserves a spec.

How does spec-driven development relate to context engineering?

The spec is the stable part of the context you give the agent: the part that deserves to live in the repository instead of being re-explained in every conversation. The spec-driven development guide develops the full relationship.