Agents forget between sessions. The repo does not.
On my HRMS project a seeder bug, duplicate employee IDs from an un-deduplicated
pluck, silently broke CI. The fix was one line.
The durable fix was a standing section in the repo's CLAUDE.md that every agent
session loads before touching code:
## Known CI Footguns: Never Re-introduce
1. Seeder dedup: always ->unique() on pluck('employeeId') in
MockDataSeeder: duplicate IDs will break seeding silently
2. Leave calendar scoping: non-approver roles must only see
their own leaves; global scoping breaks this
3. Staging Docker BuildKit cache is flaky, pre-existing,
unrelated to code changes
The rule is simple: every regression a reviewer catches becomes a constraint the next agent session starts with, instead of a mistake it gets to repeat.
Why this beats a wiki
It lives next to the code it protects, so it cannot drift out of the workflow. Agents read it whether they remember to or not, because loading it is not their decision.
Each entry is a constraint, not a post-mortem. Agents act on imperatives far
better than on narratives. "Always call ->unique()" is actionable. "We once had
an incident where duplicate IDs caused problems" is a story.
It stays short. If the list grows past a screen, entries get promoted into lint rules or tests, which are harder still to ignore. A long list of rules is a list nobody reads, including the machine.