中文EN
← Deep Research
Deep Research · Deep dive

The README for Agents: Are Context Files Infrastructure or Cargo Cult? (Deep Dive)

This is the deep-dive edition · read the plain-language edition →
TL;DR
AGENTS.md has won the standards war on facts (LF neutral hosting; native consumption by Cursor/Copilot/VS Code), but recognition is asymmetric and the symlink remains the universal adapter; the four vendor guides agree neatly — with zero control groups. The first controlled studies fight each other: the efficiency gain (−28.64% wall-clock, −16.58% tokens, p<0.05) is the only statistically tested effect; on success rates three studies contradict one another, and the flagship negative study's directional numbers were struck down by methods audit (no inferential statistics, single sampling, effective n=12); the formatting folklore shows no detectable compliance effect — task identity and session depth dominate. llms.txt is the multi-source closed case for adoption ≠ consumption (97% zero requests); context files are now a PoC-backed attack surface. Closes with a six-step rollout playbook and ten testable claims.
3 rounds · 2 famous numbers struckonly tested win: −28.64% timesuccess rates: 3 studies at war10 testable claims

Evidence in this essay is graded across three verification rounds. Rounds one and two: 35 load-bearing claim groups, 3 votes each, checked for fidelity to source (verbatim checks, re-derived arithmetic; 0 of 105 votes overturned a group, 30+ corrections — including the exposure of the pseudo-citation "keep CLAUDE.md under 10k words," which exists in no official document; the real figure is "under 200 lines"). Round three added two seats for the 6 single-source empirical groups: a contradiction-search seat (hunting for independent-team, independent-data measurements for or against) and a methods-audit seat (hostile review with kill authority). Round three changed this essay's conclusions: 2 groups' load-bearing numbers were struck down by audit (the AGENTbench directional success-rate deltas are false precision; the "2,303-file census" percentages sit on the wrong denominator), the cost direction is directly contradicted between independent measurements, and 3 groups were upgraded to multi-source status. Tags: 【multi-source】= independent teams and data agree; 【single-source, audited】= one measurement, faithfully quoted, survived methods audit; 【contested】= independent measurements point opposite ways; 【checked】= mechanics verified verbatim against official docs/source code; 【vendor】,【field】,【unverified, source】as literal. Fidelity-to-source ≠ true-of-the-world — for single-source claims the former is the verification ceiling, which is exactly why the tiers exist. A source index closes the essay.

0. An obviously-correct sentence, and three facts that refuse to cooperate

Through 2025 and 2026, every coding-agent vendor has been telling you the same thing: give your repository a "README for agents" — AGENTS.md, CLAUDE.md, .cursor/rules, copilot-instructions.md; different names, same logic. An agent enters your codebase cold every session; write down the build commands, the directory map, and the house rules, and it stops wasting time rediscovering them. The logic sounds so obviously correct that "your repo still has no AGENTS.md?" has become a new flavor of technical shaming.

Adversarial verification turned up three facts that refuse to cooperate:

First, the controlled evidence started fighting itself the moment it appeared. ETH Zurich's multi-agent evaluation claims context files don't generally improve success rates while raising inference cost by 20%+; a second team's paired Codex experiment measured −28.64% median wall-clock and −16.58% output tokens with the file present; a third team measured LLM-generated guidance files raising resolve rates by 2.8–7.5 percentage points. All three are preprints — and, more to the point (§4), none of their directional success-rate numbers passed this essay's methods audit without being downgraded. 【contested】

Second, the folk wisdom about how to write these files — keep them short, put key instructions at the top — failed its first randomized test across the board. In a factorial experiment spanning 1,650 Claude Code sessions, none of four structural variables — file size, instruction position, single-file vs. nested architecture, contradictions between adjacent files — had any detectable effect on agent compliance. 【single-source, audited】

Third, the loudest adjacent standard, llms.txt, has a measured consumption rate of approximately zero. Ahrefs' server-log analysis of 137,210 domains found that 97% of published llms.txt files received not a single request in May 2026 — with at least four independent measurements pointing the same way. 【multi-source】

