---
title: "Spec-Driven Development: Write the Spec Before Letting AI Build"
url: https://www.thinnd.site/en/engineering/spec-driven-development-write-the-spec-first/
language: en
author: "Nhu Duy Thin (Thinnd)"
published: 2026-10-29
updated: 2026-10-29
section: "Engineering"
tags: ["spec-driven development", "specification", "AI agent", "workflow", "Spec Kit", "Kiro"]
summary: "Spec-driven development means writing the desired behavior of a feature first, then letting AI build from it. Martin Fowler describes three levels: write the spec first and possibly discard it (spec-first), keep the spec for maintenance (spec-anchored), and treat the spec as the main source with code as a generated product (spec-as-source). He also lists practical limits: one heavy workflow for small tasks, many repetitive files that are hard to review, and agents that sometimes ignore the spec. A pragmatic approach is a light spec for medium and large work, skipped for small tasks."
license: "Cite with the author name and the canonical URL above."
---

# Spec-Driven Development: Write the Spec Before Letting AI Build

> For programmers and product people using AI to write code. Every technical term gets a short explanation.
>
> The description of the three levels, the three tools and the limits relies on Martin Fowler's analysis (which I read directly). The "light five-part spec" and the example are **my own suggestions**, not verified across many projects. The "refund feature" example is rebuilt to be easy to picture.

---

## Quick summary

- **Spec-driven development (SDD)** means writing down what to build first, then letting AI work from it.
- Martin Fowler describes **three levels**: **spec-first** (write first, may discard later), **spec-anchored** (keep the spec for maintenance), **spec-as-source** (edit only the spec, code is generated).
- Most approaches today are only **spec-first**.
- There are **real limits**: a heavy workflow for small tasks, many repetitive files that are hard to review, and agents that sometimes ignore the spec.
- A pragmatic approach: a **light five-part spec** for medium and large work, skipped for small tasks.

---

## Hard words, plain meaning

| Term | Plain meaning |
|---|---|
| **Spec** | A structured description of a feature's desired behavior, written in plain language. |
| **Coding agent** | AI that does not just answer but reads and edits files and runs commands to do the work. |
| **Acceptance criteria** | What must be true for the feature to count as done, often written as concrete examples. |
| **Memory bank** | Context files that apply to every session, such as rules and a project description. |
| **Brownfield** | A project that has been running a while, as opposed to a brand-new one. |
| **Non-deterministic** | The same input gives a slightly different result each time. |

---

## 1. Why a spec at all

When you ask AI with one short sentence, you give it the right to **fill the blanks itself**. For small jobs, no problem. For bigger ones, every blank is a guess, and you learn it guessed wrong only when you read the result.

