CLAUDE.md and AGENTS.md: what the evidence says, plus a starter

Updated 2026-11-06

As of 2026-11-05. Vendor pages were re-read on that date and change often; recheck the linked page before relying on a detail. We summarise these sources and did not run any of the studies. Measured studies say repo-level instruction files did not reliably improve task success, and they added cost. Their clearest measured effect was changing which tools the agent used.

What measured studies found

• [measured] Gloaguen et al. (ETH Zurich / LogicStar), arXiv 2602.11988, submitted 2026-02-12, revised v3 2026-09-29: https://arxiv.org/abs/2602.11988. Across SWE-bench Lite (300 tasks, 11 Python repos) and a second set of 138 tasks from 12 repos, instruction files changed success by roughly -2 to +2.4 points, none significant, with results varying by model, and added about 20% to cost on average, a statistically significant rise. Python bug-fix tasks only.
• [measured] Naming a tool in the file changed tool use: uv was used 1.6 times per task when mentioned versus under 0.01 when not; repo-specific tools were used 2.5 times versus under 0.05.
• [measured, vendor-run] A Vercel Next.js 16 API suite reported 53% with no docs, 53% with a default skill, 79% with a skill plus explicit instruction, and 100% with a compressed docs index in AGENTS.md. The number of cases is not stated, and the evaluation was unreplicated and run by the vendor selling the approach.
• [measured] McMillan, arXiv 2605.10039, 2026-05-11: https://arxiv.org/abs/2605.10039. Across 1,650 Claude Code sessions and 16,050 function-level observations, file size, instruction position, and file layout had no detectable effect on whether instructions were followed, in this narrow test (two TypeScript codebases, one trivial annotation rule).
• [measured, descriptive] Chatlatanagulchai et al., “Agent READMEs,” 2025-11-17: https://arxiv.org/abs/2511.12884. Examined 2,303 context files from 1,925 repos.
• [measured] Jaroslawicz et al., “How Many Instructions Can LLMs Follow at Once?” (IFScale), 2025-07-15: https://arxiv.org/abs/2507.11538. Tested 20 models, with up to 500 keyword-inclusion instructions.

What to put in—and leave out

• [vendor] Put in: exact build, test (including one test file), lint, and typecheck commands; specific, checkable instructions; misleading code locations; decisions not represented in the repo; and corrections the team has had to repeat. Sources: https://code.claude.com/docs/en/best-practices and https://code.claude.com/docs/en/memory, read 2026-11-04.
• [measured] Put in: non-standard tools or facts the agent cannot discover, especially when explicitly naming a tool changes whether it is used.
• [vendor] Leave out: architecture tours, directory listings, and dependency lists; the agent can inspect the repo. The cited Anthropic pages also advise against all-caps emphasis and “keep going, don’t be lazy” instructions. Sources: https://code.claude.com/docs/en/memory and https://code.claude.com/docs/en/best-practices, read 2026-11-04.
• [measured] Codebase overviews appeared in 8 of 12 developer-written files and did not reduce the steps needed to reach files touched by a fix.
• [opinion] Don’t duplicate rules enforced by a linter; put always-required behavior in hooks or permission rules instead of relying on instruction text.

How each tool loads instruction files

[vendor / project site] AGENTS.md is plain Markdown with no required fields; nearest file wins, and an explicit chat prompt overrides files. The site reports 60,000+ projects using it, a self-reported, unverified figure. https://agents.md, read 2026-11-04.

[opinion] A shared AGENTS.md, a one-line Claude bridge (@AGENTS.md), and a Gemini context.fileName setting are a practical cross-tool pattern; keep the shared file under Codex’s 32 KiB cap and Claude’s 200-line advice.

Common failures

• [vendor] Instructions are context, not enforcement; move must-always-happen rules into hooks or permission rules.
• [vendor] Conflicting instruction sets can coexist in Copilot. Claude imports do not reduce context cost; paths inside code formatting are not imported. Symlinks can fail on Windows without Developer Mode, and edit tools will not write through them.
• [vendor] Claude Code can warn about oversized files; /doctor proposes trims, and /doctor prompt-audit (v2.1.283+) flags outdated, dangling, or contradictory instructions.
• [opinion] The starter files below are not yet tested.

Where sources conflict or leave questions open

