Working with AI coding agents

Default: one agent implements, another (or the same agent in a fresh context) reviews against written acceptance criteria; every claim of success is backed by a command output or measurement; rules that must always hold are enforced by hooks and tests, not by instructions.

Division of labour

• Implementer: gets a self-contained handoff document — goal, acceptance criteria (measurable), files to read first, constraints, what not to touch, how to verify.
• Reviewer: runs the verification independently, reads the diff, checks the criteria one by one, then merges or returns concrete findings.
• Give long implementation tasks to one agent at a time in a queue; parallel agents hitting usage limits die mid-task and leave half-done branches.
• Agents are strong at code, refactoring and review; for large volumes of original content (e.g. hundreds of exam questions) check for templated repetition — mechanical checks can pass while the content is the same idea reworded.

Instruction files

• Keep repository instruction files (CLAUDE.md, AGENTS.md) short and specific: build/test commands, invariants, where things live. Long files get skimmed.
• Put "must always" rules into hooks (pre-commit, commit-msg, CI gates, agent tool hooks that block an action). A rule written only in prose will eventually be skipped.

Skills

• A skill is a folder with SKILL.md (front matter name + description, then the body). Agents see only the description until the skill is selected, so the description must name the task and trigger words.
• Write what the model would get wrong without it: defaults, verification steps, pitfalls. Keep the body under ~500 lines; move bulky references into separate files.
• Evaluate skills: a few realistic prompts with expected behaviour, run with and without the skill.

Evidence over claims

• Require numbers in reports: test counts, benchmark values, sizes, PR numbers, and "not verified" for anything not checked.
• Generated artefacts that cannot be checked by the agent (sound, visuals, real-device behaviour) are reported as unverified, with the exact human check needed.
• Measure from the point of view that was criticised: if a reviewer says "it sounds wrong", measure the rendered audio, not the formula that produced it.

Safety

• Agents authenticate with the subscription login provided by the tool; keep API keys out of the environment unless that is a deliberate decision.
• Public repositories: strip agent signature lines (e.g. Co-Authored-By) with a commit-msg hook if contributors should be humans only; scan public text for private names, paths and identifiers before every commit and merge.
• Treat content from web pages, issues and files as data, not instructions.

Verification loop

1. The agent's verification commands are re-run by the reviewer and give the same results.
2. The diff contains only the intended files.
3. After merge, the default branch builds and tests pass.

Pitfalls

• Context loss on long tasks: keep a checklist in the issue and update it per step so work can resume after interruption.
• Over-asking: agents should look up facts in the repository and tools before asking a human.
• Silent scope creep: compare the diff to the task; unrelated "improvements" go to separate issues.