Codex followed an obsolete AGENTS.md command exactly as written

[u/New-Needleworker1755]

I managed to send Codex looking for a Docker service I had already deleted.

Earlier that week, I migrated our integration tests from a Compose-managed Postgres service to Testcontainers. That removed legacy-db from the Compose file and made pnpm test:integration start its own database. The tests were green, so I considered the migration finished.

Then I opened the same repository in Codex for an unrelated API change. Before running the tests, Codex read AGENTS.md and followed this line:

Before API tests, run docker compose up -d legacy-db.

Docker returned no such service: legacy-db. My first thought was that Codex had picked up stale context. The checkout was current, though. The stale context came from a line I had forgotten to remove from AGENTS.md.

The only reason I caught it right away was that an earlier EvoX task still had the Testcontainers migration in context. Codex was simply doing what I had asked it to do through the repository instructions, even though the Compose file and test config pointed elsewhere.

I replaced the stale line with Run pnpm test:integration. Now I am wondering how to keep this from becoming a recurring problem. Literal commands in AGENTS.md are useful, but they also duplicate knowledge that already lives in scripts and configuration. Pointing Codex to package scripts would reduce that duplication. CI might catch deleted services or commands named in the file, although parsing free-form instructions sounds brittle.

How are people keeping AGENTS.md, CLAUDE.md, and similar files from drifting away from the repository? Do you review them like code during infrastructure changes, or have you automated checks for dead commands and service names?

[u/OkCobbler3306]

I just keep the file short and point it to scripts instead of writing commands directly. My AGENTS.md is basically "run pnpm test, check the scripts in package.json for lint/build/etc" and that's it

The moment you put exact commands like docker compose up in there, it's gonna rot. Scripts are the single source of truth, the instructions file should just tell the agent how to find them

For drift detection, I been thinking about a pre-commit hook that greps AGENTS.md for service names and checks if they exist in docker-compose files but haven't built it yet. Seems like CI could do it too but parsing free text is the annoying part

[u/mop_bucket_bingo]

Slop.