What 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.
- Say in one sentence what a coding agent is and what it is bad at.
- Explain why "done" must be written down before anything is generated.
- State the four rules of a spec-driven lifecycle: intent first, criteria before code, every artifact signed, humans accept at boundaries.
- Repeat and explain the one-liner: the spec is the contract, the agent is the implementer, the gate is the evidence.
- Answer "where is done defined in your workflow, and who would an auditor ask?"
Why this matters
Omar opens a terminal and types one line to Quill, the coding agent Bramble Books uses: "add gift card balances to the order page." That is CR-101. Nine minutes later Quill has read the repository, edited four files, run the tests, and opened a pull request. The tests pass. The diff is tidy. Omar merges it before lunch.
Two weeks later Priya, who owns the rules about payments and customer data, notices something on a customer's order page. It shows the balance of a gift card that belongs to someone else. Nobody wrote down whose balance may be shown, so Quill showed every balance it could find. When Mr. Hale, the auditor, asks who approved the change, the honest answer is "the agent, sort of." This lesson is about making sure that answer never comes out of your mouth.
1. Meet Quill: what a coding agent is
A coding agent is a language model running in a loop. It reads files, edits files, runs commands, reads the results, and repeats until it decides the task is finished. Quill is the one Bramble Books uses. It runs in the terminal, sees the whole Shelf repository, and opens pull requests on GitHub. Claude Code, Cursor's agent mode, and Copilot agents are all this kind of tool.
What Quill is good at: typing. It knows TypeScript, it knows how a Makefile works, and it can hold a hundred files in its head at once.
What Quill is bad at: knowing anything you did not tell it. It has no idea Priya exists or that a gift card holds real money. It fills every gap with the most plausible guess.
2. Where is "done" defined today?
"Done" is the point at which everyone agrees the work is complete and correct. On most teams, that definition lives in a ticket title, a chat thread, and a few heads. None of those places work for an agent or for an auditor.
A ticket title is a topic, not a test. A chat thread is a stream of maybes, and the last message wins. A head cannot be read by anyone else, and it forgets.
Spec-driven development is a way of working where the definition of done is written in files, before the agent generates anything, and every stage of the work is checked against those files. It rests on four rules.
3. Rule 1: intent is written down first, as a versioned file
Intent is the outcome you want, in business terms, in one paragraph. Not how to build it. What changes for the person who uses it.
A versioned file lives in the repository under version control, so every change to it has an author, a date, and a diff. The intent goes in intent.md, next to the code, and it is the first thing that exists for any change. Nothing is generated until Nadia has accepted it.
It names who (a customer), what (remaining value), where (their own order page), and why (to decide about a second payment). It also says what is out: staff views. The clause "the customer's own cards only" is the clause Quill never got.
4. Rule 2: acceptance criteria before code
Acceptance criteria are observable behaviors that must be true for the change to count as done. Observable means a person or a test can look and say yes or no. "Works correctly" is not observable. "A customer sees the balance of their own gift card and no other" is.
The criteria are written before any code is generated, and the agent's work is measured against them afterward. That order is the whole point.
5. Rule 3: every artifact carries an author, a timestamp, and a reviewer of record
An artifact is any file the process produces: the intent, the spec, the plan, the test log, the pull request. Each one carries three facts at the top: who wrote it, when, and who reviewed it. The reviewer of record is the named person who accepted the artifact and is accountable for that acceptance.
A spec (short for specification) is the file that turns the intent into something an agent can build from: intent, constraints, acceptance criteria, verification, human gates, and evidence. L2 teaches all six parts. For now, look at its header.
An agent produces artifacts quickly and in volume. Without headers, a folder of agent-written files is a folder of anonymous claims. With headers, it is a chain of decisions, each with a name attached.
6. Rule 4: a human accepts or rejects at each stage boundary
A stage boundary is the point where one artifact is finished and the next one begins: intent to spec, spec to plan, plan to code, code to merged pull request. At every boundary, a named human accepts or rejects. Promotion is the act of moving work across a boundary. The rule is short: the agent never promotes its own work.
| Boundary | Who accepts | What they are saying yes to |
|---|---|---|
| Intent to spec | Nadia | This is the outcome we want |
| Spec concerns | Priya | These constraints match policy |
| Plan to build | Omar | These steps and files are the right ones |
| Code to merge | The reviewer of record | The criteria are met and the evidence is attached |
7. The one-liner
Here is the whole course in one sentence. The spec is the contract, the agent is the implementer, the gate is the evidence.
A contract is an agreement about what will be delivered, written so both sides can check it. The spec plays that role between the team and the agent. The implementer does the building, and that is Quill. A gate is a check the work must pass before it moves on, with a record that it ran. Evidence is anything that proves a rule was followed: a log, a test result, a signed header. The gate produces evidence.
Say the sentence out loud once. You will hear it again in every lesson.
8. Where this course goes
The course has three verbs, and every lesson belongs to one.
| Verb | The question | Lessons |
|---|---|---|
| Specify | What does "done" mean, in writing, before anything is generated? | L0 to L3 |
| Gate | What must the agent's work pass before a person looks, and where does a person decide? | L4 to L6 |
| Prove | What evidence shows the gate ran, and who accepted the change? | L7 and B1 |
The work moves through an artifact chain: intent.md, then spec.md, then plan.md, then make test, then evals/*.json, then the merged pull request. L1 walks the chain. L2 and L3 write the spec and turn its criteria into failing tests. L4 to L6 build the gate: a script, hooks that allow, ask, or block, and a workflow in CI. L7 shows what to hand Mr. Hale.
Before you go on, answer one question in writing: where is "done" defined in your workflow today, and who would an auditor ask? If the answer is a ticket and a shrug, you are in the right course.
Summary
- A coding agent is a model in a loop that reads, edits, and runs. It is fast at typing and knows nothing you did not tell it.
- "Done" defined in tickets, chats, and heads cannot be checked by an agent or an auditor. It has to be a file.
- Four rules: intent first as a versioned file, acceptance criteria before code, every artifact signed with author, timestamp, and reviewer of record, and a human accepting at every stage boundary.
- The agent never promotes its own work. Quill opens the PR, a person merges it.
- The spec is the contract, the agent is the implementer, the gate is the evidence.
Key terms in this lesson
Check your understanding
Pick an answer to see why it is right or wrong. These are graded in code, instantly.
Apply it
Write your answer in your own words. Eve grades it against a rubric and gives you feedback, the same way an LLM judge works in Lesson 5.
Pick a workflow you know, at work or in a side project. Where is "done" defined in it today, and who would an auditor ask to prove a change was approved?
Rewrite the CR-101 request ("show a gift card's remaining balance on the order page") as an intent paragraph that Nadia could accept, followed by three acceptance criteria that Quill could be measured against. At least one criterion must address whose balance may be shown.
Instructor notes(for whoever is teaching this lesson)
Talking points
- The nine-minute CR-101 is the thread for the whole session. Every rule gets tested against one question: would this rule have stopped the balance leak?
- A coding agent is a model in a loop. It acts without anyone reading each step unless you put a person at a boundary.
- "Done" is a decision, not a feeling. Three people gave three definitions for the same ticket, and the agent worked from the typist's.
- The four rules are the course's skeleton. Say them in order and keep saying them: intent first, criteria before code, every artifact signed, humans accept at boundaries.
- The one-liner is the exit ticket. Students should be able to say it without looking and map CR-101 onto each word.
Live demo idea
Ask the room to define "done" for CR-101 in one sentence each, on paper, before you show any code. Collect five and read them aloud. Almost none will mention other customers' cards. Then show Nadia's intent.md and the three criteria, and ask which of the five sentences would have caught the leak. Close by opening any agent-authored pull request and asking, "who is the reviewer of record here?" If nobody can answer in ten seconds, the point is made.
Common misconceptions
- "The agent understood the request, so it must have known the rule." It understood the words. It had no way to know a rule that lived only in Priya's head.
- "Green tests mean done." Tests check what someone thought to test. A missing criterion produces no failing test.
- "The intent is the same as the ticket." The intent names who, what, where, why, and what is out of scope, and a named person accepts it.
- "Rule 4 means humans review every line." It means a named human accepts at each boundary. Reviewing the diff is one part; checking it against the criteria is the part that matters.
- "Evidence is the code." Evidence is what proves the gate ran: a test log, a decision log, a signed header. Code is the thing the evidence is about.
Timing
Thirty-five minutes: story and section 1, five; section 2 with the three definitions, five; rules 1 and 2, eight; rules 3 and 4, eight; the one-liner, four; where the course goes, three; the closing question, two.
If you only have 20 minutes
Run the "define done" demo (six minutes), teach the four rules from the summary bullets with the spec.md header on screen (ten minutes), and end with the one-liner mapped onto CR-101 (four minutes). Assign sections 1 and 8 as reading and the closing question as written homework for the next session.