How to keep AGENTS.md in sync with your codebase (CI automation)

An AGENTS.md is only useful if it matches reality. The fastest way to keep it honest is to stop treating it as a hand-written doc and start treating it as a build artifact.

Why it rots

Commands change, directories move, new test runners appear. Within weeks a manutained file is describing a project that no longer exists — and the agent follows instructions that fail.

Automate regeneration in CI

• Add a job that re-scans the repo on every pull request.
• Diff the generated AGENTS.md against the committed one.
• If they differ, post the update as a PR comment or fail the check so someone commits it.

Make it a gate, not a suggestion

Wire the check into your merge rules. That way context drift shows up in review, next to the code that caused it.

RepoContext generates AGENTS.md from a verified scan — wire it into a scheduled job and your agents always read current context.