AI code review can pass every test and still wreck production, because tests only check what someone bothered to write down. The real risk is not bad syntax. It is the invariant that lived only in a senior engineer's head.
Every mature codebase carries structural rules nobody documented: a handler must be idempotent because the queue delivers at least once, a function only runs inside a transaction, an ID is opaque and never parsed. AI satisfies the explicit contract, the function signature, the types, the test suite. It has no way to see a rule that exists nowhere in the repo.
- These tripwires cluster in predictable places: retries, queues, caches, locks, timeouts, shared mutable state, and any boundary between trusted and untrusted input. A queue handler that looks clean and passes review can still double-charge a customer if it silently assumes single delivery.
- Documenting everything is not the fix. Full coverage is impossible and the map goes stale within a year. The better move is surgical: when a hidden contract surfaces, make it impossible to break quietly, through an assertion at the call site or a property test that calls the handler twice and checks the state matches.
- Files like CLAUDE.md work well for cross-cutting rules, but only if something breaks when the rule stops being true. A stale invariant is read by AI the same way as a current one, so an assertion or failing test has to sit behind every written claim, or the document becomes a liability instead of a guide.
- The habit that actually compounds: after an incident, don't just patch the code. Leave a loud tripwire so the next person, human or AI, trips it in a test run instead of in production.
Bottom Line: Contracts get safer not because someone wrote them down, but because the system is built to fail loudly the moment they are violated.
