Keep AGENTS.md and CLAUDE.md from going stale

Developers keep asking the same thing: after a refactor or folder move, the agent still follows the old instructions, recreates deleted directories, or runs a command that no longer exists. The cause is simple. An instruction file reads as authoritative, so the agent has no reason to doubt a line that stopped being true weeks ago. Nobody reviews it the way they review code.

The fix is not a bigger file. It is a smaller one that you check on a schedule. Here is a routine that takes about ten minutes.

Why files go stale

• Paths and commands rot. A rule that names src/legacy/api/ or npm run test:unit stays in the file after the folder or script is gone.
• Lessons get appended, never removed. If agents or people add “things learned” at the end of every session, the file becomes a pile of notes that partly contradict each other.
• Several tools read one file. When Cursor, Claude Code and Codex all load the same AGENTS.md, a rule written for one of them can mislead the others.
• Size hides the problem. In a 600-line file nobody notices one dead line, and the model has more lines to weigh against each other.

A ten-minute staleness check

1. Check every path. List the paths and file names the file mentions and confirm each still exists. A quick way is to pull anything that looks like a path and test it, as in the snippet below.
2. Run every command. Each build, test and lint command in the file should work from a clean checkout. If you would not paste it into a new teammate's terminal, remove it.
3. Look for contradictions. Search for “always” and “never”, and for rules about the same topic (formatting, test style, error handling). Two lines that disagree are worse than none, because the model has to guess which one wins.
4. Delete what the repo already enforces. If a linter, formatter or CI check catches it, the instruction file does not need to repeat it.
5. Weigh it. Paste the file into Clogmeter to see its token count, its share of a 32k, 128k or 200k context window, and any duplicate or conflicting rules it flags. Trim the highest-cost sections first.

Find dead paths in a few lines

This shell snippet prints any backtick-quoted path in AGENTS.md that does not exist in your repo. It is a rough filter, so expect to skim the output rather than trust it blindly:

grep -oE '`[A-Za-z0-9_./-]+/[A-Za-z0-9_./-]*`' AGENTS.md \
  | tr -d '`' | sort -u \
  | while read p; do [ -e "$p" ] || echo "missing: $p"; done

Habits that stop it coming back

• Update it in the same commit. If a change moves a folder or renames a script, the instruction file edit goes in the same pull request. Put that sentence in the file itself so agents follow it too.
• Keep it short enough to review. If a reviewer can read the whole diff in a minute, it actually gets reviewed.
• Give additions a bar. Only add a rule after the agent got something wrong twice. Write the rule once, in one place.
• Resolve disagreements immediately. When two tools or two people want different things, pick one rule and delete the other the same day.
• Re-check after big refactors. Treat a folder move or framework upgrade as a trigger to run the check above.

Quick check

Count the file with the AGENTS.md / CLAUDE.md token counter, or use the CLAUDE.md token counter if that is the file you maintain. Then run the full inspector for duplicates and conflicts.