This is the condensed edition of the deep dive of the same name. Every key number went through three rounds of independent checking (105 fidelity-to-source votes, plus 12 contradiction-search and hostile methods-audit verdicts — the audit struck down two widely circulated numbers, and the contradiction search surfaced studies that flatly disagree). For the full arguments, evidence tiers, and sources, read the deep dive.
For the past year or two, every AI coding vendor has been saying the same thing: give your codebase a "README for AI" — OpenAI calls it AGENTS.md, Anthropic calls it CLAUDE.md, Cursor and Copilot have their own names. The logic sounds airtight: an AI agent enters your repo cold every single session, so write down the build commands, the directory layout, and the house rules, and it stops wandering. "Your repo still doesn't have an AGENTS.md?" is fast becoming a new flavor of technical shaming.
What the logic is missing is a control group. We fact-checked every piece of primary evidence we could find, and the results are more interesting than the slogan.
The first half of 2026 produced three with-vs-without controlled studies, and they contradict each other: an ETH Zurich team says success rates don't rise and costs go up ~20%; a second team's paired experiment measured 28.64% lower median time and 16.58% fewer output tokens with the file present (the only number of the three that carries a statistical significance test); a third team measured LLM-generated guidance files raising resolve rates by 2.8–7.5 percentage points.
We ran a hostile methods audit on all three. Result: the most famous one (ETH) had its success-rate numbers struck down — no statistical tests anywhere in the paper, every task run exactly once, an effective sample of just 12 repositories; at that precision, a ±2–4-point "direction" simply cannot be read off.
So the honest summary: nobody currently knows whether these files move success rates; the only benefit left standing is saved time and tokens — and even that has been measured exactly once. Use that framing with your boss: worth trying, worth measuring yourself, no capability miracles promised.
There's a whole scripture of file-writing rules online: keep it short, put important things at the top, don't split into too many files, never contradict yourself. Someone finally ran a randomized experiment (1,650 real agent sessions): file size, instruction position, single vs. nested files, presence of contradictions — none of the four had any detectable effect on whether the agent obeyed. For size and contradictions, the "no effect" even carries affirmative statistical support — it's not just "we couldn't tell."
What actually predicts obedience: which task it is, and how deep into the session the agent is — with every additional piece of work, the odds of following your instruction slip a little further. Which line of the file an instruction sits on doesn't matter; which item of the session the agent is on does.
So does "keep it short" survive? Yes — but for a different reason. Not "shorter files are obeyed better" (no evidence), but every line you write competes with the agent's working memory for the actual task — long-context degradation is a measured phenomenon, and OpenAI's Codex silently truncates everything past 32 KB, so beyond that point your prose is invisible anyway.
We verified several big production repos' files verbatim against the originals; the pattern is remarkably consistent:
pnpm — never use npm or yarn" (otherwise an agent corrupts the whole monorepo's lockfile).And one cautionary tale: llms.txt (the AI index file for websites, often recommended alongside AGENTS.md) — 97% of deployed files received zero requests in a full month, and Google says on the record that it doesn't use them. Before writing any machine-facing document, confirm the machine actually comes to read it.
Agents execute context files as instructions, not as text. That means: whoever can write your AGENTS.md can command your agent. NVIDIA's red team ran the full demo — a malicious dependency rewrites AGENTS.md at build time, directs the agent to plant a backdoor, and adds stealth clauses like "do not mention this change in the PR description." Separately, VS Code now injects your repo's AGENTS.md into every chat request by default — worth remembering before you open a stranger's repository.
So: context-file changes go through code review — especially ones arriving via bots and automated PRs — and when you open a third-party repo, treat its instruction files as untrusted content.
And remember the state of this field: plenty of vendor advice, very few controlled experiments — and the first controlled experiments side neither with the vendors nor with each other. Use vendor guidance as defaults. Use your own measurement as the judge.