“Done” does not count; actual test results and screenshots do.
Before handing off the work
- Run the project’s test command. Only add a test if the existing tests genuinely do not cover the behavior affected by this change. You do not need to add a regression test for every bug fix.
- For user-visible changes (webpages, interfaces): write a Playwright browser test and walk through the changed flow in a real browser. Any console error counts as a failure. Capture a screenshot at every step and save it in the project. If the browser is not installed:
npx playwright install chromium
, or use your local Chrome directly (). If you already have a browser tool, you can use it directly.
- If anything fails, fix it before handing off the work.
- Hand off the work in this format:
What was done: One sentence
Tests: <command> → N passed, 0 failed
Screenshots: <path>
Not verified: What and why; write “None” if there is nothing
After being corrected
First, fix the mistake from this instance. Then think: If the next agent only opens the file it opened, copies the nearest example, and takes the shortest path, will it make the same mistake again? If so, put a guard in place before it can happen.
Also check recent commits and AGENTS.md: if the same kind of mistake has been made before, guard against all of them.
The guard strategies below are ordered from strongest to weakest. If an earlier one is applicable, do not choose a later one:
- Remove the opportunity for the mistake: Give each responsibility one place and one way to handle it; delete old patterns that the agent might copy; consolidate multiple lists that otherwise require manual synchronization.
- Make it fail immediately: Use types, lint, tests, or validation scripts. The error message should directly state what needs to change.
- Make it immediately visible to people: If a machine cannot judge whether something looks good or feels easy to use, attach screenshots when handing off the work for human review.
- Write it into AGENTS.md: Use this only for decisions that require judgment. If the agent skips such a rule, nothing will report an error.
Once you add a check, test it against the mistake that actually occurred: put the mistake back and ensure the check reports an error; then restore the code and ensure it passes. A check that has never caught an error is no check at all.
Finally, add a row to the rule table in AGENTS.md:
| Rule | What enforces it |
|---|---|
| Run the tests and attach screenshots before handing off | `npm test` + browser screenshots |
If the rule is already in the table but nothing enforces it, the mistake is recurring. This time, move it one step toward stronger enforcement. Once the mistake can no longer happen, delete that row.
Writing tests
Tests should guard only behavior that users can perceive: data that was saved can be read back, and clicking a button changes the page. The following three types are junk tests. Fix them, or delete them if that is impossible:
- Pretend tests: The part that should be guarded is replaced by a test double (mock). For example, a test meant to verify whether data can be saved connects to a fake database, so it still passes even if the real database breaks.
- Tautological tests: The expected result is copied from the code’s current output, so if the code is wrong, the expected result is wrong too.
- Implementation-coupled tests: These check variable names or how many times an internal function was called. The behavior has not changed, but the test fails merely because the implementation was rewritten.
To evaluate a test, deliberately break the behavior it is meant to protect; the test should fail. Then rename only an internal variable; the test should still pass. If it cannot do both, it is a junk test.