Who it's for
Engineers who write the specs agents build from.
You'll be able to
Write a short spec whose done lines a checker can test, one by one.
A spec says what to build and how you will know it is done. Write the second part first.
What a spec is for
A spec is a short document with a list of checkable lines. Agents build to it, and reviewers check against it. A person approves it before any code is written.
Later, a spec checker reads the change against each line and says whether it is met, missing, or extra. That only works if every line can be answered.
Say what done means first
Put the acceptance points under one fixed heading, one line each, as a checkbox. Each point can be checked with yes or no. Here is a made-up example for a search feature:
## Acceptance points
- [ ] Searching for a word lists every lesson that contains it.
- [ ] Each result shows the lesson title and the line that matched.
- [ ] A search with no matches says so, and shows no error.
- [ ] An empty search box does not run a search.
Compare lines a checker cannot test: "search is fast", "results are relevant", "handles edge cases". Nobody can answer yes or no to them, so an agent can't tell when it has met them.
Say what "done" means before anyone writes code.
Then add one command that says "done" or "not done": a test, or a score with a limit. Choose it yourself, and make sure it cannot pass while the work is wrong. With that command, an agent can see on its own how far it is.
The rest of the spec
Keep it short. A small change needs no spec file at all: the issue is the spec, with the same heading. A bigger one usually has these parts:
| Part | What it holds |
|---|---|
| What to build | Who needs it, and what they can do when it is done |
| Acceptance points | The yes-or-no lines |
| How we know it is done | One command |
| Starting points | Code to read first, things to leave alone |
| Out of scope | What this spec does not cover |
Larger designs add a few more: the question the design answers, two or three ways to build it with one recommended, the failure cases, and a list of what is not verified yet. That last list stops guesses from passing as facts.
Change the points before the code
Acceptance points are the contract, so they get extra care. Change them in their own pull request, before the code. A pull request that changes a spec's points and its code together gets a notice for the reviewer. The notice does not block; it asks the reviewer to look.
A spec can be reviewed too, before anyone builds from it. Useful questions: what does a builder need that the spec doesn't say? Do two places disagree? Can a sentence be read two ways? Is there a point with no way to check it true or false?
Try it
Pick a recent issue in your own repository. Rewrite what "done" means as three to five checkbox lines under one heading. For each line, ask: could a test or a reviewer answer this with yes or no? Rewrite any line that fails. Then add one "out of scope" line, and the command that would prove the work is done.