• [measured] McMillan found no detectable effect from file size, instruction position, or layout; [vendor] Anthropic recommends under 200 lines, and [vendor] Cursor recommends under 500 lines per rule. These claims are left unresolved.
• [measured] The Gloaguen study found no significant task-success improvement overall; [measured, vendor-run] the Vercel evaluation reported 100% with its compressed docs index. Their results differ in setup and are not reconciled here.
• [not verified] The current status of Cursor's legacy .cursorrules file, and any size limits for Gemini CLI and Copilot.

Copy-ready starter files

These starter files are not yet tested. They follow the evidence above: only what the agent cannot work out from the code, commands first, one line per fact. Replace every placeholder in angle brackets. The Definition of done section makes the agent run checks on every task, which costs more: in the Gloaguen study, removing the testing section lowered cost significantly on one benchmark.

Base starter (AGENTS.md)

# <Project name>

<One sentence: what this is and who uses it.>

## Commands
- Install: <cmd>
- Run all tests: <cmd>
- Run one test file: <cmd path/to/file>
- Lint and format: <cmd>
- Typecheck: <cmd>
- Run locally: <cmd>   (needs <env var / service>; see <.env.example>)

## Definition of done
Run lint, typecheck and the tests for the files you changed. Report the result of each, with the failing output if any. Do not say "done" without running them.

## Conventions the code does not show
- <Use X helper for Y, never Z. Reason: ...>
- <Directory A is legacy but still live; do not copy its patterns into new code.>
- <Generated files in B: never edit; run <cmd> instead.>

## Gotchas
- <Thing that fails confusingly and the fix.>
- <Tests that need a service or key, and how to set it up.>

## Boundaries
- Always: <e.g. add a test for a bug fix.>
- Ask first: <schema changes, new dependencies, deleting files, anything that touches production or sends messages.>
- Never: <commit secrets; edit applied migrations; force-push; run destructive commands on shared data.>

## When unsure
Ask one specific question rather than guessing. State what you assumed if you proceed.

Claude Code bridge (CLAUDE.md next to it)

@AGENTS.md

## Claude Code only
- <Anything specific to Claude Code: e.g. which skills or hooks exist.>

Enforce the boundaries with settings rather than prose: permissions.deny for secret files and migrations, a Stop hook running typecheck and tests, a PostToolUse hook for the formatter. For Gemini CLI, set context.fileName in .gemini/settings.json to include AGENTS.md. Codex, Cursor and Copilot read AGENTS.md as is.

Solo founder, one product: add to the base starter

## Where things live
- <Customer-facing copy lives in X; never change pricing or legal text without asking.>
- <Deploy: how, and what must be true first.>
## Money and people
Never send email or messages, post publicly, spend money or change billing without explicit approval in this chat.

Small team, 2 to 10 people with several agents in parallel: add to the base starter

## Working in parallel
- One task per branch; branch name: <type/short-name>. Commit message: <format>.
- Do not touch files outside the task. If you need a change elsewhere, say so and stop.
- Before opening a PR: rebase, run the checks in "Definition of done", and paste their output in the PR description.
- Pull requests are reviewed by a human; do not merge.
## Shared state
- <Where the task list / decisions live and how to add to them.>

Monorepo

The root file holds only rules that apply everywhere. Each package gets one short file with its own commands and gotchas, without repeating root rules. In Claude Code, subdirectory files load on demand. In Codex, keep the sum from root to leaf under 32 KiB.

Cheap tests to run

[opinion] Use the cheapest capable model, a fixed set of 5 to 10 real past or synthetic tasks, a yes/no checking script, and at least 3 repeats per condition because runs are noisy.

• Load check: start sessions at the repo root and in a package subdirectory; confirm each tool loads the intended file. For Claude Code, use /memory and /context all; check that the bridge does not load AGENTS.md twice.
• Planted-fact test: add five harmless, checkable facts the agent cannot guess; ask five tasks that trigger them and score correct use with and without the file.
• Prune test: run the same ten tasks with no file, the starter, and the starter plus an architecture overview; compare pass rate, steps, and cost.
• Rule-by-rule ablation: remove one section at a time and check whether behavior changes; delete sections that change nothing.
• Drift test: use a task with 15 or more edits and compare compliance early and late with the file alone versus the file plus a checking hook.