AI engineering · Module 08a · Level 2: Working with AI
Spec-driven development (SDD)
When AI agents write most of the code, the most valuable thing a person writes is the specification: what to build, why, and how you'll know it's right. Spec-driven development makes that spec a real file in the repository, written and reviewed before any code, and used by the agent as its source of truth. This module explains the idea, its three levels, the tools and the practices teams have settled on by late 2026, and when it's worth the extra steps.
A 7-minute conversation: Sam asks, Priya explains
- Sam Everyone's suddenly talking about SDD, spec-driven development. What is it?
- Priya The idea that when AI agents write most of the code, the most valuable thing you write is the specification: what to build, why, and how you'll know it's right. SDD makes that spec a real file in the repository, written and reviewed before any code, and the agent builds from it.
- Priya Think of building a house. You could stand next to the builder every morning describing the next wall. Or you agree the architect's drawings first. Now everyone, including the inspector, has the same picture, and a change starts on the drawings, not with a sledgehammer.
- Sam So it's a reaction to vibe coding?
- Priya Exactly: chatting with an agent, accepting what it produces, correcting it one message at a time. SDD usually produces four things. A constitution, the rules for every change, a bit like AGENTS dot md. A spec: what and why, with testable acceptance criteria and no technology choices. A plan: how. And tasks: the order, each pointing back to a requirement.
- Sam Does everyone mean the same thing by it?
- Priya No. Birgitta Böckeler at Thoughtworks describes three levels. Spec-first: write a good spec for this task, and it may be left behind afterwards. Spec-anchored: keep the spec and update it whenever the feature changes. And spec-as-source: people only ever edit the spec, and the code is regenerated from it. That last one is still experimental.
- Sam And where does it stand now, a year in?
- Priya Thoughtworks' April twenty twenty-six Radar describes two camps. One leans on ever more capable agents with minimal structure. The other prefers defined workflows and detailed specs. Most teams sit in between: a light spec for anything with real rules, none for small changes.
- Sam What does the loop look like?
- Priya Intent, then spec, then your review. Then the plan, checked against the constitution, then your review again. Then tasks, then code and tests, task by task. And when something changes, the change goes into the spec first, and everything else follows from it.
- Sam How do you know the agent actually finished?
- Priya That's the newest step: converge. Spec Kit one point x ends with it. Thoughtworks calls the general pattern the Ralph loop: the same instruction runs again and again, each time with a fresh context, picking the next unfinished task, until every acceptance test passes. Ticked boxes aren't the goal. Passing tests are.
- Sam And the requirements themselves?
- Priya Kiro writes them in EARS, the Easy Approach to Requirements Syntax, from Rolls-Royce in 2009. "When a user requests a reset for a registered email, the system shall send a single-use link that expires after thirty minutes." One trigger, one response, numbers a test can check.
- Priya Your turn. "Store reset tokens hashed in PostgreSQL." Does that belong in the spec or the plan?
- Priya The plan. It's a decision about how. The spec only says the link is single-use and expires.
- Sam What can I try on the page?
- Priya An EARS builder that writes the requirement and the test it implies, and flags vague words like "fast" or "user-friendly". And a sorter: put each line in the spec, the plan, the tasks, or the constitution.
- Sam Is SDD always worth it?
- Priya No. It pays off for features with real rules and edge cases, for work shared between people or agents, and for anything that must be auditable. It's overkill for a one-line fix, and premature for an idea you're still exploring. Böckeler saw one tool turn a small bug into sixteen acceptance criteria.
- Sam Any warnings?
- Priya Thoughtworks has SDD, Spec Kit and OpenSpec all in "Assess". Its teams liked Spec Kit's constitution, but hit instruction bloat that degraded the agent's context, fixed by moving guidance into skills, and verbose markdown, fixed by customising the templates. Experienced engineers got the most out of it. And they suggest checking regularly whether the agents themselves now make the extra tooling unnecessary.
- Sam Is there a full example on the page?
- Priya Discount codes at checkout, chosen because it has everything: money rules, a real open question, all five EARS patterns, parallel tasks and a change a month later. The agent reads the rules, writes the spec and asks two questions it won't guess: can codes apply to sale items, and how many uses per customer. Then the plan, with a constitution check that money stays in integer cents. Then tasks. Then an analyze step that cross-checks the three files before any code, and catches a requirement with no task. Then implement and converge, and finally a change request that starts in the spec.
- Sam So what does good practice look like?
- Priya Specs in the repo, changed in the same pull request as the code. One small spec per feature. Acceptance criteria a test can check; Kiro even turns EARS requirements into property-based tests. Deltas when changing an existing system. A short constitution. A full spec only where the work is unfamiliar or sensitive. And converge, then review.
- Sam Which tools?
- Priya GitHub's Spec Kit, now version one point x: a command-line tool with thirty-eight agent integrations, commands for specify, plan, tasks, implement and converge, and extensions for bug fixing and idea assessment. Kiro, with requirements, design and tasks files, a quick spec for well-understood work, sync files to keep tasks current, and property-based tests from the requirements. OpenSpec, lightweight, built around change proposals that merge into living specs, and well suited to existing systems. Or no tool at all: a specs folder, AGENTS dot md, and plan mode.
- Sam Can I take the workflow with me?
- Priya Yes. The page has an SDD skill, one SKILL dot md file that follows the open Agent Skills standard. Copy it or download it, put it in your tool's skills folder, and any agent that supports skills can run the whole workflow, with two stops for your approval.
- Sam The memory hook?
- Priya Drawings before bricks. Agree what and why, then how, then the job list. And changes start on the drawings.
- Sam Common mistakes?
- Priya Calling a long prompt a spec. A constitution bloated into pages. One giant spec for the whole system. Putting technology in the spec. The full ceremony for a tiny change. Not reading what the agent generated. Letting the spec drift from the code. And trusting that the agent followed it, when the tests are the real proof.
- Sam And the lab?
- Priya Take the feature from module eight's lab, write a constitution and a spec with EARS acceptance criteria, then plan, task and implement in a second tool, and converge until every acceptance test passes. Make one change through the spec, and compare the effort with your first run.
1. The idea
Building a house. You could stand next to the builder every morning and describe the next wall ("a window here, maybe a bit lower"). Or you could agree the architect's drawings first: rooms, measurements, materials, and what the inspector will check. Builders can still make mistakes, but now everyone, including the inspector, has the same picture, and a change ("make the kitchen bigger") starts on the drawings, not with a sledgehammer.
Spec-driven development (SDD) means writing a structured specification before an AI agent writes code, and treating that spec as the source of truth for both the people and the agent. The name took off in 2025 with tools such as GitHub's Spec Kit and Amazon's Kiro, as a reaction to vibe coding: describing what you want in chat, accepting whatever the agent produces, and correcting it one message at a time.
Most SDD workflows produce the same few artifacts, each answering one question:
| Artifact | Answers | Typical contents |
|---|---|---|
| Constitution (or steering files) | What always applies in this project? | Principles and rules for every change: test-first, no new frameworks, security rules. Like AGENTS.md (Module 09). |
| Spec (requirements) | What are we building, and why? | User stories, rules, edge cases, testable acceptance criteria, what must not change. No technology choices. |
| Plan (design) | How will we build it? | Architecture, data model, API contracts, the tech stack, risks. |
| Tasks | In what order, in what steps? | Small, checkable tasks, each traced back to a requirement; some marked as safe to run in parallel. |
A year on, SDD is one of the most discussed practices in AI-assisted development, and opinion has split into two camps. Thoughtworks' April 2026 Technology Radar describes them: teams that lean on ever more capable agents with minimal structure, and teams that prefer defined workflows and detailed specs. Most teams sit in between, using a light spec for anything with real rules and none for small changes.
Not everyone means the same thing by "SDD". Birgitta Böckeler (Thoughtworks) describes three levels, each building on the last:
- Spec-first: write a good spec, use it for this task. Afterwards it may be left behind, so it can drift from the code. Almost every SDD tool does at least this.
- Spec-anchored: keep the spec after the task and update it whenever the feature changes. Spec and code evolve together.
- Spec-as-source: people edit only the spec; the code is regenerated from it and never edited by hand. The most ambitious, and still experimental.
2. How it works
The three levels differ in one thing: which files people edit, and which ones are allowed to fall out of date. Step through them.
Now follow one small feature, a password reset, through the actual files. Notice the requirement written in EARS form, the question the spec refuses to guess, and how every task points back to a requirement.
The newest step in the loop is converge: instead of trusting one pass, the agent keeps going until the code matches the spec. Spec Kit 1.x makes it the last phase (Specify → Plan → Tasks → Implement → Converge), and Thoughtworks names the general pattern the Ralph loop: the same instruction run again and again, each time in a fresh context, picking the next unfinished task, until every acceptance test passes. Converging needs good automated checks for the agent to run (Module 12a: harness engineering), and the result still goes through review (Module 13a).
EARS: requirements a test can checkKiro writes acceptance criteria in EARS (the Easy Approach to Requirements Syntax), created by Alistair Mavin and colleagues at Rolls-Royce and published in 2009. Five patterns cover almost everything: The system shall… (always), WHEN trigger (an event), WHILE state (a condition), WHERE feature (an optional feature) and IF … THEN (unwanted behaviour). Each sentence names one trigger and one response, so it turns directly into a test. Try it in section 3.
3. Try it yourself
Write an EARS requirement
Pick a pattern and fill in the blanks. The widget writes the requirement and the test it implies. Vague words such as fast, user-friendly or appropriate get flagged: a test can't check them.
Spec, plan or tasks?
The spec says what and why; the plan says how; the tasks say in what order. Mixing them up is the most common SDD mistake. Put each line where it belongs, then check.
4. Why it matters at work
SDD formalises the first two stages of the agentic workflow in Module 08 (map and plan) into files that live in the repository, get reviewed like code, and survive the session. That pays off in some situations and is pure overhead in others:
| Situation | SDD? | Why |
|---|---|---|
| A feature of a few days, several rules and edge cases | Yes | The spec catches misunderstandings while they cost minutes, and the task list keeps the agent's slices small. |
| Several people or agents on one feature | Yes | Everyone works from the same written intent; tasks marked as independent can run in parallel. |
| Behaviour that must be auditable (payments, compliance) | Yes | Requirements trace to tasks and tests; reviewers can check the code against the spec. |
| A one-line bug fix or a typo | No | Böckeler saw one tool turn a small bug into four user stories with sixteen acceptance criteria. Just fix it, with a test. |
| A vague idea you're still exploring | Not yet | Prototype first; write the spec once you know what you want. A spec can't be clearer than your thinking. |
Worked example: discount codes at checkout, end to end
The password reset above shows the files. This example shows every step of the workflow on a feature where SDD clearly earns its keep. Why this one:
| What a good SDD example needs | Discount codes have it |
|---|---|
| Business rules and edge cases | Expiry, minimum order, excluded items, one use per customer, a total that can't go below zero |
| Project rules that matter | It's money: the constitution's "amounts in integer cents" rule shapes the plan |
| A real question nobody has answered | Can a code be used on items that are already on sale? |
| All five EARS patterns | Event (apply), unwanted (expired), state (gift card in cart), optional feature (loyalty), ubiquitous (never below zero) |
| Work that can run in parallel | Database migration, customer messages and the admin screen are independent |
| A realistic change later | Finance asks for a minimum order value a month after launch |
| Measurable success | Redemption errors, checkout latency, support tickets |
A typo fix has none of these, and dark mode has hardly any rules. That's why they are poor examples, and poor uses of SDD. Step through the whole feature:
The analyze step produces a traceability table: every requirement links to the tasks that build it and the tests that prove it. Reviewers check the code against this table, not against memory:
| Requirement | EARS pattern | Tasks | Proved by |
|---|---|---|---|
| FR-001 apply a valid code | Event | T003, T005 | test_applies_percent_and_fixed_codes |
| FR-002 reject an expired code | Unwanted behaviour | T003, T004 | test_expired_code_message |
| FR-003 exclude gift cards | State | T003 | test_gift_card_not_discounted |
| FR-004 loyalty after code | Optional feature | T003 | test_loyalty_applied_after_code |
| FR-005 never below 0.00 | Ubiquitous | T003 | test_total_never_negative |
| FR-006 one use per customer | Unwanted behaviour | T001, T007 | test_second_use_rejected |
| FR-007 no discount on sale items | State | T003 | test_sale_items_excluded |
| FR-008 minimum order (added later) | Unwanted behaviour | T011 | test_below_minimum_message |
What good practice looks like in 2026
Across the tools and the teams reporting on them, the same habits keep coming up:
| Practice | What it means | Seen in |
|---|---|---|
| Specs live in the repo | Next to the code, under version control, changed in the same pull request as the code they describe. | Spec Kit, Kiro, OpenSpec |
| One spec per feature | Several small, focused specs rather than one document for the whole system, so teams can work in parallel. | Kiro best practices |
| Testable acceptance criteria | EARS or Given/When/Then, so every criterion becomes a test. Kiro now goes further: it derives property-based tests from EARS requirements and throws thousands of random inputs at the code. | Kiro, Spec Kit |
| Deltas for existing systems | Describe a change as additions, changes and removals to the current spec, instead of rewriting everything up front. | OpenSpec |
| A short constitution, plus skills | Keep project-wide rules brief; move reusable how-to guidance into skills that load only when needed, to avoid instruction bloat and context rot. | Thoughtworks Radar, April 2026 |
| Weight that matches the task | A full, reviewed spec for unfamiliar or compliance-sensitive work; a quick spec or none for well-understood changes. | Kiro Quick Spec, Spec Kit extensions |
| Converge, then verify | Loop until the acceptance tests pass, then review the code against the spec. Passing tests are evidence, not proof. | Spec Kit, Ralph loop |
Prompts that work in any agent, with or without an SDD tool:
| Step | Say this |
|---|---|
| Specify | "Write specs/007-password-reset/spec.md: user stories, rules, edge cases, acceptance criteria in EARS form, and what must not change. No technology choices. Mark anything unclear as [NEEDS CLARIFICATION] instead of guessing." |
| Clarify | "List every [NEEDS CLARIFICATION] and the questions you'd ask me. Don't continue until I answer." |
| Plan | "Read the spec and AGENTS.md. Write plan.md: data model, API, components, risks. Flag anything that breaks our project rules." |
| Tasks | "Write tasks.md: small steps, each naming the requirement it satisfies; tests first; mark independent tasks [P]." |
| Implement | "Do task T1 only. Run its tests. Tick it in tasks.md and stop." |
| Change | "Update the spec first: reset links now expire after 15 minutes. Then update the plan, tasks and tests to match." |
What teams report: the honest caveatsThoughtworks first placed SDD in "Assess" in November 2025 ("the workflows remain elaborate and opinionated"), and in April 2026 rated GitHub Spec Kit and OpenSpec "Assess" too. Its teams, mostly working on existing systems, found Spec Kit's constitution useful for scope, domain context, technology versions and coding standards. They also hit instruction bloat that degraded the agent's context (fixed by moving guidance into skills), unnecessary defensive code, and verbose markdown (fixed by customising the templates). Its conclusion: experienced engineers with strong clean-code and architecture habits get the most out of SDD. It also suggests re-checking regularly whether agents' own abilities make separate SDD tools unnecessary. Earlier, Böckeler pointed out the parallel with model-driven development, which generated code from models and failed for business software because it was rigid; LLMs remove the special languages but add non-determinism. Use SDD where its structure pays for itself, keep specs short, and verify behaviour with tests, not trust.
5. In your tools
You don't need a special tool: any of the five agents can follow a spec folder plus plan mode. Dedicated tools add templates, commands and checks. Checked 30 October 2026; these tools change fast, so check their docs.
| Tool | Artifacts | How you drive it | Level it aims for |
|---|---|---|---|
| GitHub Spec Kit | constitution.md, then per feature spec.md, plan.md (plus research, data model, contracts) and tasks.md | Version 1.x (1.2.5, October 2026). A specify CLI sets up the project for one of 38 agent integrations (Copilot, Claude Code, Gemini, Codex, Cursor, Kiro and others); then commands for each phase: constitution, specify, plan, tasks, implement and converge (the exact command syntax differs by agent). Bundled extensions add bug fixing and idea assessment; presets, workflows and 150+ community extensions customise it. Thoughtworks: "Assess" (April 2026) | Spec-first, moving towards spec-anchored |
| Kiro (AWS) | requirements.md (EARS), design.md, tasks.md; bugfix.md for bug fixes; steering files for project rules | Built into its editor: requirements-first or design-first workflows, Analyze Requirements to find gaps, a Quick Spec for well-understood features, tasks run one by one or in parallel waves, Sync Files to bring tasks up to date, and Correctness: property-based tests derived from the EARS requirements | Spec-first, with tools for staying anchored |
| OpenSpec | openspec/specs/ (the current behaviour) and openspec/changes/ (one folder per proposed change, with spec deltas) | Propose a change, apply it, then archive it: the deltas merge into the main specs. Lightweight and agent-neutral; Thoughtworks: "Assess" (April 2026), well suited to existing systems | Spec-anchored |
| Tessl | Specs mapped to generated code files marked "do not edit" | Explored spec-as-source in 2025; since January 2026 it focuses on a registry of agent skills | Spec-as-source (experimental) |
| Any agent, no tool | A specs/ folder you create, plus AGENTS.md as the constitution | Plan mode and the prompts in section 4, or the skill below | Whatever you choose to maintain |
The SDD skill: copy it into any agent
This skill runs the whole workflow from the worked example: weight check, spec with EARS criteria, clarify, plan with a constitution check, tasks, analyze, implement, converge and report, with two stops for your approval. It follows the open Agent Skills specification, so the same file works in every tool that supports skills, and borrows its file structure from GitHub Spec Kit's templates.
- Save it as
SKILL.mdin a folder namedspec-driven-development(the folder name must match the skill'sname). Use the Copy button on the code below, or download SKILL.md. - Put the folder where your tool looks (Module 11):
.claude/skills/for Claude Code;.agents/skills/for Codex, Cursor, Antigravity and Copilot (Copilot also reads.github/skills/). Commit it so your whole team gets it. - Use it: describe a feature ("add discount codes at checkout") or ask for a spec. The agent loads the skill from its description, or you can name it.
How it meets the standard: a lowercase hyphenated name that matches its folder; a third-person description that says what it does and when to use it (478 of the 1,024 characters allowed); a body well under the recommended 500 lines; a copyable progress checklist; explicit stop points; feedback loops (analyze, converge); and templates instead of long explanations, as Anthropic's skill-authoring guidance recommends.
---
name: spec-driven-development
description: Runs a spec-driven development workflow for a new feature or a change to an existing one. Writes spec.md (user stories, EARS acceptance criteria, open questions), then plan.md, then tasks.md, checks they agree, and implements task by task until every acceptance test passes. Use when the user asks for a spec, requirements, acceptance criteria, a feature plan or task breakdown, mentions spec-driven development or SDD, or describes a feature with business rules and edge cases.
compatibility: Works with any coding agent that supports Agent Skills. Needs to read and write files in the repository and run the project's tests.
metadata:
author: interviewkata.com
version: "1.0"
---
# Spec-driven development
Write and agree the spec before any code. The spec says what and why; the plan says how; the tasks say in what order. The spec is the source of truth: every change starts there.
## Choose the weight first
- **Skip SDD** for typos, one-line fixes and pure refactors. Fix it, with a test if behaviour matters.
- **Quick spec** (spec.md with acceptance criteria, then tasks) for small, well-understood features.
- **Full workflow** (all steps below) for features with business rules, several people or agents, unfamiliar code, or anything auditable such as money, auth or personal data.
Tell the user which weight you chose and why, in one sentence.
## Workflow
Copy this checklist into your response and tick it off as you go:
```
SDD progress:
- [ ] 1. Read the rules (constitution / AGENTS.md)
- [ ] 2. Specify: spec.md
- [ ] 3. Clarify: no open questions left ← STOP for the user
- [ ] 4. Plan: plan.md, constitution check ← STOP for the user
- [ ] 5. Tasks: tasks.md
- [ ] 6. Analyze: spec ↔ plan ↔ tasks agree
- [ ] 7. Implement task by task, tests first
- [ ] 8. Converge: every acceptance test passes
- [ ] 9. Report: what was built, against the spec
```
Files live in `specs/NNN-short-name/` (for example `specs/014-discount-codes/`), next to the code and committed with it.
### 1. Read the rules
Read `specs/constitution.md` if it exists, otherwise AGENTS.md (or the agent's own instruction file). List the rules that apply to this feature. If there is no constitution and the feature is non-trivial, propose three to seven project rules and ask the user to confirm them.
### 2. Specify
Write `spec.md` using the template below. Rules:
- No technology choices: no frameworks, tables, endpoints or libraries. Those go in the plan.
- Order user stories by priority. P1 alone must be a usable result.
- Write every functional requirement as one EARS sentence (see "EARS patterns"), with numbers and exact messages, never "fast", "appropriate" or "user-friendly".
- Never guess. Mark each unknown as `[NEEDS CLARIFICATION: question? options: A / B]`. Keep at most five; if there are more, ask the user to narrow the scope.
- List what is out of scope. It stops the agent building extra features.
### 3. Clarify (stop and ask)
Ask the user every `[NEEDS CLARIFICATION]` question in one message, each with your recommended option. Record the answers in a `## Clarifications` section with the date, update the requirements, and remove the markers. Do not continue to the plan while any marker remains.
### 4. Plan (stop and ask)
Write `plan.md`: technical context (language, dependencies, storage, testing), data model, interfaces or API contracts, components, risks, and a **constitution check** table listing each rule and whether the plan complies. Any violation needs a written justification and the simpler alternative that was rejected. Ask the user to approve the plan before writing tasks.
### 5. Tasks
Write `tasks.md` as a checklist, in phases: setup, foundational, one phase per user story in priority order, then polish. Each line:
```
- [ ] T005 [P] [US1] Short description, exact file path (FR-001, FR-003)
```
- `[P]` only when the task touches different files from other open tasks and depends on nothing unfinished.
- Tests come before the code they test, and must fail first.
- End each user story with a checkpoint: the story works on its own.
### 6. Analyze
Before writing code, check the three files agree. Fix every problem, then re-check:
- Every FR and every acceptance scenario has at least one task and one test.
- Every task points to a requirement; remove tasks that do not.
- No technology in the spec; no requirement in the plan that the spec lacks.
- No conflicts with the constitution; no `[NEEDS CLARIFICATION]` left.
- Terms are used consistently across the three files.
Report the result as a short table: check, status, fix made.
### 7. Implement
One task at a time, in order. For each: write or update the test, see it fail, write the code, run the project's checks (types, lint, tests), tick the task in tasks.md. Do not edit tests, lint rules or CI configuration to make a check pass. If the spec turns out wrong or incomplete, stop and propose a spec change instead of improvising.
### 8. Converge
Run the full acceptance test set for the feature. If anything fails, find the open or wrong task, fix it, and run again. Ticked boxes are not the goal; every acceptance test passing is. Stop after three loops without progress and report what is blocking.
### 9. Report
Summarise against the spec: each user story and FR with its status and the test that proves it, anything deferred, and any spec changes made along the way.
## Changing a feature later
Change the spec first, then the plan, tasks, tests and code, in the same pull request. Describe the change as a delta at the top of spec.md:
```
## Changes
- 2026-11-03 ADDED FR-009: per-customer limit (reason: abuse report #812)
- 2026-11-03 MODIFIED FR-004: minimum order 20.00 → 25.00
```
## EARS patterns
| Pattern | Template |
|---|---|
| Ubiquitous | The <system> shall <response>. |
| Event | WHEN <trigger>, the <system> shall <response>. |
| State | WHILE <state>, the <system> shall <response>. |
| Optional feature | WHERE <feature is enabled>, the <system> shall <response>. |
| Unwanted behaviour | IF <unwanted condition>, THEN the <system> shall <response>. |
One trigger and one observable response per sentence, so each turns directly into a test.
## spec.md template
```markdown
# Feature: <name>
Status: Draft | Clarified | Approved Spec: specs/NNN-short-name/
## User stories
### US1 (P1): <title>
As a <user>, I want <goal>, so that <value>.
Independent test: <how to check this story alone>
Acceptance scenarios:
1. Given <state>, when <action>, then <outcome>.
### US2 (P2): <title>
...
## Functional requirements (EARS)
- FR-001 WHEN <trigger>, the <system> shall <response>.
- FR-002 IF <unwanted condition>, THEN the <system> shall <response>.
- FR-003 [NEEDS CLARIFICATION: <question>? options: A / B]
## Edge cases
- <boundary or error case and the expected behaviour>
## Key entities (no implementation details)
- <Entity>: <purpose, key attributes, relationships>
## Success criteria (measurable, technology-agnostic)
- SC-001 <metric and target>
## Out of scope
- <what this feature will not do>
## Clarifications
- <date> Q: <question> → A: <answer>
```
## plan.md template
```markdown
# Plan: <name>
Spec: specs/NNN-short-name/spec.md
## Technical context
Language / dependencies / storage / testing / constraints
## Constitution check
| Rule | Complies? | Notes |
|---|---|---|
## Data model
## Interfaces and contracts
## Components and changes per file
## Risks and mitigations
## Complexity tracking (only for justified rule violations)
| Violation | Why needed | Simpler alternative rejected because |
```
## Example requirement set
For "discount codes at checkout":
```
FR-001 WHEN a customer enters a valid, active code, the checkout service shall apply its discount to the eligible items and show the new total.
FR-002 IF the code has expired, THEN the checkout service shall reject it and show "This code expired on <date>".
FR-003 WHILE the cart contains a gift card, the checkout service shall exclude the gift card from the discount.
FR-004 WHERE the customer has a loyalty account, the checkout service shall apply the loyalty discount after the code discount.
FR-005 The checkout service shall never reduce an order total below 0.00.
```6. Remember it
Memory hook: "Drawings before bricks"Agree the drawings (what and why), then the building method (how), then the job list (in order). Changes start on the drawings.
How this hook works: what “Drawings before bricks” means
What the slogan means, phrase by phrase
- “Drawings”
- The spec: what the feature does and why, with acceptance criteria a test can check. No technology choices.
- “before”
- Written and reviewed before the agent writes code; open questions are marked, not guessed.
- “bricks”
- The code, built task by task from the plan, each task traced to a requirement.
Why this picture fits: nobody pours concrete before the drawings are agreed, and an inspector checks the building against the drawings. With agents, the drawings are also what the builder reads every morning.
The story → the concept
| Building | SDD | File |
|---|---|---|
| Building regulations | Rules for every change | Constitution / AGENTS.md |
| Architect's drawings | What and why | spec.md / requirements.md |
| Engineer's method | How | plan.md / design.md |
| Job list | In what order | tasks.md |
| Inspection | Acceptance criteria → tests | The test suite |
The trap it saves you from
Changing the building without changing the drawings. Fix a requirement in code only, and the spec silently becomes fiction (drift); the next agent session reads the fiction and undoes your fix.
7. Common mistakes
Calling a long prompt a specA spec is a reviewed file in the repository with acceptance criteria a test can check. A paragraph in a chat window is a prompt.
Technology in the spec"Use Redis with a 30-minute TTL" is a plan decision. The spec says "links expire after 30 minutes"; the plan decides how.
The full ceremony for a small changeMatch the weight to the task: a quick spec or none at all for small fixes.
Not reading what the agent wroteGenerated specs and plans can be long and plausible. Review them as carefully as code; delete what isn't needed.
Letting the spec driftChange the spec first, or in the same pull request as the code. A stale spec misleads every future session.
Instruction bloatA constitution that grows into pages of rules fills the agent's context and makes it worse (context rot). Keep it short; move reusable guidance into skills (Module 11).
One giant specA single document for the whole system is impossible to keep current. One focused spec per feature; deltas for changes.
Trusting that the agent followed the specAgents still skip or over-apply instructions. Acceptance criteria become tests, and the tests are the proof.
8. Hands-on lab (week 8 of the roadmap)
- Pick the feature from Module 08's lab, or a new one of similar size.
- Write the constitution: five to ten project rules, each with a reason. If you have an AGENTS.md, start from it.
- Specify: user stories and at least five acceptance criteria in EARS form (use the widget above). Leave open questions marked.
- Clarify, plan and task: answer the questions, have the agent write the plan and tasks, and change at least one thing in each before approving.
- Implement task by task in tool B, turning each acceptance criterion into a test.
- Converge: if your tool has a converge step (or a loop you script yourself), run it until every acceptance test passes, and note how many passes it took.
- Make a change through the spec: alter one requirement, then update the plan, tasks and tests. Did the agent follow the spec, or the old code?
- Try the skill: install the SDD skill above in a second tool and run the same feature through it. Did the analyze step find a gap you missed?
- Compare with your Module 08 run: time, corrections, review effort, and whether the spec is still accurate a week later. Optionally repeat with GitHub Spec Kit or Kiro.
9. Self-check quiz
You keep the spec after shipping and update it every time the feature changes. Which level is that?
Spec-first may leave the spec behind; spec-as-source also forbids editing the code by hand.
"Store reset tokens in PostgreSQL, hashed with SHA-256." Where does that belong?
It's a decision about how. The spec only says tokens are single-use and expire.
Which requirement can a test check?
One trigger, one observable response: that's an EARS requirement, and it maps straight onto a test.
The spec doesn't say whether login uses email or phone numbers. What should the agent do?
Guessing bakes in a decision nobody made; supporting both builds features nobody asked for.
What does a converge step (or a "Ralph loop") do?
The agent repeats the work, each time with fresh context, picking the next unfinished task, until the code matches the spec.
What does the analyze step check, before any code is written?
In the worked example it caught a requirement with no task and an untracked success criterion, while fixing them was still cheap.
Where is a full SDD workflow most likely overkill?
The ceremony costs more than the change. Fix it, with a test if it matters.
10. Go deeper
| Resource | Time | Why |
|---|---|---|
| Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl (Birgitta Böckeler, martinfowler.com, October 2025) | 25 min | The clearest independent explanation: the three levels, three tools tried on real tasks, and honest concerns. |
| Spec-driven development (Thoughtworks Technology Radar, November 2025) | 3 min | Why it sits in "Assess", in one paragraph. |
| Thoughtworks Radar, April 2026: GitHub Spec Kit, OpenSpec, Ralph loop | 10 min | What teams found in practice a year in: the two camps, context rot, templates, convergence. |
| GitHub Spec Kit (official site) | 10 min | The 1.x processes: SDD with converge, bug fixing and idea assessment. |
| Correctness and best practices (Kiro) | 15 min | Property-based tests from EARS requirements; keeping specs in sync; quick versus full specs. |
| Spec-Driven Development (GitHub Spec Kit) | 20 min | The philosophy behind Spec Kit: specs as the primary artifact, the constitution, [NEEDS CLARIFICATION] markers. |
| Specs (Kiro documentation) | 15 min | Requirements, design and tasks files, EARS, and requirements-first versus design-first. |
| Easy Approach to Requirements Syntax (Wikipedia) | 10 min | The five EARS patterns with examples. |
| Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants (arXiv, January 2026) | 45 min | A practitioner guide with a decision framework for when SDD adds value. |