Who it's for
Engineers who turn an approved spec into work for agents.
You'll be able to
Write a plan of small tasks, each with its test, that traces back to the spec.
The spec says what done means. The plan says how to get there, in steps small enough that an agent can't get lost.
What a plan holds
An agent writes the plan from the approved spec, and a person approves it. The result is a list of small tasks, each with its test.
A good plan opens with a few short parts before the first task:
- Goal. One sentence: what is true when the plan is finished.
- Architecture. A few lines on the parts and how they fit.
- Spec. A link to the spec, and which of its sections bind this plan.
- Constraints for every task. For example: tests first, run the full check before every commit, one commit per task.
One task, in shape
Each task names the files it touches, the names other tasks will rely on, and its steps as checkboxes. A made-up task for a search feature:
### Task 2: Find matching lines in one lesson
Files: create search/match.py, tests/test_match.py
Produces: match(text, word), a list of matching lines
- [ ] Open the issue for this task.
- [ ] Write the failing tests: test_finds_word_in_line,
test_no_match_gives_empty_list. Run them; they fail.
- [ ] Write the code. Run the tests; they pass.
- [ ] Run the full check. Commit, naming the step.
Keep a task to names, signatures and test names. The code belongs in the build. The "Produces" line matters: a later task that uses match can trust its name and shape.
Size a task to one pull request
One task is one issue, small enough for one pull request. Each task also says how we know it is done, and whether it is routine or judgment. A person sets that mark.
| Mark | When | How it is built |
|---|---|---|
routine | A known kind of work, and the "done" command exists | By an agent; a person reviews the pull request |
judgment | A new idea, several unfamiliar parts together, or a design choice | Spec, then plan first; a person reviews at each step |
Why the split: agents are strong on work they have seen and on small steps with a strict "done". On new ideas they drift back to the common form, and they don't know the reasons behind the work unless someone writes them down.
Check the plan against the spec
Before anyone builds, read the plan against the spec, in both directions:
- Coverage. Every acceptance point has a task that delivers it.
- Trace. Every task goes back to a point of the spec.
- Names. A name one task produces is spelled the same where another task uses it.
- Risky cases. Each case you are worried about has a named test, in the task that owns it.
A task that traces to no line of the spec is scope creep. Cut it, or change the spec first.
Try it
Take a spec from your own repository, or the one from the last lesson's exercise. Write a plan of three to six tasks. For each task, write the files, one failing test name, and routine or judgment. Then tick off each acceptance point against a task. Any point with no task, or task with no point, is a gap to fix before an agent starts.