None of this means context files are useless — the essay will get to the only statistically supported benefit found so far (efficiency) and to production-grade files that survive verbatim verification. But it does mean this: nearly all "best practice" in this field is vendor narrative, the independent evidence is brand new, and the first studies disagree not only with the vendors but with each other. The standing rule from When Code Gets Cheap applies: a number without a control group gets its denominator checked before it gets quoted.

1. How to read the numbers: three evidence tiers, four standing caveats

Every load-bearing claim below carries a grade:

Four standing caveats: (1) this field moves fast — everything is stated as of 2026-07-15; (2) the controlled studies are not inter-convertible (different task sets, agents, metrics); (3) two conflict-of-interest declarations: Chroma (the context-rot report) is a vector-database company whose product story benefits from "curated context beats long context," and the AGENTbench paper's co-authors include the commercial agent-evaluation startup LogicStar.ai; (4) "context files" here means in-repo instruction files for coding agents — llms.txt (a website-facing convention) gets its own section precisely because the two keep getting conflated.

2. The standards war: AGENTS.md wins on facts, but recognition is asymmetric

The spec itself is almost contentless by design: plain Markdown, no required fields, no schema — officially a "README for agents." It began as an OpenAI-led, multi-vendor effort (Codex, Amp, Google Jules, Cursor, Factory) and moved in December 2025 to neutral hosting under the Linux Foundation's newly formed Agentic AI Foundation, a founding project alongside MCP and goose. 【checked】 "Cross-vendor" is the official framing; independent coverage reads it as "OpenAI-led, then donated." Both are true, depending on whether you read the charter or the commit history.

Adoption has a checkable but loose denominator. The official site claims "used by over 60k open-source projects" and links a GitHub search you can re-run yourself. Our verifiers re-ran it: the query executes, but it path-substring-matches (files inside directories named agents.md/ get counted) and counts files, not projects. For calibration, InfoQ's August 2025 figure was 20k repositories. 【checked】 The growth is real; the precise number is a marketing denominator.

The nesting rule is the most substantive part of the standard: the AGENTS.md closest to the edited file wins, and explicit user chat instructions override everything. Monorepos are told to put one file per package; the site cites "the main OpenAI repo has 88 AGENTS.md files" as proof of practice (a self-reported number for a private repo — unauditable). Note that the precedence rule lives in the website FAQ, not in formal spec text, and actual behavior is implementation-dependent — not every tool auto-loads nested files. 【checked】

Mutual recognition is asymmetric; the symlink remains the only reliable interop mechanism. Checked tool by tool (docs plus source code):

The official migration path is rename-plus-symlink: mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md; Aider and Gemini CLI interoperate via their own config options. 【checked】 Convergence is real, but "one file everywhere" is achieved with filesystem tricks, not with standards recognition.

3. The vendor guides, reconciled: three points of consensus, zero control groups

Put the official best-practice pages of Anthropic, OpenAI, GitHub, and Cursor side by side and the consensus is striking — strikingly uniform, which should itself raise an eyebrow, because none of the four attaches a controlled experiment.

Consensus one: keep it short. The four differ in rhetoric and enforcement. Anthropic is loudest — the docs say verbatim: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!", and recommend interrogating every line with "would removing this cause an error?" The official size figure lives on the memory page: "target under 200 lines per CLAUDE.md file" — the "under 10k words" figure circulating online does not exist in any official document. OpenAI Codex enforces by mechanism: all project docs share a default hard cap of 32 KiB (source constant DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024), silently truncated beyond that, with real GitHub issues from users who found out the hard way. GitHub's auto-generation prompt hard-requires "no longer than 2 pages." Cursor recommends under 500 lines per rule. 【checked】

