Why it matters: AI coding tools can pass every test and still wreck a system, because the rules that hold services together often exist only as tribal memory, never as code or documentation.
The Details:
- Systems run on unwritten agreements: timestamps always in UTC, idempotency keys always lowercase, one service as the sole writer to a table. These constraints were never coded as tests or comments because the engineers who set them assumed everyone already knew. An AI assistant reading the full repository still cannot see an agreement that was never written anywhere.
- Local correctness hides the danger. A change can satisfy its function signature, pass its unit tests, and clear code review while quietly violating a system-wide contract that no single file describes. The more polished the change looks, the more reviewers relax, so the broken assumption slips through untouched.
- Adding more tests does not fix this, because tests are also local by construction. They verify the function in front of them, not the cross-service handshake that was never specified. The gap sits at the seam between services, exactly where no test is standing guard.
- The workaround is narration, not process. Saying a constraint out loud, such as noting that a function runs inside a transaction or a retry loop, forces it to become a sentence instead of a feeling. That sentence can then be checked, questioned, and eventually logged in a short plain-text file of one-line invariants that travels with the repository.
Bottom Line: The fix for invariant collapse is not smarter AI or heavier test suites. It is developers finally writing down the assumptions they always thought were too obvious to mention.
