An AGENTS.md file can be perfectly clear and completely wrong.
It says tests live in test/, but the directory moved to packages/api/spec/. It tells an agent to run npm test, but the project switched to pnpm. It warns not to edit generated files, while the generator named in the same paragraph disappeared three months ago.
Humans learn to distrust stale documentation. Coding agents are more literal: they may confidently follow the obsolete path.
The fix is not a longer prompt. Put a small, machine-readable contract inside the document and test the claims that can be tested.
Separate guidance from invariants