Consensus two: executable commands first. GitHub officially analyzed 2,500+ public agents.md files and distilled six core areas — commands, testing, project structure, code style, git workflow, boundaries — with the advice to put fully-flagged executable commands in an early section (not just tool names) and to phrase boundaries as always do / ask first / never do. This is the largest public pattern analysis available, but GitHub published no methodology or dataset, and parts of the article concern Copilot custom agents rather than plain root files — grade it as vendor pattern-mining, not a controlled result. GitHub's official prompt for auto-generating copilot-instructions adds one genuinely good requirement: every build/test/lint command must be validated by actually running it before it is written down. 【checked】

Consensus three: nested files for monorepos, closest file wins. All four agree on the semantics (see §2). Anthropic's version: at launch, Claude Code loads the CLAUDE.md from the working directory and every parent; subdirectory files load on demand when files there are read. For large codebases the recommendation is a two-level split — root file for repo-wide rules, per-directory files for local conventions — with an explicit warning that a single root file "tends to either grow to cover every subsystem's conventions, costing context on instructions unrelated to the current task, or stay too generic to be useful." 【checked】

The divergence is mechanical: Cursor rules carry glob/always-apply metadata while AGENTS.md has no schema; Copilot distinguishes three file types; Codex enforces brevity in bytes while others advise it; and Anthropic alone offers an exit ramp — migrate conventions out of always-loaded CLAUDE.md into on-demand skills and plugins, candidly admitting that per-directory files at scale suffer governance failure: "conventions drift, files go stale, and no one owns the root." 【checked】

Anthropic's content checklist deserves its own record, since it answers what to write rather than just how much: include what the agent cannot guess — bash commands, non-default code style, test instructions, repo etiquette, project-specific architecture decisions; exclude what code inspection reveals, detailed API docs, and anything that changes frequently. Emphasis markers like IMPORTANT / YOU MUST may raise adherence — a claim, once again, shipped without data. 【vendor, checked】

4. The evidence, part I: does writing one actually help? Three studies at war, and only the efficiency number carries a statistical test

The first half of 2026 produced three controlled studies that answer "does it help?" head-on. They disagree with each other — and after this essay's third-round methods audit and contradiction search, less survives than meets the eye. One at a time:

Exhibit one: the AGENTbench comparison (arXiv 2602.11988, ETH Zurich + LogicStar.ai, Feb 2026) — the most famous, the weakest numbers. The authors combine SWE-bench Lite (300 tasks, 11 popular Python repos, LLM-generated context files) with their own AGENTbench (138 real PR tasks from 12 niche Python repos, all carrying developer-committed files, filtered from 5,694 PRs; unrelated to the 2023 Tsinghua benchmark of the same name). Three agents, four model configurations. Its claims: LLM-generated files reduce resolution rates across the board (−0.5pp SWE-bench Lite, −2pp AGENTbench); developer-written files manage only +4% (and nothing for Claude Code); cost rises ~20%; with READMEs deleted, LLM-generated files flip to +2.7%.

This essay's methods audit struck down every directional success-rate number in it as evidence, on five grounds: the paper contains no inferential statistics whatsoever (no confidence intervals, no significance tests — confirmed by full-text search); each instance is sampled exactly once, and with n=138 binary outcomes the minimum detectable difference is roughly 8–10 percentage points — reporting ±2–4pp "directions" is false precision; the 138 instances cluster in 12 repositories, so the effective sample size for the developer-written-file claim is 12, not 138; the benchmark was built with the very agent under evaluation (Codex/GPT-5.2 filtered tasks, rewrote descriptions, generated tests from the golden patches — circularity); and "helpful" is operationalized solely as single-shot pass rate plus cost, while the advertised benefits of context files (style adherence, convention compliance, maintainability) go unmeasured. What it reliably supports is one weak sentence: no large success-rate effect was observed in this setup. 【contested; directional numbers struck by audit】

