Audit your AGENTS.md line by line and cut what the agent can already see

Audit the agent instruction file for this repository. I want a shorter file in which every remaining line changes what the agent does, plus the reason behind each cut.

The file: {{paste AGENTS.md, CLAUDE.md, .cursorrules or equivalent, in full}}
Nested instruction files: {{paths and contents of any in subdirectories, or "none"}}
Agents that read it: {{e.g. Codex, Claude Code, Cursor, Copilot coding agent}}
The repository: {{one or two sentences: language, framework and version, monorepo or single package}}
Commands that work today: {{install, build, test, lint and typecheck, exactly as you type them}}
Mistakes the agent keeps making here: {{the recurring failures that made someone add a line, or "not tracked"}}

Put every line of the file into one of five classes.

KEEP. A fact the agent cannot get from reading the code and would get wrong without being told: a non-standard command, a framework version newer than the agent would assume, a directory that must not be edited, an invariant no test enforces, a convention that contradicts the language default.

REWRITE AS A CHECK. A line that names a technique ("use TDD", "think step by step", "audit your work when done") where the intent behind it is real. Rewrite it as something the agent runs and reports before it says it is finished, with the command and what passing looks like. For example, "use TDD" becomes "before reporting done, run {{test command}} and quote the summary line; for each bug you fixed, name the test that failed before the fix and passes after it".

DELETE, DISCOVERABLE. Anything the agent learns from one read of the repository: a directory tour, a restatement of the README, a dependency list, an architecture summary the folder names already give away.

DELETE, NO BEHAVIOUR. Lines that do not change a single action: "be careful", "make no mistakes", "you are a senior engineer", "follow best practices".

VERIFY. A command, path or version that may be stale. Compare it with the commands I listed. Where they differ, flag the line and ask which is right instead of picking one.

Return, in this order:

1. A table with the line (shortened if long), its class, and one clause of reasoning.
2. The new file, grouped by the moment the agent needs each line (before editing, while editing, before reporting done) rather than by topic. Keep it under {{target length, e.g. 60 lines}} unless a KEEP line cannot be cut.
3. Each recurring mistake I listed, next to the line in the new file that addresses it. Where no line does, write one, and say whether a test, lint rule or CI check would enforce it more reliably than an instruction. A rule that tooling enforces does not need to live in this file.
4. Any two lines that contradict each other, including across nested files, and which one the agent will follow when the file closest to the edited code takes precedence.
5. Three tasks from this repository I can run once with the old file and once with the new one, comparing whether the task succeeded and how many tokens it took, before I commit the change.

Do not add a section because templates usually have one. A project overview, a tech-stack list or a code style heading stays only if it carries a KEEP fact.

Tip: Two 2026 measurements set the cut list. An ETH Zurich study (arXiv 2602.11988, 138 tasks from 12 repositories that already had developer-written context files) found that context files did not raise task success on average and raised inference cost by more than 20 percent, and that repository overviews did not help. A September 2026 run by Dan Luu put 26 instruction lines through Codex, 80 runs each, and "use test-driven development" scored below giving no test instruction at all, while lines describing a check helped. Run the old and new file on the same tasks before committing, and confirm the new file actually loaded, since Codex caps its instruction chain at 32 KiB by default.