Patterns / Agent harness

One task per run, small diffs

Break work into small, separately verifiable tasks and commit between them.

The problem

Long, multi-goal agent runs drift. Context fills up, early instructions lose weight, and the final diff mixes several concerns so it can only be accepted or rejected as a whole.

The pattern

Give each run one goal that produces one reviewable diff. Between runs, verify and commit (or otherwise checkpoint) so every step has a known-good fallback. If a run goes wrong, revert to the last checkpoint and retry with a better brief instead of asking the agent to patch its own mess in an ever-longer thread.

A useful size check: could you review the resulting diff properly in a few minutes? If not, split the task.

Template

We are doing this in small steps. Current step only:

Step <n> of <total>: <single goal>

Rules for this step:
- Change only what is needed for this step.
- Keep the diff small; if it grows beyond <N> files or ~<M> lines, stop and propose a split.
- When the step's checks pass, stop and summarise. Do not start the next step.

Checks for this step:
- [ ] <test or command>
- [ ] <observable behaviour>

Remaining steps (for context only, do not start them):
<n+1>. <goal>
<n+2>. <goal>

When not to use it

• Mechanical, uniform changes across many files (a rename, a formatting pass) where one large diff is easier to verify with a single check.
• When splitting would leave the code broken between steps. Pick boundaries where each step still builds and passes.