Exhibit two: the paired Codex experiment (arXiv 2601.20404, Lulla et al., JAWs@ICSE 2026) — the narrowest numbers, and the only ones with a statistical test. Ten repositories, 124 real PR tasks, each run twice with and without the developer-committed AGENTS.md: median completion time 98.57s → 70.34s (−28.64%), median output tokens 2,925 → 2,440 (−16.58%), Wilcoxon signed-rank p<0.05, comparable task completion. Secondary analysis shows the mean-level savings concentrate in a few runs that would otherwise have thrashed — a guardrail against worst cases, not a uniform accelerator. Audit ruling: real-but-weak, survives narrowly scoped. 【single-source, audited】 Scope: one agent (gpt-5.2-codex), small PRs (<100 lines, ≤5 files), single root files, associational phrasing by the authors themselves.

Exhibit three: Probe-and-Refine (arXiv 2606.20512, Shepard & Albrecht, Williams College, Jun 2026) — a direct counterpunch to exhibit one. On SWE-bench Verified, with repos' normal documentation intact, an LLM-generated guidance file (tree-sitter repo map plus one-shot generic guidance) raised mean resolve rate from 25.5% to 28.3% (+2.8pp), and iterative refinement pushed it to 33.0% (+7.5pp; four independent trials, refined-vs-unguided p<0.001). That is a direct measurement in the opposite direction of "LLM-generated files reduce success" (caveat: the guidance file contains a structured repo map, unlike typical /init output). 【single-source, audited】

The cost direction is also at war: ETH reports +20–23% with files present; Lulla measures −16.58% tokens and −28.64% wall-clock. Task regimes (benchmark issue-solving vs. small real PRs), file provenance (LLM-generated vs. developer-committed), and agents all differ — no adjudication is currently possible, and at least one survey explicitly flags the two papers as reaching "opposite conclusions." 【contested】

