TDD, BDD, ADD, SDD, EDD: Which Do You Actually Need? A Practical Guide for the AI Era
> short glimpse
!SDD vs BDD
TL;DR: Five acronyms, one question: how do you know the software does what you wanted?
> TDD verifies your code.
> BDD verifies your behaviour.
> ADD / ATDD verifies your agreement.
> SDD verifies the work of your AI coding agent.
> EDD verifies the AI output you ship.
> You don't pick one. You stack them — and this article tells you where each one goes.
Read further for deepdive.
---
The Question Behind All Five
Five terms, five philosophies. And if you've been drowning in newsletters lately,
> you've probably felt the same confusion: is this a testing strategy? A process? A mindset? Are they fighting each other?
My take on this is: none of these are really "testing strategies." They're all answers to the same question, asked at different moments in software history:
> How do you know the software does what you want?
we are in the phase - AI writing the code. Writing code got cheap, fast, and almost free. Verifying code got more expensive, not less. These five practices, in different ways, are all verification tools.
Let's meet the family, one by one.
---
The Family Tree (1990s → 2026)
1990s 2003–06 2000s 2024–26 2025
│ │ │ │ │
TDD ───────────► BDD ADD EDD SDD
Kent Beck Dan North agile testing Hamel Husain GitHub Spec Kit
(Extreme (grew out of (usually written & Shreya Shankar, + OpenSpec
Programming) TDD) as ATDD) Airbnb practice
│ │ │ │ │
└────────────────┴──────────────────┘ │ │
"know what to build" │ │
(tests, behaviours, the agreement) │ │
└────────┬────────┘
│
"verify what an AI just built
(and what it shipped)"
The split is not a coincidence. The first three exist to prevent building the wrong thing. The last two exist because a new builder entered the room — one that's fast, tireless, and has zero stake in your product.
| Acronym | Full name | What it verifies | When it showed up |
|---|---|---|---|
| TDD | Test-Driven Development | Your code | Late 1990s — Kent Beck, Extreme Programming |
| BDD | Behaviour-Driven Development | Your behaviour | 2003 — Dan North |
| ADD | Acceptance-Driven Development | Your agreement | Agile years (usually written ATDD) |
| SDD | Spec-Driven Development | Your AI coding agent's work | 2025 — GitHub Spec Kit, OpenSpec |
| EDD | Eval-Driven Development | Your shipped AI's output | 2024–2026 — the AI industry |
---
TDD: The Loop That Changed Everything
Test-Driven Development was formalized by Kent Beck in the late 1990s, as part of Extreme Programming. The standard summary of the loop:
┌───────────┐
┌───►│ RED │ write the next failing test
│ └─────┬─────┘
│ ▼
│ ┌───────────┐
│ │ GREEN │ write just enough code to pass
│ └─────┬─────┘
│ ▼
│ ┌───────────┐
│ │ REFACTOR │ clean it up, tests stay green
│ └─────┬─────┘
│ │
└──────────┘ (repeat, forever)
Why it works
Two benefits, per Martin Fowler.
1. First, your code is self-testing — you can only write production code in response to making a test pass.
2. Second, and the underrated one: thinking about the test forces you to think about the interface first. You design how the thing is used before deciding how it's built.
The most common way people screw up TDD is skipping step three. No refactoring means a messy aggregation of code fragments — the tests stay green, the code doesn't.
---
BDD: Tests That Read Like English
Behaviour-Driven Development was coined by Dan North. North was teaching TDD and kept hitting the same wall: beginners asking where do I start, what should I test, what do I call this, why did it fail?
His answer was a reframe. Stop saying test. Start saying behaviour.
BDD has three parts:
1. Discovery — structured conversations around real-world examples of how the system should behave.
2. Formulation — writing those examples down in a human-readable, executable format (usually Gherkin).
3. Automation — wiring the examples to the running system as tests.
Feature: User login
Scenario: Successful login
Given a registered user exists
When the user submits valid credentials
Then they are redirected to the dashboard
The mechanics worth knowing:
- Test names are sentences, not testFailsForDupes.
- The "should" template: every test fits the class should do something. The word "should" quietly invites you to challenge the premise — should it, really? That's how stale assumptions get caught.
- The story shape: As a [X], I want [Y], so that [Z]. The "so that" forces you to state the value — and half of all feature requests die there, honestly and quickly.
- A ubiquitous language (borrowed from Domain-Driven Design): the same words appear in the requirement, the test, and the code. When everyone shares a vocabulary, miscommunication — one of the most expensive bug sources in software — drops.
BDD is for deterministic systems. The output of a login form is either correct or it isn't. assert redirect_url == "/dashboard" is a valid test. Tools: Cucumber, SpecFlow, Behave, pytest-bdd, Jest + Testing Library.
---
ADD: The Contract You Sign Before the Machine Starts
Acceptance-Driven Development / ATDD (Acceptance Test-Driven Development).
The idea is simple: before anyone writes a line of code, the team — developers, testers, and the business person — writes the acceptance criteria for the story. In natural language. End to end.
─────────
╱ ADD ╲ acceptance: "what does done mean?"
╱ the ╲ team signs off BEFORE any code
╱ contract ╲
╱───────────────╲
╱ BDD ╲ behaviour: "what should it do?"
╱ Given/When/ ╲ scenarios in plain English
╱─────────────────────╲
╱ TDD ╲ unit: "does this function work?"
╱ red-green- ╲ smallest, fastest, cheapest
╱───────────────────────────╲
Read that pyramid from the bottom up: TDD checks the parts, BDD checks the behaviour, ADD checks the agreement. Each level is slower, coarser, and closer to the business.
A story in full ADD dress:
> Story: As a user, I want to reset my password, so that a compromised account is less dangerous.
>
> Acceptance criteria:
> - A reset link expires after 30 minutes.
> - A reset link can only be used once.
> - A user with 2FA must re-verify their identity after a reset.
> - The account is logged out everywhere after a reset.
That's the whole practice. The criteria are written before implementation, reviewed by the people whose jobs depend on the feature, and become the tests the finished feature must pass. Each of the three roles gets something:
- The developer knows the exact shape of "done" before starting — and the shape rarely changes mid-build.
- The tester designs the verification while it's still cheap to change, not after the code exists.
- The business person signs off on behaviour in a language they actually read.
---
SDD: The Spec Is the Source of Truth
Spec-Driven Development is the newest heavyweight.
- GitHub Spec Kit (github/spec-kit) — GitHub's open-source toolkit (140k+ stars as of Oct 2026) for spec-driven work with AI coding agents; bug-fix and idea-assessment flows ride along, but SDD is the flagship.
- OpenSpec (openspec.dev, by Fission-AI) — a lighter-weight community framework where specs live in your repo as first-class artifacts (73k+ stars).
- AWS Kiro — an IDE with the spec-driven flow (specs, requirements, project steering docs) baked into the editor; where many teams first meet SDD.
The fundamental problem SDD solves: if you let an AI agent write both the component and the tests for it, the agent will unconsciously write **tests that pass — not tests that verify.
** SDD ** breaks that cycle by locking the spec before any code exists. The spec is written by a human. The code is written by the agent.
> The spec is the non-negotiable contract between them.
OpenSpec's mental model is the contract and the contractor: a contractor who shows up with no blueprint builds whatever they think you meant. OpenSpec is the contract. The agent is the contractor.
The Spec Kit flow
/speckit-constitution once per project: principles (quality, tests, style)
│
▼
/speckit-specify ──► /speckit-plan ──► /speckit-tasks
what & why stack & the spec, broken
constraints into an ordered task list
│
▼
┌────────────────────────────────────┐
│ /speckit-implement │
│ │ │
│ ▼ │
│ /speckit-converge │
│ does the code match the spec? │
│ │ no │ yes │
│ └───────────► "Converged" │
│ (fix & re-implement) │
└────────────────────────────────────┘
Two details deserve emphasis. The constitution is the spec for specs — your project's non-negotiables, written once.
converge is a verb the pre-AI world didn't need: TDD asks "do the tests pass?"; SDD asks something stricter — does what was built match what was specified, end to end? The spec is the source of truth; the code is the claimant.
The OpenSpec flow
/opsx:explore optional: a no-stakes thinking partner —
reads the codebase, shapes the plan
│
▼
/opsx:propose <feature> agent writes the spec. No code yet.
│
▼
/opsx:apply <feature> agent writes code strictly following the spec
│
▼
/opsx:archive <feature> the change is folded into the main spec,
permanently
Lighter than Spec Kit:
each change is a folder of plain Markdown —
proposal.md,
specs/ (requirements and scenarios),
design.md,
tasks.md — reviewed by a human before any code is written.
Command spellings vary by tool (/opsx-propose, $openspec-propose); openspec init prints the right form for yours.
Why it works (and why it's not "just a good prompt")
Agents are bad at holding thirty requirements in their head across a long session. They're good at following a written document step by step. A spec is a leash with a purpose: it keeps intent outside the model — in a file that survives session restarts, model swaps, context windows, and team changes.
> Tell an agent a feature in chat, and the intent dies with the conversation. Write it in a spec, and it outlives everything except your product.
---
EDD: The TDD of the AI World
Eval-Driven Development that exists because of a specific technical fact: LLM output is probabilistic.
You build a support bot.
You write assert response == "Your order has shipped." and you've written a test that will fail on the first Tuesday of the month, for reasons you cannot predict.
Unit tests assume determinism.
Probabilistic output breaks that assumption, so the whole verification story has to be rebuilt. That rebuild is EDD.
The term was formalized in methodology by Hamel Husain and Shreya Shankar, and got an academic process model in the arXiv paper "Evaluation-Driven Development and Operations of LLM Agents".
The vocabulary in 60 seconds
- An eval is a test that measures whether your AI system is doing what you want. It returns a score or a pass/fail on a set of real or representative examples.
- Product evals vs model benchmarks: benchmarks (MMLU, GPQA, Terminal-Bench) say how a model does on generic tasks. They say almost nothing about your order-cancellation agent. Product evals measure your product against your users' actual needs.
- A trace is the complete record of one session: every message, tool call, and retrieval from first query to final answer. Traces are your raw material — you can't find failures you can't see.
The loop (in the correct order)
1. RUN the system, collect traces
│
▼
2. ERROR ANALYSIS
read 30–100 traces, note every failure,
group notes into a failure taxonomy
│
▼
3. BUILD an eval for each failure that matters
cheap first: code assertions, regex, JSON checks,
"did it call the right tool?"
expensive last: LLM-as-judge for judgment calls,
validated against 100–200 human labels before trusting it
│
▼
4. FIX → re-run → improved, without regressing?
│
└────────► new traces, new failures, repeat
Hamel and Shankar put it in their own FAQ: on serious projects, 60–80% of development time goes to error analysis and evaluation — that is, looking at data, not building dashboards. That ratio is the practice. If your eval workflow is 90% dashboard and 10% looking, you have the wrong workflow.
Two more rules of the road:
- Binary beats Likert. A pass/fail per failure mode beats a fuzzy 1–5 rating.
- Change one variable at a time — prompt, model, or RAG config — then measure. Otherwise you can't tell what actually improved.
The part everyone gets wrong
The naive version of EDD says: "build a golden dataset and a scoring rubric first, then develop."
Here's the correction, from the field's most-cited authority. Hamel Husain's own answer to "Should I practice eval-driven development?" is generally no. His reasoning: unlike traditional software, where failure modes are predictable, LLMs have an infinite surface area for potential failure. You can't anticipate what will break. Writing evals before the system exists means writing evals for failures you imagined — wasted effort, and it blocks you on questions you can't answer until the system exists.
The version that works:
> Do error analysis first. Write evals for failures you found, not failures you guessed.
The golden dataset is real and important — but it grows out of error analysis, as a version-controlled set of representative examples and expected quality. It's not something you author on a whiteboard in week one.
One exception: if you have a constraint where you already know exactly what success looks like — "the model must never mention competitor X" — writing that evaluator early is fine. It's a known boundary, not a prediction.
Tools: LangSmith, Braintrust, RAGAS, Arize Phoenix, Weights & Biases Weave.
When to use EDD
- Any LLM-powered feature: chatbots, RAG systems, agents, summarizers, classifiers.
- Any time you change a prompt, model, or retrieval setup and can't tell if it got better or worse. (You can't. Run the evals.)
- Before you trust a "fix" to an AI feature. If it doesn't show up in the evals, it didn't happen.
When EDD is the wrong tool
- Deterministic code with no AI in the loop. That's TDD's job.
- Week one of a new AI feature, when you have no traces yet. (You can bootstrap error analysis on synthetic data — that's standard.)
- When the team's first instinct is to buy an eval platform instead of reading 30 traces. The platform is step four, not step one.
---
SDD vs EDD: How the Two Split
This is the most common confusion in the field, so here's the clean split:
> SDD is for people who are coding and creating applications using coding agents.
> EDD is for people who are building AI-powered features as their product.
| | SDD | EDD |
|---|---|---|
| Who uses it | App developers using AI coding assistants | AI engineers building AI-powered products |
| What you're verifying | Does the generated code do what the spec says? | Does the AI output meet quality criteria? |
| Test type | Deterministic — unit tests, Gherkin, UI assertions | Probabilistic — eval sets, LLM-as-judge scores, regression metrics |
| Spec format | Analysis docs, Gherkin scenarios, PRDs | Scoring rubrics, golden input/output pairs, thresholds |
| The failing signal | expected button to be visible — FAIL | faithfulness score 0.62 < threshold 0.80 |
| Tools | GitHub Spec Kit, OpenSpec, your test framework | LangSmith, Braintrust, RAGAS, Arize Phoenix, W&B Weave |
| "Done" means | Component satisfies all spec contracts | Agent output consistently scores above threshold |
SDD's failing signal EDD's failing signal
┌───────────────────────────┐ ┌───────────────────────────┐
│ expected button to be │ │ faithfulness score 0.62 │
│ visible — FAIL │ │ < threshold 0.80 │
└───────────────────────────┘ └───────────────────────────┘
deterministic · boolean probabilistic · scored
"the spec says visible" "the judge says not faithful"
One sentence: SDD verifies that the agent built what you specified. EDD verifies that what you built is actually good.
---
When to Use Which: The Decision Guide
Stop treating these as competitors. They stack. Here's the map:
What are you building / verifying?
│
├─ deterministic code, small change ────────────► TDD
│
├─ business rule, multiple roles in the room ──► BDD
│
├─ "what counts as done?" is ambiguous, ───────► ADD
│ stakeholders must sign off
│
├─ new feature / app built by an AI agent ─────► SDD
│
├─ AI / LLM output shipped as a product ───────► EDD
│
└─ a real product (most projects) ─────────────► all of them,
layered ↓
The reference table
| Situation | Start with | Why |
|---|---|---|
| Bug fix in deterministic logic | TDD | A failing test reproduces the bug and proves the fix |
| Auth / billing / payment rules | BDD | Given/When/Then in the domain's own language |
| PM + dev + tester must agree on "done" | ADD | The contract is signed before the machine starts |
| Greenfield app via Copilot / Cursor / Claude Code | SDD | The spec anchors the agent across sessions |
| Chatbot, RAG pipeline, or AI agent | EDD | Probabilistic output — asserts don't apply |
| Swapping models (GPT → Claude → whatever) | EDD | Same prompt, different model = different quality |
| A screen / API / service you write yourself | TDD (+ BDD if it has domain rules) | Deterministic — unit tests are the right tool |
| On-device ML inside a mobile app | EDD | Precision / recall / latency, not assert |
| Everything above, in one product | Layer them | See the worked example below |
---
One Feature, Five Practices
┌─────────────────────────────────────────────┐
│ SDD — the spec │ intent: what we decided to build
├─────────────────────────────────────────────┤
│ ADD + BDD — the acceptance criteria │ agreement: what "done" means
├─────────────────────────────────────────────┤
│ TDD — the unit tests │ implementation: the code's truth
├─────────────────────────────────────────────┤
│ EDD — the evals (the AI parts only) │ quality: the output's truth
└─────────────────────────────────────────────┘
Case 1: You're building a photo organizer with AI tagging:
Photo Organizer with AI tagging
│
├─ SDD spec: "albums grouped by date, tile preview,
│ AI tags on import, tags editable"
├─ ADD criteria (with the PM): "one album per month;
│ a tag can be deleted; suggestions appear within
│ 60s for a 100-photo import"
├─ BDD behaviour: timezone grouping, in Given/When/Then —
│ exactly where "done" gets ambiguous
├─ TDD code: date logic, tag-edit API, preview pagination —
│ red/green/refactor, agent driving the loop
└─ EDD AI tagging: collect traces of real imports, read 30,
build the taxonomy ("miscategorizes group photos",
"hallucinates tags for non-photo files"), one eval
per top failure, fix, re-run
### Case 2: Mobile and On-Device ML
Mobile is where this gets interesting, because a single app might need *multiple* methodologies at once, applied to different parts of the same codebase.
A mobile app (Android / iOS / React Native / Flutter)
│
├─ app code: screens, navigation, business logic
│ │
│ ├─ you write it ──────────────► TDD / BDD
│ │ (XCTest, Espresso, JUnit)
│ │
│ └─ an AI agent writes it ─────► SDD
│ (spec first — lifecycle, offline
│ sync, and memory rules live IN the
│ spec, before the agent touches a file)
│
└─ on-device ML feature ──────────────► always EDD
(golden set + precision / recall / latency / RAM)
**Why EDD is harder on mobile.** On-device ML adds a hardware dimension server-side EDD doesn't have. Your golden dataset must cover not just output quality but:
- **RAM footprint** — peak and steady-state across low-end, mid-range, and flagship devices
- **Thermal and battery impact** — CPU / GPU / NPU utilisation under sustained load
- **Inference latency** — time-to-first-token on *real devices*, not simulators (which are too fast and too uniform)
| Platform | ML frameworks | EDD tooling |
|---|---|---|
| **iOS** | Core ML, Create ML, Apple Foundation Models | Xcode Instruments (Neural Engine, Foundation Models), XCTest assertion harnesses |
| **Android** | TensorFlow Lite, MediaPipe, ExecuTorch (NNAPI / GPU delegates) | Android Studio Profiler, custom JUnit eval harnesses against test tensors, Firebase Test Lab |
| **React Native / Flutter** | Core ML / NNAPI via platform channels, ONNX Runtime, ExecuTorch | Firebase Test Lab, BrowserStack real devices, host-side harness driving the native runtime |
The split never changes, whatever the platform: **the app code follows TDD/BDD or SDD depending on who writes it; the AI feature inside the app is always EDD.**
One feature. Five practices. None of them redundant. The spec carried the intent. The acceptance criteria carried the agreement. The behaviours carried the domain rules. The tests carried the code. The evals carried the AI quality. Remove any one and something leaks.
The one-line memory aid
| You're… | Reach for… |
|---|---|
| Building code | TDD — tests first |
| Stating behaviour | BDD — scenarios in plain English |
| Agreeing on "done" | ADD — criteria before code |
| Anchoring an agent | SDD — spec first |
| Measuring AI output | EDD — error analysis first, evals for what you find |
---
The AI-Era Mistakes we tend to do
The tools are new, so the failures are new too.
1. Trusting the agent's green light.
"The tests passed" — whose tests, run where, by whom? Run the suite yourself. Read the diff. Green means "the tests you have pass." It does not mean "correct." In the agent era, your review of the diff is the review of the agent, not of a colleague.
2. Writing evals for failures you imagined.
Hamel's "generally no" applies. If your eval suite was written before the product existed, it measures your expectations, not the product. Error analysis first, always.
3. Chasing 100% eval pass.
A perfect score is a signal that your evals are soft. The teams getting value live at 70–85% on hard checks and slowly ratchet the bar.
4. Spec rot.
The spec says one thing, the code does another, nobody noticed for three sprints. That's what the converge step exists for. A spec that isn't re-verified is a rumor.
5. Platform before practice.
Buying the fancy eval dashboard in week one instead of spending 30 minutes reading traces. The data is the practice. The platform is furniture.
6. TDD theater.
Tests written after the code that merely mirror the implementation. That's not TDD, that's a screenshot of the code. The test's job is to state intent — the thing that should be true independent of how the code got there.
---
Your Quick Start
Five steps if you want to do something this week:
1. You ship AI output? Pick 30 real traces from your system. Read them all. Write down every failure. Group them. That failure taxonomy is worth more than any eval platform.
2. Building something new with an agent? Write the spec before the first prompt. Even one page. Future-you will diff against it.
3. Business rules in the mix? Write the acceptance criteria before implementation — one screen, plain language, reviewed by the person who lives with the feature.
4. Every function, human- or agent-written, gets a test. Red first when you can. When the agent says "done," the suite is your definition of done, not its word.
5. Never merge on an agent's say-so. Run it. Read it. Ship it. That last sentence is the entire AI-era engineering methodology, distilled.
---
The Big Picture
> Every one of these practices is a response to the same fear: I built it, and it's not what I wanted.
TDD answered that fear for functions.
BDD answered it for behaviours and shared language.
ADD answered it for teams and stakeholders. And when the builders became agents.
SDD answered it for intent — what did we actually decide to build? EDD answered it for quality — is the AI output actually good, and how do we know?
You don't have to pick one. You don't have to master all five. Pick the one that matches the failure you're most afraid of this week, and run it badly at first. Then run it less badly. The practices compound: every spec you write, every behaviour you articulate, every eval you fix, makes the next build cheaper to verify.
Code is cheap now. The scarce resource was never typing — it was knowing. These five practices are all just different languages for the same sentence:
> Here's what I meant. Prove it.
---
References
The sources behind this article, in the order they were used:
1. Martin Fowler, Test Driven Development (updated Dec 2023). The standard summary of Red-Green-Refactor and its benefits. — martinfowler.com
2. Kent Beck, The Canonical TDD Post. Beck's own walkthrough of the TDD loop. — tidyfirst.substack.com
3. Kent Beck, Test-Driven Development: By Example, Addison-Wesley, 2002. The original book.
4. Dan North, Introducing BDD (2006). The canonical essay: behaviour over test, the "should" template, Given/When/Then, ubiquitous language. — dannorth.net
5. Cucumber, BDD documentation. The Discovery / Formulation / Automation structure and Gherkin reference. — cucumber.io
6. BrowserStack, TDD vs BDD vs ATDD: Key Differences. The collaborative, pre-development nature of ATDD's acceptance criteria. — browserstack.com
7. GeeksforGeeks, TDD vs BDD vs ATDD: Key Differences. — geeksforgeeks.org
8. Software Testing Help, How Testers Are Involved in TDD, BDD & ATDD Techniques. — softwaretestinghelp.com
9. Ivan Turkovic, ADD: AI-Driven Development Methodology for Modern Engineers (Jan 2026). Cited for the disambiguation: "ADD" is also used for AI-Driven Development. — ivanturkovic.com
10. GitHub, Spec Kit — the open-source toolkit for spec-driven development with AI coding agents (140k+ stars as of Oct 2026). — github/spec-kit
11. GitHub Spec Kit Documentation — the SDD walkthrough: constitution → specify → plan → tasks → implement → converge. — github.github.com
12. Fission-AI, OpenSpec — a lightweight, open-source spec framework for AI coding agents (73k+ stars); specs as first-class repo artifacts. — Fission-AI/OpenSpec · openspec.dev
13. Hamel Husain & Shreya Shankar, AI Evals: Everything You Need to Know (Evals FAQ, updated Sep 2026). The reference for the EDD loop, error analysis, LLM-as-judge, the "generally no" answer on strict EDD, and the 100%-pass-rate warning. — hamel.dev
14. Hamel Husain, Your AI Product Needs Evals. The practical guide to building domain-specific evaluation systems. — hamel.dev
15. Boming Xia, Qinghua Lu, Liming Zhu, Zhenchang Xing, Dehai Zhao, Hao Zhang, Evaluation-Driven Development and Operations of LLM Agents: A Process Model and Reference Architecture (arXiv:2411.13768). The academic treatment of EDD for LLM agents. — arxiv.org
16. Gergely Orosz & Hamel Husain (The Pragmatic Engineer), A Pragmatic Guide to LLM Evals for Devs (Dec 2025). Industry perspective on evals as an engineering discipline. — newsletter.pragmaticengineer.com
17. Exploding Gradients, RAGAS — open-source evaluation for RAG pipelines. — explodinggradients/ragas
Mentions
Revisa la especificación antes del código: también puede recoger mal lo que pediste. MIT. Requiere Python 3.11+, uv y un agente de código compatible, con su coste. github/spec-kit
Source: github/spec-kit README + integrations docs (MIT, v1.2.6 out Nov 2). Setup: uv tool install specify-cli, then specify init my-project --integration claude (or codex, cursor-agent). Reports land in .specify/bugs/<slug>/ and only "verified" confirms the fix.
Works with 30+ agents, including Claude, Codex, Copilot & Cursor. Less prompting. More building. github/spec-kit
TDD, BDD, ADD, SDD, EDD: Which Do You Actually Need? A Practical Guide for the AI Era > short glimpse !SDD vs BDD TL;DR: Five acronyms, one question: how do you know the software does what you wanted? > TDD verifies your code. > BDD verifies your behaviour. > ADD / ATDD verifies your agreement. > SDD verifies the work of your AI coding agent. > EDD verifies the AI output you ship. > You don't pick one. You stack them — and this article tells you where each one goes. Read further for deepdive. --- The Question Behind All Five Five terms, five philosophies. And if you've been drowning in newsletters lately, > you've probably felt the same confusion: is this a testing strategy? A process? A mindset? Are they fighting each other? My take on this is: none of these are really "testing strategies." They're all answers to the same question, asked at different moments in software history: > How do you know the software does what you want? we are in the phase - AI writing the code. Writing code got cheap, fast, and almost free. Verifying code got more expensive, not less. These five practices, in different ways, are all verification tools. Let's meet the family, one by one. --- The Family Tree (1990s → 2026) 1990s 2003–06 2000s 2024–26 2025 │ │ │ │ │ TDD ───────────► BDD ADD EDD SDD Kent Beck Dan North agile testing Hamel Husain GitHub Spec Kit (Extreme (grew out of (usually written & Shreya Shankar, + OpenSpec Programming) TDD) as ATDD) Airbnb practice │ │ │ │ │ └────────────────┴──────────────────┘ │ │ "know what to build" │ │ (tests, behaviours, the agreement) │ │ └────────┬────────┘ │ "verify what an AI just built (and what it shipped)" The split is not a coincidence. The first three exist to prevent building the wrong thing. The last two exist because a new builder entered the room — one that's fast, tireless, and has zero stake in your product. | Acronym | Full name | What it verifies | When it showed up | |---|---|---|---| | TDD | Test-Driven Development | Your code | Late 1990s — Kent Beck, Extreme Programming | | BDD | Behaviour-Driven Development | Your behaviour | 2003 — Dan North | | ADD | Acceptance-Driven Development | Your agreement | Agile years (usually written ATDD) | | SDD | Spec-Driven Development | Your AI coding agent's work | 2025 — GitHub Spec Kit, OpenSpec | | EDD | Eval-Driven Development | Your shipped AI's output | 2024–2026 — the AI industry | --- TDD: The Loop That Changed Everything Test-Driven Development was formalized by Kent Beck in the late 1990s, as part of Extreme Programming. The standard summary of the loop: ┌───────────┐ ┌───►│ RED │ write the next failing test │ └─────┬─────┘ │ ▼ │ ┌───────────┐ │ │ GREEN │ write just enough code to pass │ └─────┬─────┘ │ ▼ │ ┌───────────┐ │ │ REFACTOR │ clean it up, tests stay green │ └─────┬─────┘ │ │ └──────────┘ (repeat, forever) Why it works Two benefits, per Martin Fowler. 1. First, your code is self-testing — you can only write production code in response to making a test pass. 2. Second, and the underrated one: thinking about the test forces you to think about the interface first. You design how the thing is used before deciding how it's built. The most common way people screw up TDD is skipping step three. No refactoring means a messy aggregation of code fragments — the tests stay green, the code doesn't. --- BDD: Tests That Read Like English Behaviour-Driven Development was coined by Dan North. North was teaching TDD and kept hitting the same wall: beginners asking where do I start, what should I test, what do I call this, why did it fail? His answer was a reframe. Stop saying test. Start saying behaviour. BDD has three parts: 1. Discovery — structured conversations around real-world examples of how the system should behave. 2. Formulation — writing those examples down in a human-readable, executable format (usually Gherkin). 3. Automation — wiring the examples to the running system as tests. Feature: User login Scenario: Successful login Given a registered user exists When the user submits valid credentials Then they are redirected to the dashboard The mechanics worth knowing: - Test names are sentences, not testFailsForDupes. - The "should" template: every test fits the class should do something. The word "should" quietly invites you to challenge the premise — should it, really? That's how stale assumptions get caught. - The story shape: As a [X], I want [Y], so that [Z]. The "so that" forces you to state the value — and half of all feature requests die there, honestly and quickly. - A ubiquitous language (borrowed from Domain-Driven Design): the same words appear in the requirement, the test, and the code. When everyone shares a vocabulary, miscommunication — one of the most expensive bug sources in software — drops. BDD is for deterministic systems. The output of a login form is either correct or it isn't. assert redirect_url == "/dashboard" is a valid test. Tools: Cucumber, SpecFlow, Behave, pytest-bdd, Jest + Testing Library. --- ADD: The Contract You Sign Before the Machine Starts Acceptance-Driven Development / ATDD (Acceptance Test-Driven Development). The idea is simple: before anyone writes a line of code, the team — developers, testers, and the business person — writes the acceptance criteria for the story. In natural language. End to end. ───────── ╱ ADD ╲ acceptance: "what does done mean?" ╱ the ╲ team signs off BEFORE any code ╱ contract ╲ ╱───────────────╲ ╱ BDD ╲ behaviour: "what should it do?" ╱ Given/When/ ╲ scenarios in plain English ╱─────────────────────╲ ╱ TDD ╲ unit: "does this function work?" ╱ red-green- ╲ smallest, fastest, cheapest ╱───────────────────────────╲ Read that pyramid from the bottom up: TDD checks the parts, BDD checks the behaviour, ADD checks the agreement. Each level is slower, coarser, and closer to the business. A story in full ADD dress: > Story: As a user, I want to reset my password, so that a compromised account is less dangerous. > > Acceptance criteria: > - A reset link expires after 30 minutes. > - A reset link can only be used once. > - A user with 2FA must re-verify their identity after a reset. > - The account is logged out everywhere after a reset. That's the whole practice. The criteria are written before implementation, reviewed by the people whose jobs depend on the feature, and become the tests the finished feature must pass. Each of the three roles gets something: - The developer knows the exact shape of "done" before starting — and the shape rarely changes mid-build. - The tester designs the verification while it's still cheap to change, not after the code exists. - The business person signs off on behaviour in a language they actually read. --- SDD: The Spec Is the Source of Truth Spec-Driven Development is the newest heavyweight. - GitHub Spec Kit (github/spec-kit) — GitHub's open-source toolkit (140k+ stars as of Oct 2026) for spec-driven work with AI coding agents; bug-fix and idea-assessment flows ride along, but SDD is the flagship. - OpenSpec (openspec.dev, by Fission-AI) — a lighter-weight community framework where specs live in your repo as first-class artifacts (73k+ stars). - AWS Kiro — an IDE with the spec-driven flow (specs, requirements, project steering docs) baked into the editor; where many teams first meet SDD. The fundamental problem SDD solves: if you let an AI agent write both the component and the tests for it, the agent will unconsciously write **tests that pass — not tests that verify. ** SDD ** breaks that cycle by locking the spec before any code exists. The spec is written by a human. The code is written by the agent. > The spec is the non-negotiable contract between them. OpenSpec's mental model is the contract and the contractor: a contractor who shows up with no blueprint builds whatever they think you meant. OpenSpec is the contract. The agent is the contractor. The Spec Kit flow /speckit-constitution once per project: principles (quality, tests, style) │ ▼ /speckit-specify ──► /speckit-plan ──► /speckit-tasks what & why stack & the spec, broken constraints into an ordered task list │ ▼ ┌────────────────────────────────────┐ │ /speckit-implement │ │ │ │ │ ▼ │ │ /speckit-converge │ │ does the code match the spec? │ │ │ no │ yes │ │ └───────────► "Converged" │ │ (fix & re-implement) │ └────────────────────────────────────┘ Two details deserve emphasis. The constitution is the spec for specs — your project's non-negotiables, written once. converge is a verb the pre-AI world didn't need: TDD asks "do the tests pass?"; SDD asks something stricter — does what was built match what was specified, end to end? The spec is the source of truth; the code is the claimant. The OpenSpec flow /opsx:explore optional: a no-stakes thinking partner — reads the codebase, shapes the plan │ ▼ /opsx:propose <feature> agent writes the spec. No code yet. │ ▼ /opsx:apply <feature> agent writes code strictly following the spec │ ▼ /opsx:archive <feature> the change is folded into the main spec, permanently Lighter than Spec Kit: each change is a folder of plain Markdown — proposal.md, specs/ (requirements and scenarios), design.md, tasks.md — reviewed by a human before any code is written. Command spellings vary by tool (/opsx-propose, $openspec-propose); openspec init prints the right form for yours. Why it works (and why it's not "just a good prompt") Agents are bad at holding thirty requirements in their head across a long session. They're good at following a written document step by step. A spec is a leash with a purpose: it keeps intent outside the model — in a file that survives session restarts, model swaps, context windows, and team changes. > Tell an agent a feature in chat, and the intent dies with the conversation. Write it in a spec, and it outlives everything except your product. --- EDD: The TDD of the AI World Eval-Driven Development that exists because of a specific technical fact: LLM output is probabilistic. You build a support bot. You write assert response == "Your order has shipped." and you've written a test that will fail on the first Tuesday of the month, for reasons you cannot predict. Unit tests assume determinism. Probabilistic output breaks that assumption, so the whole verification story has to be rebuilt. That rebuild is EDD. The term was formalized in methodology by Hamel Husain and Shreya Shankar, and got an academic process model in the arXiv paper "Evaluation-Driven Development and Operations of LLM Agents". The vocabulary in 60 seconds - An eval is a test that measures whether your AI system is doing what you want. It returns a score or a pass/fail on a set of real or representative examples. - Product evals vs model benchmarks: benchmarks (MMLU, GPQA, Terminal-Bench) say how a model does on generic tasks. They say almost nothing about your order-cancellation agent. Product evals measure your product against your users' actual needs. - A trace is the complete record of one session: every message, tool call, and retrieval from first query to final answer. Traces are your raw material — you can't find failures you can't see. The loop (in the correct order) 1. RUN the system, collect traces │ ▼ 2. ERROR ANALYSIS read 30–100 traces, note every failure, group notes into a failure taxonomy │ ▼ 3. BUILD an eval for each failure that matters cheap first: code assertions, regex, JSON checks, "did it call the right tool?" expensive last: LLM-as-judge for judgment calls, validated against 100–200 human labels before trusting it │ ▼ 4. FIX → re-run → improved, without regressing? │ └────────► new traces, new failures, repeat Hamel and Shankar put it in their own FAQ: on serious projects, 60–80% of development time goes to error analysis and evaluation — that is, looking at data, not building dashboards. That ratio is the practice. If your eval workflow is 90% dashboard and 10% looking, you have the wrong workflow. Two more rules of the road: - Binary beats Likert. A pass/fail per failure mode beats a fuzzy 1–5 rating. - Change one variable at a time — prompt, model, or RAG config — then measure. Otherwise you can't tell what actually improved. The part everyone gets wrong The naive version of EDD says: "build a golden dataset and a scoring rubric first, then develop." Here's the correction, from the field's most-cited authority. Hamel Husain's own answer to "Should I practice eval-driven development?" is generally no. His reasoning: unlike traditional software, where failure modes are predictable, LLMs have an infinite surface area for potential failure. You can't anticipate what will break. Writing evals before the system exists means writing evals for failures you imagined — wasted effort, and it blocks you on questions you can't answer until the system exists. The version that works: > Do error analysis first. Write evals for failures you found, not failures you guessed. The golden dataset is real and important — but it grows out of error analysis, as a version-controlled set of representative examples and expected quality. It's not something you author on a whiteboard in week one. One exception: if you have a constraint where you already know exactly what success looks like — "the model must never mention competitor X" — writing that evaluator early is fine. It's a known boundary, not a prediction. Tools: LangSmith, Braintrust, RAGAS, Arize Phoenix, Weights & Biases Weave. When to use EDD - Any LLM-powered feature: chatbots, RAG systems, agents, summarizers, classifiers. - Any time you change a prompt, model, or retrieval setup and can't tell if it got better or worse. (You can't. Run the evals.) - Before you trust a "fix" to an AI feature. If it doesn't show up in the evals, it didn't happen. When EDD is the wrong tool - Deterministic code with no AI in the loop. That's TDD's job. - Week one of a new AI feature, when you have no traces yet. (You can bootstrap error analysis on synthetic data — that's standard.) - When the team's first instinct is to buy an eval platform instead of reading 30 traces. The platform is step four, not step one. --- SDD vs EDD: How the Two Split This is the most common confusion in the field, so here's the clean split: > SDD is for people who are coding and creating applications using coding agents. > EDD is for people who are building AI-powered features as their product. | | SDD | EDD | |---|---|---| | Who uses it | App developers using AI coding assistants | AI engineers building AI-powered products | | What you're verifying | Does the generated code do what the spec says? | Does the AI output meet quality criteria? | | Test type | Deterministic — unit tests, Gherkin, UI assertions | Probabilistic — eval sets, LLM-as-judge scores, regression metrics | | Spec format | Analysis docs, Gherkin scenarios, PRDs | Scoring rubrics, golden input/output pairs, thresholds | | The failing signal | expected button to be visible — FAIL | faithfulness score 0.62 < threshold 0.80 | | Tools | GitHub Spec Kit, OpenSpec, your test framework | LangSmith, Braintrust, RAGAS, Arize Phoenix, W&B Weave | | "Done" means | Component satisfies all spec contracts | Agent output consistently scores above threshold | SDD's failing signal EDD's failing signal ┌───────────────────────────┐ ┌───────────────────────────┐ │ expected button to be │ │ faithfulness score 0.62 │ │ visible — FAIL │ │ < threshold 0.80 │ └───────────────────────────┘ └───────────────────────────┘ deterministic · boolean probabilistic · scored "the spec says visible" "the judge says not faithful" One sentence: SDD verifies that the agent built what you specified. EDD verifies that what you built is actually good. --- When to Use Which: The Decision Guide Stop treating these as competitors. They stack. Here's the map: What are you building / verifying? │ ├─ deterministic code, small change ────────────► TDD │ ├─ business rule, multiple roles in the room ──► BDD │ ├─ "what counts as done?" is ambiguous, ───────► ADD │ stakeholders must sign off │ ├─ new feature / app built by an AI agent ─────► SDD │ ├─ AI / LLM output shipped as a product ───────► EDD │ └─ a real product (most projects) ─────────────► all of them, layered ↓ The reference table | Situation | Start with | Why | |---|---|---| | Bug fix in deterministic logic | TDD | A failing test reproduces the bug and proves the fix | | Auth / billing / payment rules | BDD | Given/When/Then in the domain's own language | | PM + dev + tester must agree on "done" | ADD | The contract is signed before the machine starts | | Greenfield app via Copilot / Cursor / Claude Code | SDD | The spec anchors the agent across sessions | | Chatbot, RAG pipeline, or AI agent | EDD | Probabilistic output — asserts don't apply | | Swapping models (GPT → Claude → whatever) | EDD | Same prompt, different model = different quality | | A screen / API / service you write yourself | TDD (+ BDD if it has domain rules) | Deterministic — unit tests are the right tool | | On-device ML inside a mobile app | EDD | Precision / recall / latency, not assert | | Everything above, in one product | Layer them | See the worked example below | --- One Feature, Five Practices ┌─────────────────────────────────────────────┐ │ SDD — the spec │ intent: what we decided to build ├─────────────────────────────────────────────┤ │ ADD + BDD — the acceptance criteria │ agreement: what "done" means ├─────────────────────────────────────────────┤ │ TDD — the unit tests │ implementation: the code's truth ├─────────────────────────────────────────────┤ │ EDD — the evals (the AI parts only) │ quality: the output's truth └─────────────────────────────────────────────┘ Case 1: You're building a photo organizer with AI tagging: Photo Organizer with AI tagging │ ├─ SDD spec: "albums grouped by date, tile preview, │ AI tags on import, tags editable" ├─ ADD criteria (with the PM): "one album per month; │ a tag can be deleted; suggestions appear within │ 60s for a 100-photo import" ├─ BDD behaviour: timezone grouping, in Given/When/Then — │ exactly where "done" gets ambiguous ├─ TDD code: date logic, tag-edit API, preview pagination — │ red/green/refactor, agent driving the loop └─ EDD AI tagging: collect traces of real imports, read 30, build the taxonomy ("miscategorizes group photos", "hallucinates tags for non-photo files"), one eval per top failure, fix, re-run ### Case 2: Mobile and On-Device ML Mobile is where this gets interesting, because a single app might need *multiple* methodologies at once, applied to different parts of the same codebase. A mobile app (Android / iOS / React Native / Flutter) │ ├─ app code: screens, navigation, business logic │ │ │ ├─ you write it ──────────────► TDD / BDD │ │ (XCTest, Espresso, JUnit) │ │ │ └─ an AI agent writes it ─────► SDD │ (spec first — lifecycle, offline │ sync, and memory rules live IN the │ spec, before the agent touches a file) │ └─ on-device ML feature ──────────────► always EDD (golden set + precision / recall / latency / RAM) **Why EDD is harder on mobile.** On-device ML adds a hardware dimension server-side EDD doesn't have. Your golden dataset must cover not just output quality but: - **RAM footprint** — peak and steady-state across low-end, mid-range, and flagship devices - **Thermal and battery impact** — CPU / GPU / NPU utilisation under sustained load - **Inference latency** — time-to-first-token on *real devices*, not simulators (which are too fast and too uniform) | Platform | ML frameworks | EDD tooling | |---|---|---| | **iOS** | Core ML, Create ML, Apple Foundation Models | Xcode Instruments (Neural Engine, Foundation Models), XCTest assertion harnesses | | **Android** | TensorFlow Lite, MediaPipe, ExecuTorch (NNAPI / GPU delegates) | Android Studio Profiler, custom JUnit eval harnesses against test tensors, Firebase Test Lab | | **React Native / Flutter** | Core ML / NNAPI via platform channels, ONNX Runtime, ExecuTorch | Firebase Test Lab, BrowserStack real devices, host-side harness driving the native runtime | The split never changes, whatever the platform: **the app code follows TDD/BDD or SDD depending on who writes it; the AI feature inside the app is always EDD.** One feature. Five practices. None of them redundant. The spec carried the intent. The acceptance criteria carried the agreement. The behaviours carried the domain rules. The tests carried the code. The evals carried the AI quality. Remove any one and something leaks. The one-line memory aid | You're… | Reach for… | |---|---| | Building code | TDD — tests first | | Stating behaviour | BDD — scenarios in plain English | | Agreeing on "done" | ADD — criteria before code | | Anchoring an agent | SDD — spec first | | Measuring AI output | EDD — error analysis first, evals for what you find | --- The AI-Era Mistakes we tend to do The tools are new, so the failures are new too. 1. Trusting the agent's green light. "The tests passed" — whose tests, run where, by whom? Run the suite yourself. Read the diff. Green means "the tests you have pass." It does not mean "correct." In the agent era, your review of the diff is the review of the agent, not of a colleague. 2. Writing evals for failures you imagined. Hamel's "generally no" applies. If your eval suite was written before the product existed, it measures your expectations, not the product. Error analysis first, always. 3. Chasing 100% eval pass. A perfect score is a signal that your evals are soft. The teams getting value live at 70–85% on hard checks and slowly ratchet the bar. 4. Spec rot. The spec says one thing, the code does another, nobody noticed for three sprints. That's what the converge step exists for. A spec that isn't re-verified is a rumor. 5. Platform before practice. Buying the fancy eval dashboard in week one instead of spending 30 minutes reading traces. The data is the practice. The platform is furniture. 6. TDD theater. Tests written after the code that merely mirror the implementation. That's not TDD, that's a screenshot of the code. The test's job is to state intent — the thing that should be true independent of how the code got there. --- Your Quick Start Five steps if you want to do something this week: 1. You ship AI output? Pick 30 real traces from your system. Read them all. Write down every failure. Group them. That failure taxonomy is worth more than any eval platform. 2. Building something new with an agent? Write the spec before the first prompt. Even one page. Future-you will diff against it. 3. Business rules in the mix? Write the acceptance criteria before implementation — one screen, plain language, reviewed by the person who lives with the feature. 4. Every function, human- or agent-written, gets a test. Red first when you can. When the agent says "done," the suite is your definition of done, not its word. 5. Never merge on an agent's say-so. Run it. Read it. Ship it. That last sentence is the entire AI-era engineering methodology, distilled. --- The Big Picture > Every one of these practices is a response to the same fear: I built it, and it's not what I wanted. TDD answered that fear for functions. BDD answered it for behaviours and shared language. ADD answered it for teams and stakeholders. And when the builders became agents. SDD answered it for intent — what did we actually decide to build? EDD answered it for quality — is the AI output actually good, and how do we know? You don't have to pick one. You don't have to master all five. Pick the one that matches the failure you're most afraid of this week, and run it badly at first. Then run it less badly. The practices compound: every spec you write, every behaviour you articulate, every eval you fix, makes the next build cheaper to verify. Code is cheap now. The scarce resource was never typing — it was knowing. These five practices are all just different languages for the same sentence: > Here's what I meant. Prove it. --- References The sources behind this article, in the order they were used: 1. Martin Fowler, Test Driven Development (updated Dec 2023). The standard summary of Red-Green-Refactor and its benefits. — martinfowler.com 2. Kent Beck, The Canonical TDD Post. Beck's own walkthrough of the TDD loop. — tidyfirst.substack.com 3. Kent Beck, Test-Driven Development: By Example, Addison-Wesley, 2002. The original book. 4. Dan North, Introducing BDD (2006). The canonical essay: behaviour over test, the "should" template, Given/When/Then, ubiquitous language. — dannorth.net 5. Cucumber, BDD documentation. The Discovery / Formulation / Automation structure and Gherkin reference. — cucumber.io 6. BrowserStack, TDD vs BDD vs ATDD: Key Differences. The collaborative, pre-development nature of ATDD's acceptance criteria. — browserstack.com 7. GeeksforGeeks, TDD vs BDD vs ATDD: Key Differences. — geeksforgeeks.org 8. Software Testing Help, How Testers Are Involved in TDD, BDD & ATDD Techniques. — softwaretestinghelp.com 9. Ivan Turkovic, ADD: AI-Driven Development Methodology for Modern Engineers (Jan 2026). Cited for the disambiguation: "ADD" is also used for AI-Driven Development. — ivanturkovic.com 10. GitHub, Spec Kit — the open-source toolkit for spec-driven development with AI coding agents (140k+ stars as of Oct 2026). — github/spec-kit 11. GitHub Spec Kit Documentation — the SDD walkthrough: constitution → specify → plan → tasks → implement → converge. — github.github.com 12. Fission-AI, OpenSpec — a lightweight, open-source spec framework for AI coding agents (73k+ stars); specs as first-class repo artifacts. — Fission-AI/OpenSpec · openspec.dev 13. Hamel Husain & Shreya Shankar, AI Evals: Everything You Need to Know (Evals FAQ, updated Sep 2026). The reference for the EDD loop, error analysis, LLM-as-judge, the "generally no" answer on strict EDD, and the 100%-pass-rate warning. — hamel.dev 14. Hamel Husain, Your AI Product Needs Evals. The practical guide to building domain-specific evaluation systems. — hamel.dev 15. Boming Xia, Qinghua Lu, Liming Zhu, Zhenchang Xing, Dehai Zhao, Hao Zhang, Evaluation-Driven Development and Operations of LLM Agents: A Process Model and Reference Architecture (arXiv:2411.13768). The academic treatment of EDD for LLM agents. — arxiv.org 16. Gergely Orosz & Hamel Husain (The Pragmatic Engineer), A Pragmatic Guide to LLM Evals for Devs (Dec 2025). Industry perspective on evals as an engineering discipline. — newsletter.pragmaticengineer.com 17. Exploding Gradients, RAGAS — open-source evaluation for RAG pipelines. — explodinggradients/ragas
【1分で分かるOSS】 GitHub製「Spec Kit」、AIに書かせる前に仕様を固める ▶ 仕様→計画→タスク→実装の順にMarkdownで整理 ▶ Copilot、Claude、Gemini、Codexなど30のエージェントに対応 ▶ MITライセンスで無料 リポジトリはこちら👇 github/spec-kit #AI #OSS
6 ステップで AI 開発の「？」をなくす。GitHub Spec Kit の仕様駆動開発 #Shorts AI に「作ってください」→「できました」。でも、何人まで使える？ 同時に予約したら？ 頼んでいない所は誰も決めていません。 GitHub Spec Kit は、仕様を先に決めて AI に作らせる「仕様駆動開発」の道具です（画面の予約アプリは流れを見せるための例）。 参考：github/spec-kit ／ github.com/github/spec-kit/blob/main/spec-driven.… ※ナレーションはAI音声（Microsoft Edge 読み上げ）です。 #Shorts #GitHub #SpecKit #仕様駆動開発 #AI開発
367 - GitHub Spec Kit: l'AI scrive codice, ma chi scrive i requisiti? Oggi, grazie all'AI, possiamo scrivere codice sempre più velocemente. Ma cosa succede quando i requisiti sono incompleti o poco chiari? In questa puntata ti parlo di GitHub Spec Kit e di Spec-Driven Development, un approccio che mette le specifiche al centro dello sviluppo software, aiutandoci a lavorare meglio con i coding agent. • github/spec-kit #GitHubSpecKit #SpecDrivenDevelopment #AI #CodingAgents #DotNet #DotNetInPillole #Podcast
仕様駆動開発（SDD）とテスト駆動開発（TDD）の違いを徹底比較：BDD・DDDなど「〇〇駆動開発」もまとめて整理 AIコーディングの広がりとともに、「仕様駆動開発（Spec-Driven Development、SDD）」という言葉をよく聞くようになりました。一方で、昔からある「テスト駆動開発（Test-Driven Development、TDD）」も、AIにコードを書かせる時代に改めて注目されています。 名前が似ていて、どちらも「先に何かを書いてから作る」ので、違いが分かりにくいと感じる人も多いと思います。さらに世の中には、BDD、ATDD、DDD、FDD……と「〇〇駆動開発」がたくさんあります。 この記事では、SDDとTDDの違いを、同じ機能を例にしてできるだけ細かく比べます。そのうえで、ほかの「〇〇駆動開発」も整理し、どう組み合わせればいいかまで解説します。 ! SDDを支えるAIツール（Kiro、GitHubのSpec Kitなど）は、更新がとても速い分野です。この記事は2026年10月時点の公式ドキュメントをもとに書いています。コマンド名などの細部は、使う前に公式ドキュメントを確認してください。 先に結論 仕様駆動開発（SDD） テスト駆動開発（TDD） ひとことで 「何を作るか」を先に文章で決め、人とAIで合意してから作る 「正しく動くか」を先にテストで書き、1歩ずつ作る 最初に書くもの 仕様書（要件・設計・タスク） 失敗するテスト 答える問い 何を、なぜ、どこまで作るか このコードは期待どおりに動くか 1回の単位 機能まるごと（数時間〜数日） 小さな振る舞い1つ（数分） 主な読み手 人とAIの両方（企画・設計・開発） 開発者と、テストを実行する機械 いちばん大事なのは、SDDとTDDは対立するものではないということです。SDDは「何を作るか」を決める手法で、TDDは「決めたものを正しく作る」手法です。担当している範囲が違うので、組み合わせて使えます。 そもそも「駆動」とは何か 「〇〇駆動開発」の「駆動」は、開発を前に進めるきっかけと、迷ったときに立ち返る拠り所が何かを表しています。 テスト駆動なら、テストが次の一手を決め、テストが「正しさ」の基準になる 仕様駆動なら、仕様書が作業を決め、仕様書が「何を作るべきか」の基準になる ドメイン駆動なら、業務（ドメイン）の理解が設計を決める この「何を最初に書き、何を正とするか」という見方で比べると、たくさんある駆動開発の違いが整理しやすくなります。 この記事で使う例題：送料の計算 違いが分かりやすいように、同じ機能を例にします。ネットショップの送料を計算する機能です。 注文の合計金額が5,000円以上なら、送料は無料 5,000円未満なら、送料は全国一律600円 ただし沖縄県への配送は、400円を追加する 合計金額が負の数のときはエラーにする この機能を、TDDとSDDでそれぞれどう作るかを見ていきます。 テスト駆動開発（TDD） 起源と考え方 TDDは、1990年代の終わりに、ケント・ベック（Kent Beck）がエクストリーム・プログラミング（XP）の実践の一つとして広めた手法です。2002年に出た著書『Test-Driven Development: By Example』が原典として知られています（日本語訳は『テスト駆動開発』）。 考え方の中心は、コードを書く前に、そのコードが満たすべきテストを書くことです。そして、ごく小さな歩幅で、次の3つを繰り返します。 Red（レッド）：次に作りたい振る舞いのテストを1つ書く。まだ実装が無いので、テストは失敗する Green（グリーン）：テストが通る最小限のコードを書く Refactor（リファクタリング）：テストが通る状態を保ったまま、コードをきれいにする テストを実行すると、失敗は赤、成功は緑で表示されることが多いので、この名前が付いています。 例題をTDDで作る Node.jsに標準で入っているテストの仕組み（node:test）で、実際に動かした手順を紹介します。 1周目 Red：送料無料のテストを書く // shipping.test.js import { test } from "node:test"; import assert from "node:assert/strict"; import { shippingFee } from "./shipping.js"; test("合計が5,000円以上なら送料は0円", () => { assert.equal(shippingFee({ total: 5000, prefecture: "東京都" }), 0); }); 関数の中身はまだ空なので、テストは失敗します。 ✖ 合計が5,000円以上なら送料は0円 ここで「失敗することを確かめる」のが大事です。最初から成功するテストは、何も確かめていない可能性があるからです。 1周目 Green：とにかく通す // shipping.js export function shippingFee(order) { return 0; } 「常に0を返す」は、明らかに手抜きです。でも、TDDではこれで正解です。今あるテストを通す最小限のコードだけを書き、足りない部分は次のテストで明らかにします。 ✔ 合計が5,000円以上なら送料は0円 2周目：5,000円未満のテストを足す test("合計が5,000円未満なら送料は600円", () => { assert.equal(shippingFee({ total: 4999, prefecture: "東京都" }), 600); }); 「常に0」では通らないので、ここで初めて条件分岐が必要になります。 export function shippingFee(order) { if (order.total >= 5000) return 0; return 600; } 境目の4,999円をテストに使っているのがポイントです。境目の値（境界値）は、バグが一番起きやすい場所です。 3周目：沖縄県のテストを足し、そのあとリファクタリング test("沖縄県への5,000円未満の注文は送料1,000円", () => { assert.equal(shippingFee({ total: 3000, prefecture: "沖縄県" }), 1000); }); まずは最小限で通します。 export function shippingFee(order) { if (order.total >= 5000) return 0; if (order.prefecture === "沖縄県") return 1000; return 600; } テストが全部通ったら、リファクタリングです。「1000」がどこから来た数字なのか分かりにくいので、意味のある名前を付けます。 const FREE_SHIPPING_THRESHOLD = 5000; // 送料無料になる合計金額 const BASE_FEE = 600; // 全国一律の送料 const REMOTE_SURCHARGE = 400; // 遠方への追加料金 const REMOTE_PREFECTURES = new Set(["沖縄県"]); export function shippingFee({ total, prefecture }) { if (total >= FREE_SHIPPING_THRESHOLD) return 0; const surcharge = REMOTE_PREFECTURES.has(prefecture) ? REMOTE_SURCHARGE : 0; return BASE_FEE + surcharge; } 形は大きく変わりましたが、テストは全部通ったままです。これが「テストがあるから、安心して書き直せる」というTDDの強みです。 4周目：エラーのテストを足す test("合計が負の数ならエラーになる", () => { assert.throws(() => shippingFee({ total: -1, prefecture: "東京都" }), RangeError); }); 失敗を確かめてから、関数の先頭に1行足します。 if (total < 0) throw new RangeError("合計金額が負の数です"); ✔ 合計が5,000円以上なら送料は0円 ✔ 合計が5,000円未満なら送料は600円 ✔ 沖縄県への5,000円未満の注文は送料1,000円 ✔ 合計が負の数ならエラーになる 4つの振る舞いを、テストという形で1つずつ確かめながら作れました。 TDDの3つのルール TDDを実践するうえで、よく言われる約束があります。 失敗するテストが無いうちは、本番のコードを書かない 一度に足すテストは1つだけ テストを通すのに必要な分だけ、コードを書く 歩幅を小さく保つことで、失敗したときに「何が原因か」がすぐ分かります。 TDDのよくある誤解 「テストを先に全部書くこと」ではない TDDは、テストを1つ書いては実装する、の繰り返しです。最初に全テストを書き切るのは、TDDとは別のやり方です。 「テストのための手法」ではない TDDで作られたテストは、結果として品質を守ってくれます。ただ、本来の目的は「小さな歩幅で設計を進めること」です。テストを先に書くと、「この関数はどう呼ばれたら使いやすいか」を、使う側の目線で先に考えることになります。 リファクタリングを飛ばしがち マーチン・ファウラー（Martin Fowler）は、TDDの一番よくある失敗として「3つ目のステップ（リファクタリング）を飛ばすこと」を挙げています。テストは通るけれど読みにくいコードが溜まっていきます。 TDDの向き・不向き 向いている 向いていない（工夫が必要） 計算や判定など、入力と出力がはっきりしたロジック 画面の見た目、デザインの細部 バグを直すとき（まずバグを再現するテストを書く） 何を作るか自体が決まっていない探索的な試作 長く保守するコード 外部サービスに強く依存する部分（差し替えの工夫が必要） 仕様駆動開発（SDD） 「仕様駆動」には2つの意味がある 「仕様駆動開発」という言葉は、文脈によって指すものが違うので注意が必要です。 昔からの意味：仕様を先に書いてから作る、という一般的な考え方。形式的な仕様記述や、後で紹介する「契約による設計」も、仕様を中心にした開発の一種です。 最近の意味（AI時代のSDD）：AIコーディングエージェントに作業させる前に、要件・設計・タスクを文章で書いて人とAIで合意し、それに沿ってAIに実装させるやり方。 この記事でSDDと呼ぶのは、主に2つ目です。 なぜ今SDDなのか 会話型のAIに「〇〇を作って」と頼むと、AIはそれらしいコードをすぐ出してくれます。ところが、頼んだ側の頭の中にある前提（対象範囲、例外のとき、制約）が伝わっていないと、AIは推測で穴を埋めます。いわゆる「雰囲気で書いてもらう（vibe coding）」状態です。 SDDは、この推測を減らすために、作る前に「何を作るか」を文章にして固定するやり方です。シリーズの記事で「AIの答えがぶれるのはinputが足りないサイン」と書きましたが、SDDはそのinputを最初にそろえる仕組みだと言えます。 SDDの流れ ツールによって細部は違いますが、流れはおおむね共通です。 要件（Requirements）：誰が、何をしたいのか。受け入れ基準（どうなれば完成か） 設計（Design）：どう作るか。構成、データの形、処理の流れ タスク（Tasks）：実装を小さな作業に分けた一覧 実装（Implement）：タスクを1つずつAIに実装させ、人がレビューする それぞれの段階で人が内容を確認し、合意してから次へ進むのがポイントです。 代表的なツール Kiro AWSが提供する開発環境です。仕様（Spec）を作ると、requirements.md（要件と受け入れ基準）、design.md（構成・シーケンス図・実装方針）、tasks.md（追跡できる実装計画）の3つのファイルができます。要件の書き方には、後で紹介するEARS記法を使います。 GitHub Spec Kit GitHubが公開しているオープンソースのツールキットです。プロジェクト全体の原則を決める「憲法（constitution）」を最初に作り、そのあと仕様、計画、タスク、実装と進めます。執筆時点のREADMEでは、各段階を /speckit-constitution、/speckit-specify、/speckit-plan、/speckit-tasks、/speckit-implement、/speckit-converge のように呼び出す形になっています（コマンドの名前は版によって変わってきたので、使う前に確認してください）。 EARS記法：要件を「テストできる文章」にする SDDで要件を書くときに役立つのが、EARS（Easy Approach to Requirements Syntax）という書き方です。決まった型に当てはめて書くことで、あいまいさを減らします。主な型は次のとおりです。 型 書き方 使う場面 常に THE SYSTEM SHALL 〜 いつでも成り立つこと イベント WHEN 〜 THE SYSTEM SHALL 〜 何かが起きたとき 状態 WHILE 〜 THE SYSTEM SHALL 〜 ある状態の間 望ましくない状況 IF 〜 THEN THE SYSTEM SHALL 〜 エラーや異常のとき オプション WHERE 〜 THE SYSTEM SHALL 〜 ある機能があるとき 例題の送料計算を、EARSで要件にするとこうなります。 要件：送料の計算 ユーザーストーリー 購入者として、注文を確定する前に送料を知りたい。 それによって、送料無料まであといくら買えばよいか判断できるようにしたい。 受け入れ基準 1. WHEN 注文の合計金額が5,000円以上である THE SYSTEM SHALL 送料を0円にする 2. WHEN 注文の合計金額が5,000円未満である THE SYSTEM SHALL 送料を600円にする 3. WHEN 合計金額が5,000円未満で、配送先が沖縄県である THE SYSTEM SHALL 送料に400円を加える 4. IF 注文の合計金額が負の数である THEN THE SYSTEM SHALL 注文を受け付けずエラーを返す 決まっていないこと - 離島（沖縄県以外）の扱い - 送料の消費税の表示方法 最後の「決まっていないこと」がとても大事です。SDDの価値の半分は、作る前に、決まっていないことに気づけることにあります。TDDの例では、離島の扱いは誰にも問われないまま実装が進んでいました。 AIに仕様を書かせるときのプロンプト ツールを使わなくても、SDDの考え方はAIへの頼み方に取り入れられます。 送料を計算する機能を作りたいです。いきなり実装せず、まず requirements.md を書いてください。受け入れ基準はEARS記法（WHEN / IF 〜 THE SYSTEM SHALL 〜）で書き、決まっていないことは推測で埋めずに「決まっていないこと」として一覧にしてください。私が確認してから設計に進みます。 「推測で埋めずに一覧にして」と「確認してから進む」がポイントです。 SDDの3つのレベル マーチン・ファウラーのサイトに掲載された、ビルギッタ・ベッケラー（Birgitta Böckeler）による記事では、SDDを仕様の扱い方で3つのレベルに分けています。 レベル 仕様の扱い spec-first 作る前に仕様を書く。作り終えたら仕様は使わない spec-anchored 作り終えたあとも仕様を残し、その後の改修や保守でも使い続ける spec-as-source 仕様が主なソース。人は仕様だけを編集し、コードには手を触れない 同じ記事では、Kiroは spec-first 寄り、Spec Kitも実態は spec-first 寄りと分析しています。一方、Tesslというツールは、spec-anchored や spec-as-source を目指しているそうです。 SDDの課題 SDDは万能ではありません。先ほどの記事では、次のような課題も指摘されています。 レビューの負担：ツールが大量のMarkdownを作るため、読むのが大変。筆者は「これだけのMarkdownを読むより、コードをレビューしたい」とまで書いています。 AIが仕様を守るとは限らない：仕様やチェックリストを用意しても、AIが指示を無視したり、同じコードを重複して作ったりすることがあった、と報告されています。 モデル駆動開発（MDD）の失敗の繰り返しになる恐れ：仕様から全部を作ろうとすると、かつてのモデル駆動開発と同じ「柔軟性のなさ」に、AIの「出力が毎回変わる」性質が加わる、と警告しています。 つまり、仕様を書いても、出てきたものが仕様どおりかを確かめる仕組みは別に必要です。ここでTDDの出番になります。 SDDとTDDを細かく比べる 観点 仕様駆動開発（SDD） テスト駆動開発（TDD） 目的 何を作るかの認識をそろえる 作ったものが正しく動くことを確かめながら作る 最初に書くもの 要件・設計・タスクの文書 失敗するテスト1つ 正（拠り所） 仕様書 テスト 書く言葉 自然言語（EARSなどの型で半構造化） プログラミング言語 判定 人とAIが読んで判断する（あいまいさが残る） 機械が実行して判定する（成功か失敗か） 粒度 機能・ユーザーストーリー単位 関数・振る舞い単位 サイクルの長さ 数時間〜数日 数分 関わる人 企画、設計者、開発者、AI 主に開発者（とAI） 見つけやすい問題 抜けている要件、決まっていないこと、認識のずれ 実装のバグ、境界値の誤り、変更による壊れ 見つけにくい問題 実装のバグ（読むだけでは分からない） そもそも作るものが間違っていること AIとの関係 AIへの入力をそろえる AIの出力を機械で確かめる 生まれた時期 考え方は昔から。AI時代の手法としては2025年ごろから広まる 1990年代末〜2000年代初め よくある失敗 文書が増えすぎて誰も読まない テストが実装の後追いになる 表の「見つけやすい問題」と「見つけにくい問題」を見ると、お互いの弱点をお互いが補っていることが分かります。 SDDとTDDを組み合わせる 組み合わせ方は、とてもシンプルです。仕様の受け入れ基準を、そのままテストにするのです。 受け入れ基準（SDD） テスト（TDD） 1. 5,000円以上なら送料0円 合計が5,000円以上なら送料は0円 2. 5,000円未満なら送料600円 合計が5,000円未満なら送料は600円 3. 沖縄県は400円を加える 沖縄県への5,000円未満の注文は送料1,000円 4. 負の数はエラー 合計が負の数ならエラーになる EARSで書いた受け入れ基準は「〜のとき、〜する」という形なので、1つの基準がそのまま1つのテストになります。 流れ SDD：要件をEARSで書き、決まっていないことを洗い出して、人が確認する SDD：設計とタスクに分ける TDD：タスクごとに、受け入れ基準をテストにして、失敗することを確かめる TDD：テストが通るように実装し、リファクタリングする 確認：すべての受け入れ基準に、対応するテストがあるかを確かめる 5番目の「対応しているか」は、人の目だけだと漏れやすいところです。要件・実装・テストの対応表を作って、機械で確かめる方法もあります。たとえば私が公開している ai-coding では、要件ごとに実装とテストの場所を表に書き、テストが実在してアサーションがあることをCIで確かめています。 AIエージェントにTDDをさせるときのプロンプト AIに実装を任せるときも、TDDの順番を守らせると品質が安定します。 requirements.md の受け入れ基準1〜4を、1つずつTDDで実装してください。基準ごとに、先にテストを書いて失敗することを確かめ、そのあと最小限の実装でテストを通してください。テストの期待値は受け入れ基準から決め、実装に合わせて書き換えないでください。全部通ったら、テストが通るのを保ったままリファクタリングしてください。 最後の「期待値を実装に合わせて書き換えない」が特に大事です。AIはテストを通すために、テストの方を直してしまうことがあるからです。 ほかの「〇〇駆動開発」 振る舞い駆動開発（BDD：Behavior-Driven Development） TDDから派生した手法で、ダニエル・テルホルスト＝ノース（Daniel Terhorst-North）とクリス・マッツ（Chris Matts）が広めた「Given-When-Then」の書き方で知られます。TDDを教える中で「何をテストすればいいのか分からない」という混乱が多かったことから、「テスト」ではなく振る舞い（behavior）という言葉を使い、それを業務の言葉で書くことを重視します。 Feature: 送料の計算 Scenario: 送料無料のライン Given カートの合計金額が 5000 円である And 配送先が 東京都 である When 送料を計算する Then 送料は 0 円になる この書き方はGherkinと呼ばれ、Cucumberなどのツールで、そのまま自動テストとして実行できます。SDDの受け入れ基準と、TDDのテストの、ちょうど中間にある手法と考えると分かりやすいです。 受け入れテスト駆動開発（ATDD：Acceptance Test-Driven Development） 開発を始める前に、顧客や企画の人と一緒に受け入れテスト（何ができたら完成か）を決め、それを満たすように開発する手法です。TDDが「開発者の小さなテスト」から始めるのに対し、ATDDは「利用者から見た完成の条件」から始めます。BDDとよく似ていて、実例で仕様を書く「実例による仕様（Specification by Example）」とも深い関係があります。 ドメイン駆動設計（DDD：Domain-Driven Design） エリック・エヴァンス（Eric Evans）が2003年の著書で体系化した考え方です。名前は「設計（Design）」で、開発の手順というより設計の考え方です。 ユビキタス言語：業務の専門家と開発者が同じ言葉を使い、その言葉をコードにもそのまま使う 境界づけられたコンテキスト：大きな業務を、言葉の意味が一貫する範囲ごとに分ける たとえば「会員」という言葉が、販売の部署と経理の部署で違う意味を持つなら、無理に1つにまとめず、別のコンテキストとして扱います。SDDで仕様を書くときにも、この「言葉をそろえる」考え方はそのまま役に立ちます。 機能駆動開発（FDD：Feature-Driven Development） ジェフ・デ・ルカ（Jeff De Luca）が、1997年にシンガポールの銀行の大規模なプロジェクトのために考えた手法です。次の5つの活動で進めます。 全体のモデルを作る 機能の一覧を作る 機能ごとに計画する 機能ごとに設計する 機能ごとに作る 利用者にとって価値のある小さな「機能」を単位に計画と進捗を管理するのが特徴です。 モデル駆動開発（MDD：Model-Driven Development） UMLなどのモデル（図や形式的な定義）を正とし、そこからコードを自動生成する考え方です。2001年に業界団体のOMGが、MDA（Model-Driven Architecture）という枠組みを打ち出しました。考え方としては今のSDDの「spec-as-source」に近く、モデルとコードの食い違いや、柔軟性のなさといった、当時の課題が今も参考になります。 契約による設計（DbC：Design by Contract） バートランド・メイヤー（Bertrand Meyer）が、プログラミング言語Eiffelの設計とともに、1986年ごろから提唱した考え方です。関数ごとに3つの約束を決めます。 事前条件：呼び出す側が守ること（例：合計金額は0以上） 事後条件：関数が保証すること（例：送料は0以上） 不変条件：常に成り立つこと 例題の「負の数ならエラー」は、事前条件をチェックしていることになります。 型駆動開発（Type-Driven Development） 先に型（データの形や、関数が受け取るもの・返すもの）を決め、型に導かれるように実装する考え方です。型で表せる制約が多い言語ほど効果が大きく、「ありえない状態を型で表せないようにする」ことで、バグの入る余地を減らします。 スキーマ駆動・API駆動（Contract-First / API-First） APIを作るとき、先にOpenAPIなどでAPIの定義（スキーマ）を書き、それを正として、サーバーとクライアントを並行して作るやり方です。定義からコードや型、テスト用のモックを生成できるので、チーム間の食い違いを減らせます。 名前が似ているけれど、開発手法ではないもの イベント駆動（Event-Driven）やデータ駆動（Data-Driven）も「駆動」と付きますが、多くの場合は開発の進め方ではありません。 イベント駆動アーキテクチャ：何かが起きた（イベント）ことをきっかけに処理が動く、システムの作り方 データ駆動：データにもとづいて判断する、意思決定の考え方 「〇〇駆動」と聞いたら、それが開発の進め方なのか、システムの作り方なのかを区別すると混乱しません。 一覧で比べる 名前 最初に書くもの 正（拠り所） 主な単位 主な読み手 SDD 要件・設計・タスク 仕様書 機能 人とAI TDD 失敗するテスト テスト 小さな振る舞い 開発者 BDD Given-When-Thenのシナリオ 振る舞いの記述 シナリオ 業務担当と開発者 ATDD 受け入れテスト 受け入れテスト ユーザーストーリー 顧客と開発者 DDD ドメインモデルと共通の言葉 ドメインモデル コンテキスト 業務の専門家と開発者 FDD 機能の一覧 機能の一覧 機能 管理者と開発者 MDD モデル モデル システム 設計者 DbC 事前・事後条件 契約 関数 開発者 スキーマ駆動 API定義 API定義 API 複数のチーム どう選ぶか 状況 おすすめ AIに機能をまるごと作らせたい SDDで仕様をそろえ、実装はTDDの順番で 計算や判定のロジックを書く TDD バグを直す TDD（まずバグを再現するテストを書く） 企画や業務の人と完成の条件を合わせたい BDD・ATDD 業務が複雑で、言葉の意味が人によって違う DDD 複数のチームでAPIをやり取りする スキーマ駆動 まず作ってみないと分からない試作 無理に駆動開発をしない。方向が決まってから仕様やテストを整える 1つに決める必要はありません。実際の開発では、DDDで言葉をそろえ、SDDで仕様を決め、BDDで受け入れ基準を書き、TDDで実装する、というように重ねて使うことがよくあります。 よくある失敗 SDDで文書を書きすぎる 要件・設計・タスクを細かく書くほど、読む人の負担が増えます。読まれない仕様は、無いのと同じです。まずは受け入れ基準と「決まっていないこと」だけでも十分に価値があります。 TDDのテストが、実装の後追いになる 実装を書いてから、その動きに合わせてテストを書くと、テストは「今の動き」を写しただけになります。AIに書かせるときは特に、期待値は仕様から決め、実装に合わせないよう指示しましょう。 仕様とテストが別々に育つ 仕様を直したのにテストが古いまま、またはその逆、ということが起きがちです。受け入れ基準とテストを対応させ、どちらかを変えたらもう片方も見直す運用にします。 「〇〇駆動」の名前にこだわりすぎる 手法は目的ではなく道具です。チームが抱えている問題（認識のずれなのか、バグなのか、言葉の混乱なのか）に合わせて選びましょう。 まとめ SDDは「何を作るか」を先に文章で決め、人とAIの認識をそろえる手法 TDDは「正しく動くか」を先にテストで書き、小さな歩幅で作る手法 SDDは作るものの間違いに強く、TDDは実装の間違いに強い。だから組み合わせると強い 組み合わせるコツは、受け入れ基準をそのままテストにすること AIがコードを書く時代になっても、「何を作るか決める」と「正しく作れたか確かめる」は人の仕事として残ります。SDDとTDDは、その2つをAIと一緒に進めるための、心強い道具です。 参考 Test Driven Development（Martin Fowler） Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl（Birgitta Böckeler / martinfowler.com） github/spec-kit Kiro: Specs Kiro: Feature Specs（EARS記法） Given When Then（Martin Fowler） Behavior-driven development（Wikipedia） Domain Driven Design（Martin Fowler） Feature-driven development（Wikipedia） Model-driven architecture（Wikipedia） Design by contract（Wikipedia）
GitHub Spec Kit: 3 Ways Specs Evolve What happens to your spec.md, plan.md and tasks.md after the feature ships and the requirement changes? GitHub Spec Kit's docs name three answers, flow-back, flow-forward and living spec, and pick none. We explain each one, section by section from the official docs, on a real API change. For developers and teams using Spec Kit, or deciding how to keep specs true after the first version. What you'll learn - The two separate questions: how long a spec should matter, and what happens to the documents after delivery - What all three models share (the same delivery loop; no automatic reconciliation; no default) - Flow-back, flow-forward and living spec: when each fits, and each one's main risk, in the docs' words - The docs' comparison table and two questions to choose a model for your team Chapters 0:00 What happens to your spec after you ship? 0:22 The setup: spec-driven development and our example 1:39 Two separate questions 2:25 Same delivery, different upkeep 3:11 Flow-back spec 4:27 Flow-forward spec 5:42 Living spec 6:48 Flow-back vs flow-forward vs living spec 7:26 How to choose a model 8:14 Coming up: we ran all three Code techshippedstudio-glitch/bookmarks-api - Starting point for the change: tag ep03-start - Flow-forward example (folder 002): branch ep03/forward-r3 - Living spec example (spec.md first): branch ep03/living-r2, tag ep03-living-r2-spec - Run results and the race check: branch ep03/results (episodes/ep03/). The repo also keeps two earlier flow-forward runs made without the guide's analyze step (ep03/forward-r1, ep03/forward-r2), labelled there; the video counts the two by-the-guide runs per model. Versions: GitHub Spec Kit 1.2.2 · FastAPI · PostgreSQL Cost and time: the measured runs (time, tokens, tests) are in ep03/results and come in the next episodes of this series. References - Spec Persistence Models (Spec Kit docs, v1.2.2): github.com/github/spec-kit/blob/v1.2.2/docs/conce… - Evolving Specs in Existing Projects (Spec Kit guide, v1.2.2): github.com/github/spec-kit/blob/v1.2.2/docs/guide… - GitHub Spec Kit: github/spec-kit Playlist: GitHub Spec Kit: When Requirements Change (this is episode 1) Narration: AI voice. #SpecDrivenDevelopment #GitHubSpecKit #SoftwareEngineering
spec 駆動開発のツールはまだマスター設計を考えていない：機能ごとの設計書が作った端から枯れていく AI に実装させる前に、機能ごとの設計ディレクトリ（要件・設計・タスク）を repo に置く。spec-kit や Kiro が広めたこの形は、2026 年 10 月時点でほぼ定番になった。 ところが、この形には「今のシステム全体の設計はどこにあるか」に答える場所が無い。設計書は機能ごと、変更ごとに作られ、merge されるたびに増えていく。それらを畳み込んだマスター設計、つまり「今の仕様はこれ」と言える 1 つの文書を、spec-kit も Kiro も持たない。AI は次の作業で、溜まった設計ディレクトリのどれかを今の仕様として読む。 知りたいこと 結論 根拠 なぜマスターが要るのか 機能ごとの設計書は差分の説明でしかない。差分を積んでも今の仕様にはならない 構造からの説明 今のツールはマスターを持っているか spec-kit と Kiro は持たない。持つのは OpenSpec だけで、それも変更提案を通らないコード変更はマスターに戻らない 公式ドキュメント、spec-kit の issue #620・#4940 どの repo に置くか どのツールも、既定では設計書をコードと同じ repo に置く。機密と読み手の違いを考えると、設計は専用の repo に分ける判断になる 構造からの説明、OpenSpec の Stores 自分たちで持つには 設計 repo に提案とマスターを置き、コードの PR から ID で参照させる 設計の提案 2026 年 10 月時点の主なツールを並べると、次のとおりである。 ツール 機能ごとの設計書 マスター設計 コードの変更がマスターに戻るか 設計を別の repo に置くには spec-kit specs/NNN-name/ 無い。維持の方式は「チームの選択」 戻す core コマンドは not planned プロジェクトはディレクトリ単位。別 repo の間は版付きの成果物か同期したコピーで、と案内するだけ Kiro spec ごとに requirements・design・tasks 無い。steering は前提の説明 手順なし multi-root workspace で、別フォルダの .kiro/ の spec も一覧に並ぶ OpenSpec openspec/changes/<名前>/ openspec/specs/ 変更提案を通ったものだけ Stores（ベータ）で設計専用の repo を持てる。同期はツールの外 機能ごとの設計書は「その時点の差分の説明」 機能ごとの設計ディレクトリに書かれているのは、「今の状態から、この機能でこう変える」という差分の説明である。merge した時点で、その差分はコードに入り、役目を終える。 差分を何本積んでも、今の仕様にはならない。たとえば、001 でメールとパスワードのログインを作り、9 か月後の 009 で二段階認証を足したとする。今のログインの仕様を知るには、001 と 009 を両方読んで頭の中で合成しなければならない。その間にレビューの手直しや障害対応でコードだけ変わっていれば、どちらの設計書にも書かれていない。 人間なら、古い設計書を「経緯の記録」として読み流せる。AI はそうはいかない。repo に specs/001-login/spec.md があれば、それを今の仕様として読み、その前提でコードを書く。 設計書を artifact や Wiki ではなく repo に置けば、「コードと同じ PR で直せる」「履歴が残る」「AI がファイルとして読める」は手に入る。ただ、機能ごとの設計書が溜まるだけなら、AI が古い設計を正として読む事故は、置き場所を変える前と同じ形で起きる。要るのは置き場所ではなく、マスターである。 spec-kit：マスターは「チームの選択」 spec-kit の成果物は、機能ごとの specs/NNN-name/（spec.md、plan.md、tasks.md など）と、全体の原則を書く constitution.md である。constitution はテストの方針や設計原則を書く場所で、システムが今どう振る舞うかを書く場所ではない。 全体の今の仕様を持ちたい、という声は早くから出ている。2025 年 9 月に立った issue #620 は、まさに先の 001 と 009 の例を挙げて「仕様を時間とともに統合する推奨のやり方はあるか」と尋ねている。2026 年 10 月時点でも open のまま、「全体の今の定義を 1 か所で持ちたい」というコメントが続いている。 公式ドキュメントの答えは、Spec Persistence Models にある。配信後の設計書の扱いを flow-forward（完了した設計書は履歴として残し、変更は新しいディレクトリで行う）、living spec（機能の spec.md を契約として更新し続ける）、flow-back（実装で得た発見を設計書に戻す）の 3 つに分け、こう書いている。 None is the default, and none is required by Spec Kit. living spec でも、更新し続けるのは機能ごとの spec.md である。機能をまたいで今の仕様を 1 つにまとめる場所は、どの方式にも無い。 2026 年 10 月 13 日には、実装との食い違いのうち「コードが正しい」ものを spec と plan に書き戻す core コマンドの提案（#4940）が出た。これは同じ日に not planned で閉じられた。メンテナの説明は「配信と、配信後の維持は別物である。維持の方式はチームが選ぶもので、core がコマンドを用意する約束はしない」というものだった。 一方で、設計思想を書いた spec-driven.md にはこうある。 Specifications stay in sync with code because they generate it spec がコードを生成するので同期は保たれる、という主張である。これは機能ごとの spec と、そこから生成したコードの間の話で、マスターの話ではない。「同期する」という言葉が、全体の今の仕様はどこにあるかという問いを見えなくしている。 コミュニティには、merge 後に機能の設計を中央の .specify/memory/spec.md に畳み込む archive 拡張がある。マスターを欲しがる人が自作している、というのが 2026 年 10 月時点の状態である。 Kiro：steering は設計ではない Kiro の設計書も spec ごとに作られる。1 つの spec が requirements.md（または bugfix.md）、design.md、tasks.md を持つ。 全体の文脈として、Kiro には .kiro/steering/ がある。標準の 3 ファイルは次のとおり。 product.md：製品の目的、対象ユーザー、主な機能、事業の目標 tech.md：フレームワーク、ライブラリ、開発ツール、技術的な制約 structure.md：ファイル構成、命名規則、import の書き方、アーキテクチャ上の判断 どれも、AI にプロジェクトの前提を伝えるためのものである。「ログインは今どう振る舞うか」を書く場所ではない。 発表記事（2025 年 7 月 14 日）は「Kiro's specs stay synced with your evolving codebase.」と書いている。公式ドキュメントで同期の手段として挙がっている Sync Files は、設計を直したあとにタスクを作り直すことと、実装済みのタスクに完了の印を付けることをする。どちらも 1 つの spec の中の話で、spec をまたいで今の仕様をまとめる機能ではない。 唯一：OpenSpec はマスターを持っている OpenSpec は、マスターを最初から設計に入れている。spec-kit の #620 にも「それがまさに OpenSpec の売りだ」というコメントが付いている。 openspec/specs/ を source of truth（今の振る舞い）とする。 変更は openspec/changes/<名前>/ に提案として置く。spec には差分（ADDED / MODIFIED / REMOVED）だけを書く。 /opsx:archive で差分をマスターに merge し、提案は changes/archive/ に凍結する。 「変更提案は凍結し、今の仕様は 1 つだけ更新し続ける」という分け方で、RFC や ADR を運用してきたプロセスと同じ構造である。 ただし、マスターが更新されるのは、変更提案を通ったときだけである。手でコードを直したときは「archive の前に揃える」と FAQ にある。食い違いを見つける /opsx:verify は任意で、Verify won't block archive と明記されている。verify の対象は 1 つの change で、change を作らずに直したコード（レビュー後の手直し、障害対応、リファクタリング）を、マスターと突き合わせる仕組みは無い。 設計の repo をコードの repo から分ける マスターをどこに置くか。spec-kit は specs/、Kiro は .kiro/、OpenSpec は openspec/ と、どのツールも、既定では設計書をコードと同じ repo に置く。同じ PR でコードと設計を直せるので、ずれを防ぐには一番強い置き方に見える。 しかし、設計をコードの repo に置くと決める前に、2 つの点で設計 repo を分ける判断が要る。 機密：読める範囲は repo 単位でしか切れない 設計の背景には、コードの repo に入れられないものが混ざる。 特定の顧客の要望、契約条件、障害の相手先 料金や取引の事情、まだ公表していない計画 個人情報を含む問い合わせの中身 GitHub の読み取り権限は repo 単位である。「この repo のコードは読めるが、specs/ の下は読めない」という設定はできない。コードの repo に設計を置いた時点で、その repo を読める全員、つまり開発者全員、外部の協力者、CI、AI エージェントが背景まで読む。エージェントは読んだものを、コード、コメント、コミットメッセージ、PR 本文に書き出しうる。 背景を書かせないと、設計書は「AI は issue の背景を知らない」という元の問題に戻る。背景を書かせて、読める範囲を絞りたいなら、設計を別の repo に置くしかない。 読み手：設計を承認する人はコードの repo にいない 設計を「これで合っている」と承認するのは、PdM や顧客の窓口であることが多い。この人たちは、コードの repo に入る必要がない。設計がコードの repo にあると、承認のためだけにコードの読み取り権限を渡すことになる。 spec-kit は、この読み手の違いには気づいている。/speckit.specify の指示には、spec.md は「何を・なぜ」に絞り、開発者ではなく事業側の関係者に向けて書く、とある。ただ、その spec.md はコードの repo の中にある。事業側の関係者が読むには、コードの repo の権限が要る。 画面も同じである。人が意図を確かめるのは、文章より画面の画像である。merge 時点の画面を画像で固定して設計に添えると、コードの repo の履歴に画像が積み上がっていく。設計の repo なら、そこは気にしなくてよい。 分けると何を失うか 分けると、「同じ PR でコードと設計を直せる」が消える。2 つの repo は別々に merge されるので、何もしなければ、設計を artifact や Wiki に置いていたときと同じ形でずれる。分けるなら、このずれを塞ぐ仕組みを先に用意する必要がある。 Kiro は multi-root workspace で、複数のフォルダの .kiro/ にある spec を 1 つの一覧に並べて読める。設計用のフォルダを別に開いておく使い方はできるが、両者をつなぐ仕組みは無い。設計専用の repo を正面から扱っているのは、OpenSpec の Stores（2026 年 10 月時点でベータ）だけである。ドキュメントの説明は「planning in its own repo」で、複数の repo にまたがる機能や、要件を持つチームと使うチームが違う場合を動機に挙げている。機密や承認者の範囲は動機に入っていない。そして、2 つの repo の同期はツールの仕事ではないと明記している。 OpenSpec never clones, syncs, or pushes anything on its own. マスターから設計する 2026 年 10 月時点のツールがマスターも repo の分け方も考えていない以上、チームが先に決めるしかない。順番は、機能ごとの設計書の書式より先に、マスターをどの repo に置くかである。 1. 設計 repo を作り、変更提案とマスターをそこに置く。 issue ごとの提案（背景・設計・手順）と、今の仕様を書くマスターを、同じ設計 repo に置く。読み取り権限は、背景を読んでよい人に絞る。PdM や顧客の窓口は、この repo だけに入れる。画面は merge 時点の画像で固定し、ここに置く。 2. 提案は merge の時点でマスターに反映し、凍結する。 AI への指示（CLAUDE.md や AGENTS.md）に「今の仕様はマスターを読む。提案は経緯として読む」と書けば、エージェントの読み方が一意に決まる。マスターの記述が変わらない小さい修正には、提案を要求しない。 3. コードの PR から、設計 repo を ID で参照させる。 同じ PR で直せない分は、CI で塞ぐ。コードの repo の PR には、次のどちらかを求める。 設計 repo の提案の ID を書く。CI は、その提案が承認済みかを確かめる。 PR 本文で「仕様は変わらない」と宣言する。 逆向きも見る。設計 repo の提案を凍結するときは、対応するコードの PR が merge 済みかを確かめる。提案を通らないコード変更がマスターに戻らない問題は、ツールの中だけで閉じている OpenSpec でも残っている。repo を分けるなら、この往復の検査が無いと必ずずれる。 4. AI には作業ごとに必要な分だけ渡す。 コードの repo で動くエージェントに、設計 repo 全体を読ませない。その作業の提案と、マスターの該当箇所だけを渡す。背景のうちコードに書き出してはいけないものは、提案の中で分けておく。 spec 駆動のツールは、1 つの機能を書き始めるまでを速くした。機能が積み上がったあとに「今の仕様はどこか」に答えること、そして「設計を誰に読ませるか」を決めることは、まだツールの仕事になっていない。設計を repo で持つと決めたら、どの repo に置くかと、コードの repo とをつなぐ検査も一緒に決める必要がある。 参考 github/spec-kit: spec-driven.md github/spec-kit: Spec Persistence Models github/spec-kit: Evolving Specs in Existing Projects github/spec-kit: Using Spec Kit in a Monorepo github/spec-kit #620: How to keep specs consistent and up-to-date with spec-kit? github/spec-kit #4940: Core flow-back step for drift where the code is ahead of the spec github/spec-kit Discussion #1804: How do you keep your spec files canonical? Introducing Kiro Kiro: Steering Kiro: Specs best practices Kiro: Multi-root workspaces OpenSpec: Concepts OpenSpec: FAQ OpenSpec: Stores: Plan in Its Own Repo