Spec-Driven Development for Dummies
Write what "done" means before an AI agent writes the code, gate the work with checks a human can trust, and leave evidence an auditor can read.
AI coding agents are fast at typing and terrible at knowing what you meant. This course teaches the loop that fixes that: intent written down first, acceptance criteria before code, a gate the agent must pass before a person looks, and a merged change that carries its own proof. You practice on a tiny bookshop app with a coding agent named Quill, and Eve, the built-in tutor, is one highlight away.
9 lessons · about 7 hours of reading · quizzes graded by code and by Eve
- 1intent.mdproduct owner accepts
- 2spec.mdrouted to policy owners
- 3plan.mdengineer approves before build
- 4Failing testfails for the expected reason
- 5gate.sh + hooksallow, ask, or block
- 6evals/*.jsonpass rate gates the merge
- 7CI workflowconfig is code
- 8Evidence packcode + proof + approver
How the course is organized
| Phase | Question it answers | Lessons |
|---|---|---|
| Specify | What does "done" mean, in writing, before anything is generated? | L0–L3 |
| Gate | What must the agent's work pass before a person looks, and where does a person decide? | L4–L6 |
| Prove | What evidence shows the gate ran, and who accepted the change? | L7–B1 |
Modules
Start Here
What a coding agent is, why "done" has to be written down, and the four rules of a spec-driven lifecycle.
The Executable Spec
The artifact chain from intent to merged PR, the six parts of a spec an agent can build from, and turning criteria into failing tests before any code exists.
The Enforced Gate
Checks the agent must pass before a person looks, hooks that allow, ask, or block, eval cases built from real work, and why the gate lives in CI.
The Auditable Change
Control, evidence, metric, and cost: how to prove a gate ran, and how to talk to an auditor with files instead of memories.
Bonus
A 30-day plan for bringing spec-driven development to a real team, and answers to the usual objections.
Every lesson
Module 0Start Here
- L0Specify· 35 min Not startedWhat Is Spec-Driven Development?
Meet Quill, see why "done" has to be a file, and learn the four rules and the one-liner that run the whole course.
Module 1The Executable Spec
- L1Specify· 45 min Not startedThe Artifact Chain
Follow one change through six files, from intent.md to the merged PR, and learn who accepts each link and why the agent never promotes its own work.
- L2Specify· 60 min Not startedWriting an Executable Spec
Write the six parts of a spec Quill can build from and Mr. Hale can read: intent, constraints, criteria, verification, human gates, evidence.
- L3Specify· 55 min Not startedFrom Spec to Failing Test
Turn one acceptance criterion into a test that fails for the right reason, hand it to Quill with the tests locked, and read the diff for a moved test.
Module 2The Enforced Gate
- L4Gate· 55 min Not startedThe Enforced Gate
Build gate.sh, write a hook that allows, asks, or blocks, make every block explain itself, and log each decision where no one engineer can edit it.
- L5Gate· 55 min Not startedEval Cases for Coding Agents
Turn real tasks into eval cases with checks, version them in the repo, and regression test CLAUDE.md, skills, and hooks like the code they steer.
- L6Gate· 50 min Not startedWhy the Gate Lives in CI
Move the eval gate into CI so a model swap or prompt edit cannot change Quill's behavior without a person seeing the pass rate drop first.
Module 3The Auditable Change
- L7Prove· 50 min Not startedEvidence Thinking and Audit Readiness
Answer control, evidence, metric, and cost for every gate, then assemble the evidence pack that lets you talk to an auditor with files instead of memories.
Module 4Bonus
- B1Bonus· 30 min Not startedBonus: Adopting It on Your Team
A 30-day plan for bringing spec-driven development to a real team, one change, one gate, one eval suite at a time, plus answers to the usual objections.
Meet Bramble Books, Shelf, and Quill
Bramble Books is a small bookshop chain whose web app, Shelf, handles inventory, online orders, gift cards (stored value, so money rules apply), and customer emails (so privacy rules apply). Quill is the AI coding agent the team uses. Every lesson follows the same three change requests through the same artifact chain, so you never re-learn the setting.
| Tool | What it does | Risk tier |
|---|---|---|
intent.md | The outcome in one sentence, in business terms | Nadia (product owner) accepts |
spec.md | Intent, constraints, acceptance criteria, verification, human gates, evidence | Concerns routed to Priya (policy owner) |
plan.md | The steps Quill will take and the files it will touch | Omar (engineer) approves before build |
make test | Build, tests, lint; output attached to the PR | Exit code is the verdict |
gate.sh + hooks | Allow, ask, or block an agent action; log every decision | Human gate for production actions |
evals/*.json | Real tasks paired with accepted outcomes; runs in CI | Pass rate gates the merge |
The ideas follow a short lecture on AI-augmented engineering in a regulated software lifecycle: the artifact chain, the executable spec, the enforced gate, evals in CI, and evidence thinking. All lesson text, examples, quizzes, the glossary, and the Bramble Books world were written for this course.