~/codigoagente
AI agents

What is Spec-Driven Development (SDD)? Building with AI agents from a written spec, with an example

Spec-Driven Development (SDD) is a way of working with AI coding agents where, before asking for code, you write a specification: what is being built, for whom, why, and how you will know it works. From that spec the agent derives a technical plan, a task list and, finally, the implementation. Code stops coming out of an improvised conversation and starts coming out of a document you have reviewed.

This article explains what SDD is, where it comes from, its phases, what a good specification should contain (with a sample spec.md), which tools exist and how to apply it in Claude Code with or without installing anything. If you already know SDD and want the lighter alternative, read ODD vs SDD.

SDD in one sentence

SDD means writing the what before the how, and the how before the code, keeping each step in a file the agent re-reads instead of relying on chat history.

The problem it solves has a name: *vibe coding*. When requirements only live in messages, the agent decides every detail you did not mention, forgets what you said twenty messages ago when the context gets compacted, and when it finishes there is no way to check whether it did what you asked. OpenSpec's README puts it this way: AI assistants are powerful but unpredictable when requirements live only in chat history.

Where it comes from

Specifying before coding is as old as software engineering (requirements documents, use cases, user stories). What is new is the reader: the spec is no longer read only by humans but by an agent that uses it as an instruction. The term took off in 2025 with three tools:

  • Kiro (AWS), an IDE that generates requirements, design and tasks before coding.
  • [GitHub Spec Kit](https://github.com/github/spec-kit) (MIT), announced on September 2, 2025, which adds SDD commands to agents such as Claude Code, Copilot, Cursor and Gemini CLI.
  • [OpenSpec](https://github.com/Fission-AI/OpenSpec) (MIT), lighter and organized around changes.

Birgitta Böckeler (Thoughtworks) describes three levels on martinfowler.com: spec-first (the spec guides one task), spec-anchored (it is kept alive to evolve the feature) and spec-as-source (the spec is the only thing you edit and the code is regenerated).

The phases of SDD

The seven SDD phases with their Spec Kit commands; clarify is optional · codigoagente

Each tool names them differently, but the shape is the same. Here it is with Spec Kit's commands (main branch, November 2026), which you type in the agent's chat, not in the terminal:

  1. Constitution (/speckit-constitution), once per project: principles the agent must not break (quality, tests, performance, conventions).
  2. Specify (/speckit-specify <description>): generates spec.md with the what and why. No technology.
  3. Clarify (/speckit-clarify, optional): the agent looks for gaps in the spec and asks you up to five targeted questions; your answers are written back into spec.md.
  4. Plan (/speckit-plan <stack>): generates plan.md with the how: stack, data model, folder structure and a check against the constitution.
  5. Tasks (/speckit-tasks): generates tasks.md, a dependency-ordered list grouped by user story. Tasks that can run in parallel are marked [P].
  6. Implement (/speckit-implement): the agent executes the tasks one by one.
  7. Converge (/speckit-converge): compares the code against the spec, plan and tasks, and appends whatever is missing as new tasks. You repeat implement and converge until the report says *Converged*.

There is one more command, /speckit-analyze, which checks consistency across spec.md, plan.md and tasks.md without changing anything. The golden rule of the whole flow: review each file before moving to the next one. If you approve a spec.md without reading it, SDD protects you from nothing.

What a good specification contains

Spec Kit's official template (templates/spec-template.md) is the best reference we know, because it forces you to separate things that get mixed up in chat. Its sections:

SectionWhat it holdsWhy it matters with an agent
**Prioritized user stories**P1, P2, P3; each one can be tested and shipped aloneP1 alone is already a minimum product; the agent does not try to do everything at once
**Acceptance scenarios***Given / When / Then* per storyThey turn straight into tests
**Edge cases**What happens at the boundaries and on errorsThe first thing an agent forgets when it is not written down
**Functional requirements**`FR-001: System MUST...`Numbered, so tasks and reviews can cite them
**Doubt markers**`[NEEDS CLARIFICATION: ...]`The agent flags what it does not know instead of inventing it
**Key entities**Which data exists and how it relates, no technologyFixes the vocabulary before the database model
**Success criteria**Measurable and technology-agnostic: "in under 2 minutes"Lets you say whether the feature delivered
**Assumptions**What the agent took for grantedYou review them before they become code

The most useful idea in the template is that the spec does not talk about technology. "The system MUST prevent booking a taken slot" is specification; "add a unique index on the bookings table" is plan. Mixing them is the most common mistake.

Example: a real spec.md

We filled in the official template for a small feature of a hair salon booking app. This is what a spec you can review in two minutes looks like:

specs/001-book-slot/spec.mdtext
# Feature Specification: book a slot

**Status**: Draft · **Input**: "Customers book a free 30-minute slot with a stylist."

## User Scenarios & Testing

### User Story 1: book a free slot (P1)
A customer picks a stylist, a day and a free time, and confirms the booking.
**Independent Test**: with one stylist and a day with free slots, a booking can be made and seen.

**Acceptance Scenarios**
1. **Given** the Tuesday 10:00 slot is free, **When** the customer books it, **Then** it is booked in their name.
2. **Given** the slot is already booked, **When** another customer tries to book it, **Then** they see "That time is no longer available" and no booking is created.

### User Story 2: cancel a booking (P2)
...

### Edge Cases
- Two customers confirm the same slot at the same time: only one booking is created.
- The customer tries to book a slot in the past.

## Requirements
- **FR-001**: System MUST show only free, future slots.
- **FR-002**: System MUST prevent two bookings for the same slot, including simultaneous ones.
- **FR-003**: System MUST notify the customer via [NEEDS CLARIFICATION: WhatsApp, email or none?].

### Key Entities
- **Slot**: 30 minutes of one stylist on one day; free or booked.
- **Booking**: a slot assigned to a customer.

## Success Criteria
- **SC-001**: A customer completes a booking in under 1 minute on mobile.
- **SC-002**: Zero duplicate bookings for the same slot.

## Assumptions
- Slots always last 30 minutes.
- Payment is out of scope for this feature.

Notice three details: scenario 2 includes the literal message (it can be tested), FR-002 covers the concurrency case an agent rarely considers on its own, and FR-003 is flagged as a doubt instead of invented. With /speckit-clarify, the agent would ask you about it before planning.

SDD tools

Spec KitOpenSpecKiro
ByGitHubFission AIAWS
LicenseMITMITCommercial IDE
How you use it`specify` CLI (Python 3.11+ and uv) + commands in your agent`openspec` CLI (Node 22.20+) + skills in your agentIts own IDE
Unit of workA feature (`specs/001-.../`)A change (`openspec/changes/<change>/`), archived when doneOne spec per feature
Files`spec.md`, `plan.md`, `tasks.md` and more`proposal.md`, `specs/`, `design.md`, `tasks.md``requirements.md`, `design.md`, `tasks.md`
Requirement formatStories + *Given/When/Then* + `FR-###``SHALL` + `WHEN/THEN` scenariosEARS notation (`WHEN ... THE SYSTEM SHALL ...`)
AgentsClaude Code, Copilot, Cursor, Gemini CLI and others30+ assistantsIts own

OpenSpec (version 2.1.0) positions itself as lighter than Spec Kit: its basic flow is /openspec-propose, /openspec-apply-change and /openspec-archive-change, and it has no rigid gates between phases. Spec Kit, for its part, now offers separate flows for bugs (specify extension add bug) and for assessing ideas, without going through full SDD.

How to apply SDD in Claude Code without installing anything

You do not need a tool to do SDD; you need the order. This prompt reproduces the flow in plain Claude Code. Use it with plan mode on (Shift+Tab) so it does not touch code while it specifies:

prompttext
Let's do Spec-Driven Development for this feature: [description].
1. Read the related code. Do not change anything yet.
2. Write docs/specs/[feature]/spec.md with: prioritized stories (P1, P2...),
   Given/When/Then scenarios with the literal messages, edge cases,
   requirements FR-001..., entities, measurable success criteria and assumptions.
   No technology. Mark anything you don't know with [NEEDS CLARIFICATION] and ask me.
3. Stop and wait for my approval.
Then: plan.md (stack, data, files that change) and tasks.md (small tasks,
test first, one per commit). Ask for approval between each step.

If you want this on every feature without pasting the prompt, turn it into a skill: we explain how in Claude Code skills: what they are and how to use them. And if you would rather have the agent interview you to extract the spec, Matt Pocock's to-spec and to-tickets skills do exactly that.

Benefits and limits of SDD

Benefits

  • Fewer surprises: you decide the behavior before there is code to defend.
  • Context that survives: the agent re-reads the file, not a summary of the conversation.
  • Cheaper review: reviewing a one-page spec is faster than reviewing 600 lines of wrong code.
  • Acceptance criteria ready for tests: *Given / When / Then* scenarios turn into tests almost verbatim (we explain how in SDD vs TDD vs BDD vs DDD).

Limits

  • Overhead: applied to everything, a three-line bug produces several Markdown files. Böckeler saw Kiro turn a small fix into four user stories with 16 acceptance criteria.
  • A lot of text to review: if you do not read the files, you pay the cost without the benefit.
  • The agent does not always obey: a long spec does not guarantee the agent follows it; that is why tests and the converge step matter.

Those limits are why ODD (*Organic Driven Development*) appeared: it only writes a spec when the task is large. We compare them with data in ODD vs SDD.

When to use SDD

  • Yes: new projects, multi-session features, client work where the scope must be approved, teams where several people or agents implement against the same contract, industries that need requirement traceability.
  • Not needed: bugs you understand, style tweaks, changes you could resume just by reading the git diff.
  • Middle ground: light SDD when the project starts (a PRD, the architecture and the tickets) and direct tasks with test first after that.

Common mistakes

  • Putting technology in the spec. "Use Postgres with a unique index" belongs in the plan. If it is in spec.md, you cannot change your mind without rewriting the requirements.
  • Approving without reading. SDD's value is your review between phases. Without it, you only added files.
  • Criteria without messages or numbers. "Must be fast" cannot be checked; "in under 1 minute" can.
  • Not flagging doubts. If the agent fills gaps without asking, the spec looks complete but contains decisions nobody made.
  • Letting the spec die. If you change behavior in the code and not in spec.md, the next feature starts from a false document.

Frequently asked questions

What does SDD stand for in programming?

*Spec-Driven Development*: writing a reviewable specification before an AI agent (or a person) implements. Not to be confused with SSD, which is a kind of disk.

Is SDD the same as writing a PRD?

They are close. A PRD describes a whole product for people; an SDD spec describes one feature in a format designed for an agent to execute and verify: numbered requirements, testable scenarios and flagged doubts.

Do I need Spec Kit to do SDD?

No. Spec Kit, OpenSpec and Kiro automate the flow and provide templates, but with a prompt like the one in this article and a docs/specs/ folder you can do SDD with any agent.

Does SDD work with Claude Code?

Yes. Spec Kit and OpenSpec both integrate with Claude Code, and the manual flow works with plan mode.

Does SDD replace tests?

No. The scenarios in the spec say which tests must exist; the tests are what prove the code complies. Spec Kit's constitution template suggests a test-first principle as an example.

Conclusion

SDD is about writing down, before the code, what you want and how you will know it is right, and having the agent work from that document. Its value lies in the spec itself (prioritized stories, testable scenarios, numbered requirements and flagged doubts), not in the tool. Start with this article's prompt on your next large feature and save the full flow for when the scope justifies it.

From spec to a project in production

Writing the spec is step one; then it has to become tickets, you need memory across sessions, code review and a deployment. The guide Claude Code de cero a producción (in Spanish) walks that whole path with a real project (a hair salon booking app, in fact): planning with light SDD and ODD, PRD, architecture and ticket templates, skills to plan and review, and deployment to Vercel or your own VPS. It includes 68 ready-to-copy prompts. It costs 19.99 USD, one-time payment: get the guide here.

Sources: GitHub Spec Kit (README, templates/spec-template.md and templates/commands/) · OpenSpec (README, v2.1.0) · Kiro: specs concepts · Birgitta Böckeler, "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl".

// source code

Repositories in this article
The code this article covers is public: browse it, star it or clone it from here.

Help us grow

codigoagente is free, with no paywalls. If this article helped you, any of these keeps the blog going.

// newsletter

One email a week with the repos worth your time

The week's new articles, tested against real code. No spam; unsubscribe in one click.

AI agents

guide · The complete ECC guide for Claude Code · #8

AgentShield, ECC's scanner, checks CLAUDE.md, settings.json, MCP, hooks and agents. We ran it on a deliberately vulnerable setup and on ECC's own install.
  • Security and code review
  • Claude Code
read article
AI agents

guide · The complete ECC guide for Claude Code · #7

We measured ECC's context footprint with /ecc:context-budget --audit (about 12,500 tokens on the minimal profile) and how to trim it: model, compaction and MCP.
  • Claude Code
  • Skills for your agents
read article
AI agents

guide · The complete ECC guide for Claude Code · #6

What ECC's 28 hooks do, how GateGuard stops the first edit, how to save and resume sessions and how continuous learning instincts work, with a real test.
  • Claude Code
  • Skills for your agents
read article