The honest synthesis of all three:

  1. The efficiency gain (time and tokens) is the only effect in this literature that carries a statistical test — but it is one measurement, and another study points the opposite way on cost. Treat it not as law but as the default expectation worth re-measuring on your own repos.
  2. On success rates, the honest evidence state is "undetermined": three preprints in mutual contradiction, each underpowered or externally limited. Neither "files don't help" nor "files help" currently qualifies as a conclusion.
  3. "Value comes from non-redundant information" is demoted from finding to hypothesis — but it has two independent weak signals pointing the same way (the docs-removal ablation flip, itself audit-struck as a number, and Shepard's +2.8pp static guidance). It is the mechanism most worth testing next.

5. The evidence, part II: the how-to-write folk wisdom meets its first controlled test, and loses

On how to write the file, vendors and practitioners share a folklore: short, key items first, don't over-split, never contradict yourself. In May 2026 a factorial experiment (arXiv 2605.10039, Damon McMillan, single-author preprint) finally put those variables on the table: 1,650 Claude Code CLI sessions, 16,050 function-level observations, two TypeScript codebases, five tasks, primarily Sonnet 4.6, measuring compliance with one simple annotation instruction.

The results are uncomfortable for both camps:

The limits are equally severe, and the audit seat added two more: the dependent variable is a single zero-cost, unambiguous annotation instruction — a single-stimulus design that cannot distinguish "structure has no effect" from "this particular instruction is salient wherever you put it"; plus one agent ecosystem, the 25–500-line range, a single unreviewed author. From the contradiction seat: as of 2026-07, no replication, no direct-measurement contradiction, no substantive expert critique — unchallenged single-source, which is not the same as multi-source. But the tension with the vendor line still deserves stating plainly: Anthropic says bloat causes ignored instructions; the only controlled test to date finds no size effect within 25–500 lines.

Does that kill the "keep it short" advice? No — but it relocates the argument. The defensible chain is context budget and context rot. Chroma's technical report (July 2025; self-published, vendor interest declared) tested 18 LLMs and found models do not use context uniformly: performance degrades non-uniformly as input grows even on simple tasks; on a cleaned 306-prompt LongMemEval subset, a focused prompt (~300 tokens of relevant excerpts) consistently beat embedding the same information in a ~113k-token average full history; distractors — related but irrelevant content — amplify the degradation with length. This is one of the essay's few multi-source empirical results: non-uniform long-context degradation is independently measured by NoLiMa (Adobe, pre-dating Chroma), Du et al. (EMNLP 2025), and Databricks, and focused-beats-full by the LongMemEval authors themselves (ICLR 2025). 【multi-source】 Two audit caveats travel with it: the "focused" condition is an oracle-retrieval upper bound — the authors hand-extracted exactly the relevant excerpts, a line no practical retrieval system reaches, so it demonstrates the ceiling of precise context, not what casual pruning buys you; and the dose-response curves come mostly from synthetic tasks (NIAH extensions, repeated words), so extrapolation to real codebases takes a haircut.

The honest synthesis: "short" is soundly justified by cost and context budget (every line competes with the task's working memory, and long-context degradation is multi-source measured), not by "shorter files make agents more obedient" (unproven). Structure appears to matter little on the single-source evidence available; what you write, and how deep into the session the agent is, are the live variables.

6. The content census and the field evidence: what people actually write, and what they omit

The census: the first large-scale empirical study (arXiv 2511.12884, "Agent READMEs," Nov 2025) collected 2,303 context files from 1,925 repositories (root-level CLAUDE.md, AGENTS.md, copilot-instructions.md only — Cursor/Windsurf rules and subdirectory files excluded; "first" is the authors' own claim, with adjacent AIware 2025 work in the same season). Here a denominator correction that this essay's own first edition also fell for: the widely quoted percentages (implementation details 69.9%, architecture 67.7%, build/run commands 62.3%, security 14.5%, performance 14.5%) were NOT computed over the 2,303-file corpus — they come from a manually annotated subset of 332 CLAUDE.md files (out of 922 collected), with the sampling procedure undocumented in the paper. Quote them only with that denominator attached. 【single-source, audited; denominator restated】

The good news: the qualitative pattern is multi-source. An independent team (UFMG, arXiv 2511.09268) with an independently collected sample of 328 CLAUDE.md files and its own taxonomy reproduces the shape — architecture-type content ranks first (72.6%), and security/performance likewise fail to rank among common content. "Commands and maps dominate; non-functional requirements are systematically absent" holds in both independent samples. On maintenance, the files "are not static documentation but complex, difficult-to-read artifacts that evolve like configuration code, maintained through frequent, small additions." 【multi-source (pattern); exact percentages single-source】

The field: four production files, checked verbatim against GitHub on 2026-07-15:

Their common shape confirms the 2,500-file vendor analysis: high-signal files are command-first, concretely prohibitive, and confined to what agents cannot guess. Datadog's frontend team adds a monorepo pattern — a root file acting purely as a router (workspace map, toolchain, routing rules, default safety constraints) with detail pushed into nested files for high-value/high-risk workspaces, iterated against a durable suite of 1–2 test prompts per common task across multiple agents — methodologically sane, but practitioner self-report 【unverified, source: Datadog engineering blog on dev.to】.

7. llms.txt: a closed case in the wrong direction

llms.txt keeps appearing next to AGENTS.md on "agent-era documentation" checklists, but their measured consumption could not differ more. It earns its own section because it demonstrates that adoption narratives and actual consumption can decouple completely:

The lesson is not "llms.txt is a scam" but a portable method: before writing any machine-facing documentation, verify that the machine in question actually reads it. AGENTS.md passes that test (VS Code loads it by default; Cursor and Codex consume it natively; Copilot supports it officially — all checkable in docs and source). llms.txt does not.

8. The security face: your README is now an attack surface

Agents consume context files as trusted instructions, not as data — and by 2026 that trust model has proof-of-concept attacks on record:

The supply-chain write path (NVIDIA AI Red Team). A malicious Golang build-time dependency detects Codex environments via the CODEX_PROXY_CERT environment variable, then writes a crafted AGENTS.md instructing Codex to inject a five-minute time.Sleep into every Golang main function — with stealth directives: never mention the change in PR descriptions, commit messages, or summaries, down to code comments telling AI summarizers not to mention it. The attack presupposes a compromised dependency (the attacker already executes code); NVIDIA frames it as a supply-chain risk dimension unique to agentic development. Disclosure timeline: submitted to OpenAI 2025-07-01; OpenAI acknowledged and declined changes, reasoning the attack does not elevate risk beyond what a compromised dependency can already do. Demonstrated on Codex only; .cursorrules, CLAUDE.md, and copilot-instructions.md are named as the same risk class (a class statement, not a demonstrated PoC). 【checked; blog publication date varies across indexes — first half of 2026】

The editor auto-injection path. Since v1.104, VS Code injects the workspace root's AGENTS.md into every chat request by default (chat.useAgentsMdFile; source code confirms include-unless-explicitly-disabled). Security vendor Prompt Security demonstrated the consequence: open a malicious repo, type a single character into chat, and the injected instructions can steer the agent toward data exfiltration. The taxonomy the attack maps to — OWASP's Top 10 for Agentic Applications 2026, ASI01 (Agent Goal Hijack) and ASI02 (Tool Misuse & Exploitation) — is real (published 2025-12-09); the mapping of this specific finding is the vendor's own. 【checked】 The key point: auto-inclusion is documented, by-design product behavior, not an undisclosed bug — which is exactly what makes it a stable attack surface.

For wider context — a 78-study meta-analysis reporting >85% attack success against state-of-the-art defenses under adaptive strategies, with four major coding platforms failing compound attacks 【unverified, source: arXiv 2601.17548】 — treat as directional only; it did not pass through our per-claim verification.

Three engineering consequences: treat context files in third-party repos as untrusted input (audit your editors' auto-load defaults); review context-file diffs like code (especially from automated PRs and dependency bots); restrict write access to AGENTS.md/CLAUDE.md in build environments (the NVIDIA write path).

9. The rollout playbook: a plan for your company's codebase

The preceding eight sections compress into an executable plan. Three design principles: do the cheap, verified things first; make every step measurable; treat vendor guidance as defaults, not truths. Every step carries its evidence grade.

Step 1 — Inventory (half a day). List the agents your teams actually use (this determines filenames and the interop matrix, §2 【checked】); map repo topology (monorepo?); score existing documentation quality — the highest-leverage step, because "value comes from non-redundant information" is the field's most promising mechanism hypothesis (two independent weak signals agree, §4): repos with excellent READMEs should expect little; documentation deserts should expect the most. Treat it as a hypothesis to confirm or refute with your own Step-5 measurements.

Step 2 — Pick the standard (one-time decision). Default: AGENTS.md as the single source of truth, plus a symlink for Claude Code (ln -s AGENTS.md CLAUDE.md); open the file by declaring it canonical and forbidding additions to other rule files (the Sentry pattern 【checked】). If your org is Claude-Code-only, use CLAUDE.md directly — just never double-maintain.

Step 3 — A minimum viable root file (1–2 hours per repo). Follow the verified high-signal shape: (a) executable commands with full flags, early in the file, each validated by actually running it (GitHub's own generation prompt requires this 【vendor】); (b) a 3–5 line directory map; (c) boundaries in three tiers — always / ask-first / never — with the largest blast radius first (Cloudflare's pnpm clause 【field】); (d) only what agents can't guess: naming law, non-standard toolchains, repo etiquette (Airflow's Dag/breeze clauses 【field】). Budget: start under 200 lines / 2 pages (vendor defaults; remember Codex's 32 KiB silent truncation 【checked】). Do not paste in the human README (both independent signals of the redundancy hypothesis point to "paraphrase = overhead"). Bulk-LLM-generating and committing files sight-unseen currently sits in contested territory — one study measured harm (its directional numbers failed audit), another measured gains (+7.5pp, p<0.001, with a repo-map-based iterative generator); the robust route is unchanged: /init for a first draft 【vendor】, human pruning, and Step-5 measurement as the acceptance gate.

Step 4 — Monorepo layering (as needed). Root file for global rules and routing; nested files only for high-value or high-risk packages, leaning on closest-file-wins semantics (spec + all four vendors 【checked】; "root as router" is Datadog practice 【unverified】). Guard against the governance failure Anthropic itself admits — drifting conventions, stale files, an unowned root 【vendor, checked】 — by writing an owner into every file.

Step 5 — Measurement and expectation-setting (2–4 week pilot). Report to management with honest expectations: the efficiency gain (time/tokens) is the field's only statistically tested effect, measured once, with one study pointing the other way on cost; the success-rate evidence is undetermined — which is why your pilot measurement isn't garnish, it is the only local ground truth you will get. Method: pick 1–2 pilot repos, build a small durable suite of 1–2 test prompts per common task, run before/after, record completion, wall-clock, tokens (the method is Datadog practice 【unverified】, but it is simply regression testing for documentation — cheap, and it removes the need to trust anyone's numbers, including ours). Put structural fiddling (position, splitting) last — the only controlled experiment found nothing there 【single-source, audited】.

Step 6 — Maintenance and security (steady state). Maintenance: context-file changes go through PR review; re-audit after major model releases (rules that patched an old model's limitation become pure overhead); optionally a Stop hook that proposes updates from session transcripts (all three are Anthropic guidance 【vendor】; that these files evolve like high-churn config code is the empirical observation 【single-source, audited】). Security: require review on context-file changes in CI, specifically intercepting writes to AGENTS.md from automated PRs and dependency bots (the NVIDIA path 【checked】); have security review each editor's auto-load defaults 【checked】. Finally: do not write an llms.txt unless you have verified that a consumer you care about actually reads it 【multi-source】.

Anti-patterns, all grounded above: pasting the full human README; committing wholesale LLM-generated files unreviewed; one giant root file serving a monorepo; preaching "shorter = more obedient" as established fact; running naked in the 14.5% club (no security boundaries at all); trusting third-party repos' context files.

10. Conclusion: ten testable claims

  1. The efficiency gain is the field's only statistically tested effect (−28.64% median wall-clock, −16.58% median output tokens, Wilcoxon p<0.05, single-agent paired experiment) — but one other study measures the opposite sign on cost; adjudication needs a third party re-testing both regimes under one setup. 【single-source, audited + contested】
  2. On success rates, the honest evidence state is "undetermined": the study claiming harm reports directions that are false precision (no inferential statistics, single sampling, effective n=12); the study claiming gains has p<0.001 but an atypical guidance-file format. Neither "doesn't help" nor "helps" qualifies as a conclusion yet. 【contested】
  3. "Value comes from non-redundant information" is the field's most testable mechanism hypothesis: two independent weak signals agree (the docs-removal ablation flip; +2.8pp from static generated guidance), neither at evidence grade. Directly testable by re-measuring hand-written files on well-documented repos.
  4. The formatting folklore is unproven: size (25–500 lines), position, architecture, and contradictions show no detectable compliance effect (size and conflict as Bayesian affirmative nulls; position and architecture possibly just underpowered); task identity and session position dominate. Single-stimulus design, no replication — awaiting a second team. 【single-source, audited】
  5. The sound argument for "short" is context budget plus multi-source long-context degradation, not obedience — noting the degradation experiments' "focused" condition is an oracle-retrieval upper bound; Codex's 32 KiB silent truncation makes the budget a hard constraint. 【multi-source + checked】
  6. AGENTS.md has won the standards war on facts (LF neutral hosting; native consumption by Cursor, Copilot, VS Code; a loose 60k+ adoption proxy) — but recognition is asymmetric, Claude Code remains a separate system, and the symlink is still the universal adapter. 【checked】
  7. Production-grade files converge: commands-first with flags, three-tier boundary rules, only the unguessable — four flagship repos verified verbatim, matching the 2,500-file vendor analysis. 【field + vendor】
  8. The systematic content gap is non-functional requirements (security/performance) — a pattern that holds in two independent samples (14.5% each in the 332 annotated CLAUDE.md files; UFMG's independent 328-file sample shows the same shape); note the exact percentages sit on the annotated-subset denominator, not "2,303 files." 【multi-source (pattern)】
  9. Context files are a demonstrated attack surface: supply-chain writes (NVIDIA PoC) plus default editor auto-injection (VS Code v1.104), mapping to OWASP ASI01/ASI02; review their diffs like code. 【checked】
  10. llms.txt is the closed case for adoption ≠ consumption: 8.8× growth coexisting with 97% zero-request rates (the latter agreed by at least four independent measurements) and no major AI consumer. Verify the reader exists before writing for it. 【multi-source】

Worth watching next: whether a third party adjudicates the three-way contradiction under a unified setup; a direct test of the non-redundancy hypothesis on well-documented repos; whether the within-session decay (OR = 0.944) survives a preregistered replication by a second team; and when the first real-world (non-PoC) context-file injection incident lands under the OWASP ASI labels.

Appendix: primary sources

Standard & spec: agents.md site and spec repo (github.com/agentsmd/agents.md) · Linux Foundation press release (Agentic AI Foundation, Dec 2025) · InfoQ (Aug 2025; the 20k-repo baseline)

Vendor documentation: Anthropic — best-practices, large-codebases, and memory pages at code.claude.com/docs · OpenAI — developers.openai.com/codex/guides/agents-md and the codex source (codex-rs/core/src/agents_md.rs) · GitHub — Copilot custom-instructions docs; github.blog, "How to write a great agents.md: lessons from over 2,500 repositories" (Matt Nigh, Nov 2025) · Cursor — cursor.com/docs/rules · VS Code — v1.104 release notes and microsoft/vscode source

Independent studies: Gloaguen, Mündler, Müller, Raychev & Vechev, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (arXiv 2602.11988, ETH Zurich / LogicStar.ai) · Lulla, Mohsenimofidi, Galster, Zhang, Baltes & Treude, "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" (arXiv 2601.20404, JAWs@ICSE 2026) · Shepard & Albrecht, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents" (arXiv 2606.20512, Williams College) · McMillan, "Instruction Adherence in Coding Agent Configuration Files" (arXiv 2605.10039) · Chatlatanagulchai et al., "Agent READMEs: An Empirical Study of Context Files for Agentic Coding" (arXiv 2511.12884) · Santos, Costa, Montandon & Valente (UFMG, arXiv 2511.09268; independent 328-file sample) · Hong, Troynikov & Huber, "Context Rot" (Chroma technical report, Jul 2025; independently corroborated by NoLiMa (Adobe), Du et al. (EMNLP 2025), Databricks, and the LongMemEval authors (ICLR 2025))

llms.txt audit: Ahrefs, "We Analyzed 137K Sites: 97% of llms.txt Files Never Get Read" (Jun 2026) · OtterlyAI own-site 90-day logs · Adobe AEM 1,000-domain LLM-bot event audit · Originality.ai llms.txt tracking study · John Mueller's Bluesky post (2025-06-17) and Search Engine Roundtable/Journal coverage · Chrome Lighthouse 13.3 agentic-browsing docs

Security: NVIDIA Technical Blog, "Mitigating Indirect AGENTS.md Injection Attacks in Agentic Environments" · Prompt Security, "When Your Repo Starts Talking" (vendor PoC) · OWASP Top 10 for Agentic Applications 2026 (ASI01/ASI02, Dec 2025) · arXiv 2601.17548 (prompt-injection meta-analysis; unverified)

Field files (verified verbatim 2026-07-15): AGENTS.md in getsentry/sentry, cloudflare/workers-sdk, apache/airflow, coder/coder · Datadog frontend engineering blog (dev.to; unverified)

Research materials and every verification verdict are archived in the research base (research/agent-readme/ in this repository: 35 load-bearing claim groups × 3 votes across rounds one and two — 105 votes — plus round three's 12 contradiction-search and methods-audit verdicts over the 6 single-source empirical groups, all on record, including the two audit strike-downs and every scope correction).