Treat AGENTS.md as production configuration. The useful question is not whether the file exists, but which rules the current runtime loaded and which observable behavior each rule requires.
1You edited an AGENTS.md that is not in the active loading path
Repositories can contain more than one instruction file. A fresh process is the strongest check because a running session may preserve older context.
Check
pwd -P
find .. -name AGENTS.md -type f -print
ls -l AGENTS.md
shasum -a 256 AGENTS.md
From the intended project directory, start a fresh read-only Codex session and ask:
Identify every instruction file loaded for this directory. Restate the five critical rules from AGENTS.md. Do not edit files.
Fix
Put the rules in the file and scope the runtime actually loads. Record the verified path and hash, then open a new session. If multiple instruction files apply, make their responsibilities and precedence explicit instead of copying the same rule into each file.
2The combined instruction text may exceed the configured document budget
The relevant value is the runtime's current configuration, not a universal number. The linked static auditor uses 32 KiB as a reference value only.
Check
find .. -name AGENTS.md -type f -exec wc -c {} \;
wc -c AGENTS.md
tail -n 80 AGENTS.md
Compare the result with the active Codex configuration and documentation. In the fresh session, ask it to restate a critical rule from the file's tail.
Fix
Remove repetition, keep critical instructions first, and increase a documented configuration value only when you have verified that the active runtime reads it. Re-run the tail-rule check after changing either the file or configuration.
3Rules overlap or contradict one another
A strong “always” and a strong “never” can share the same action without saying which condition wins. Duplicate long instructions also drift when one copy changes.
Check
grep -nEi '\b(always|must|required to|never|must not|do not)\b' AGENTS.md
sort AGENTS.md | uniq -d
find .. -name AGENTS.md -type f -print
Read the matching lines together, including any parent or nested rules files that the fresh-session check identified.
Fix
Add explicit conditions and a precedence rule so only one directive applies. Keep one canonical copy of a long instruction and refer to it from related sections.
4The instruction asks for an outcome but defines no evidence
Confident completion prose does not prove the change, and one generic success signal does not fit every tool.
Check
grep -nEi '\b(verify|validate|test|lint|typecheck|check|exit code|git diff --check)\b' AGENTS.md
grep -nEi 'DONE:|FAILED:|HUMAN_ACTION_REQUIRED:|acceptance criteria|completion (criteria|marker|means)' AGENTS.md
grep -nEi 'per-tool|per-agent|each (tool|agent|CLI)|completion marker' AGENTS.md
Fix
For each important task type, name the verification command and required evidence. Define completed, failed, unknown, and human-blocked states. When multiple tools are coordinated, record each tool's own completion marker and failure interpretation.
5A prohibition gives Codex no safe next action
“Do not do X” can correctly block an unsafe path while leaving the agent unable to proceed or report the real blocker.
Check
grep -nEi '^[[:space:]]*([-*][[:space:]]*)?(never|do not|must not|forbid)\b' AGENTS.md
For each result, look for an adjacent alternative such as stop, report, use a safe substitute, request human action, or state an exception.
Fix
Pair every important prohibition with a reachable safe action. For hard-to-reverse work, require an exact target inspection, a recovery path, and human approval where user-owned or external data is involved.
6The rule exists in prose but not in an execution path
A rule file can describe a test, guard, or publishing check that no script or person actually runs.
Check
grep -nEi '\b(always|automatically|now)\b|\b(is|are|gets?) (checked|verified|validated|enforced)\b' AGENTS.md
grep -rn '<rule-id-or-unique-phrase>' scripts/ automation/ tests/
Fix
Connect the rule to a hook, script, test, checklist owner, or terminal report field. If it remains manual, label it manual. Do not describe a prose-only control as automatic.
7AGENTS.md drifted after the last successful check
An out-of-scope edit can shrink or alter the file without making the unrelated task fail.
Check
git status --short -- AGENTS.md
git diff -- AGENTS.md
shasum -a 256 AGENTS.md
Fix
Pin the hash after a verified edit and review it after sessions that touch files. If the hash changed unexpectedly, inspect and restore the intended rules, then validate them in a new read-only Codex process.