An example from this very blog: when a user reported "the search does not work", the agent checked the logic and found it correct, while the real issue was that results sat below the first screen so nothing seemed to change (see [Three hours with an AI agent](https://www.thinnd.site/en/field-notes/agent-field-notes-real-project/)). A spec line like "after typing, results must show without scrolling" **might** have caught that early. I say "might" because that is hindsight reasoning, not a test result.

The idea of spec-driven development is to turn lines like that into an official step **before** AI works.

---

## 2. Three levels

According to Martin Fowler:

| Level | Meaning | The spec after the work |
|---|---|---|
| **Spec-first** | Write the spec first, use it to guide the work | May be discarded |
| **Spec-anchored** | Keep the spec, use it to evolve and maintain the feature | Kept and updated |
| **Spec-as-source** | The spec is the main artifact, people edit only the spec, not the code | Is the source, code is generated |

He notes that most SDD approaches today sit only at **spec-first**, and their plans for keeping specs over time are often vague.

He also separates a spec from a **memory bank**: a memory bank (rules, product and codebase descriptions) applies to every session, while a spec applies only to the feature being built or changed. So a file like AGENTS.md (see [A handbook for AI](https://www.thinnd.site/en/engineering/writing-agents-md/)) and a spec complement each other.

---

## 3. Three tools, per Fowler's article

Fowler examines three tools. The descriptions below are my summary.

| Tool | Workflow | Fowler's note |
|---|---|---|
| **Kiro** | Requirements, design, tasks. A "steering" feature acts as a memory bank | Lighter, mostly spec-first |
| **Spec Kit (GitHub)** | Principles, specify, plan, tasks, then implement, each step producing Markdown files | GitHub aims at spec-anchored, but Fowler sees it as spec-first since it creates a branch per spec |
| **Tessl (private beta)** | Aims explicitly at spec-anchored and tries spec-as-source. Generated files are marked not to be edited | Fowler saw non-deterministic output from the same spec |

These tools are new and change fast, so do not treat the descriptions above as final.

---

## 4. Fowler's observations and criticisms

What I find most worth reading is that Fowler **does not only praise**. He points out:

- **One workflow for every size.** Kiro turned a small bug into four user stories and 16 acceptance criteria. Spec Kit felt like overkill for a medium feature in an existing codebase, where writing directly with AI would have been faster and easier to control.
- **Review burden.** Spec Kit produced many repetitive, verbose Markdown files that are tiring to review. He would rather review code.
- **A false sense of control.** Agents sometimes ignored spec content, such as recreating a class that already existed even though the research step had documented it, or over-applying general principles.
- **Existing code is harder.** Two of the three tools are hard to introduce into running projects, so they are hard to evaluate.
- **The line between functional and technical is unclear** in practice.
- **"Spec" is being used loosely.** The word risks becoming a synonym for "detailed prompt".
- **Lessons from model-driven development (MDD).** MDD did not succeed for business applications. Fowler worries spec-as-source may inherit both MDD's rigidity and language models' non-determinism.

Even so, he still finds **spec-first thinking valuable**: carefully writing a spec before asking an agent often helps. What he doubts are the heavy, many-file workflows.

---

## 5. When it pays off, when it does not

*This table rests on Fowler's words plus my own reasoning.*

| Situation | Spec | Why |
|---|---|---|
| Fixing a small bug | **No** | Writing the spec costs far more than the work |
| A medium change in existing code | **Light**, or none | Reviewing lots of documents may cost more than writing directly with AI |
| A new medium to large feature | **Yes**, light | Many blanks for AI to guess, so pin them down first |
| High-risk change (money, permissions, personal data) | **Yes**, with clear acceptance criteria | You must write down what must not happen |
| A large, unclear problem | **Not yet**, learn about users first | A spec does not replace understanding the problem |
| Work needing control in small steps | **Little**, go step by step | A big spec can run against iterating in small steps |

---

## 6. A light five-part spec template

*My suggestion, not any tool's standard.* One short file, one page, next to the code.

1. **Why.** One or two sentences on the problem and the user. Not the solution.
2. **Desired behavior.** What the user sees and does, in plain sentences.
3. **Will not do.** Things deliberately out of scope. This section stops AI from "doing extra".
4. **Acceptable examples.** Three to six concrete examples: input, expected result, including odd cases (empty, very long, wrong type).
5. **Open questions.** What you do not know yet. Make AI ask instead of guessing.

**An illustrative example (rebuilt): a refund feature.**

- **Why:** A customer who cancels an order wants their money back without calling support.
- **Behavior:** On the order page, an undelivered order has a "Cancel and refund" button. After pressing it, the customer sees the status "refunding" and receives an email.
- **Will not do:** Partial refunds, delivered orders, switching to another payment method.
- **Acceptable examples:** an undelivered order of 200,000, fully refunded. A delivered order: the button does not appear. Pressing twice in a row: refunded only once. Payment gateway error: a message shows, the order status does not change.
- **Open questions:** Where does the refund go if the card has expired? Who approves above one million?

The acceptable examples in the middle are exactly what **tests** can follow and what reviewers use to compare. They also connect to the checklist for [reviewing AI-written code](https://www.thinnd.site/en/engineering/reviewing-ai-written-code/): point 1 (matches the request) and point 9 (what the test checks).

---

## 7. A four-step workflow you can use today

1. **Write the light spec** (about 10 to 20 minutes). Ask AI to question the vague parts, but **you** decide.
2. **Have AI draft a short plan** from the spec, and read the plan before letting it work.
3. **Work in small steps.** One small change per step, run it, then compare against the acceptable examples.
4. **Update or discard the spec.** If the feature will live long, update the spec when behavior changes. If not, delete it so it does not go stale.

Steps 3 and 4 match Fowler's concerns: **keep steps small and remember a spec can go stale too**.

---

## 8. A balanced view

- **Most of the evidence is one person's analysis.** Fowler tried the tools on a few tasks, it is not a large survey. I have not seen independent research measuring SDD's effectiveness.
- **The tools change fast.** The descriptions of Kiro, Spec Kit and Tessl may differ by the time you read this. Secondary sources also disagree on launch dates and usage figures, so I do not quote them.
- **"Spec" means several things.** Do not confuse a spec with a long prompt or with a design document.
- **A spec does not replace understanding users.** It helps pin down what to do, not discover what is worth doing.
- **The five-part template is my suggestion**, not verified across many teams.

---

## 9. Conclusion

Writing the spec first is not a new ritual for its own sake. It is a way to **pin down the blanks AI would fill itself**. But as Fowler reminds us, do not use a sledgehammer on small jobs: a light spec, a few acceptable examples and small steps are often enough.

A small step today: pick a feature you plan to ask AI to build this week, write the five parts above in ten minutes, then compare the result with how you usually work.

---

## References

- [Martin Fowler: Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl](https://www.martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
- [GitHub Spec Kit](https://github.github.com/spec-kit/)
- Related posts in this blog: [A handbook for AI (AGENTS.md)](https://www.thinnd.site/en/engineering/writing-agents-md/), [Reviewing AI-written code](https://www.thinnd.site/en/engineering/reviewing-ai-written-code/), [Three hours with an AI agent on a real project](https://www.thinnd.site/en/field-notes/agent-field-notes-real-project/)