An AGENTS.md file can save a coding agent from rediscovering repository commands and constraints. It can also make every task carry instructions that do not apply. Both effects show up in research published in 2026.
One study reported lower runtime and output-token use when AGENTS.md was present. Another found that repository-context files tended to lower task success and raise reasoning cost. A third catalogued recurring configuration smells such as duplicated linter rules and bloated context.
The takeaway is not simply that short files are good or context files are bad. The studies changed different things and measured different outcomes.
The studies measured different outcomes
On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents compared 124 pull requests across 10 repositories with and without AGENTS.md.
With AGENTS.md, median runtime fell by 28.64% and output tokens by 16.58%. Both conditions produced relevant code changes, but the primary measures were time and output tokens rather than task correctness. The result does not establish that AGENTS.md improves success rates.
Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? evaluated repository tasks across multiple agents and models.
In that study, repository-context files tended to reduce task success and increase reasoning cost by more than 20%. Agents explored more files and ran broader tests, but irrelevant requirements could make the task harder to complete.
Configuration Smells in AGENTS.md Files examined 100 popular open-source repositories containing AGENTS.md or CLAUDE.md.
The researchers found Lint Leakage—copying linter configuration into instructions—in 62% of the sample. Context Bloat appeared in 42%, and Skill Leakage, where persistent instructions contained tool-specific procedures, appeared in 35%. These are prevalence figures for patterns defined by the authors, not measured performance penalties.
| Study | Files examined | Main measure | Reported observation | What it did not establish |
|---|---|---|---|---|
| Efficiency study | AGENTS.md | Runtime, output tokens | 28.64% and 16.58% reductions | Higher correctness |
| Context evaluation | Repository context files | Success, reasoning cost | Lower success trend, >20% cost rise | Every handwritten file is bad |
| Smell study | AGENTS.md and CLAUDE.md | Pattern prevalence | Context Bloat in 42%, among others | Performance cost of each smell |
The findings can coexist. Providing the repository layout and exact test command can reduce exploration. Adding unrelated policies can make an agent inspect unnecessary files and satisfy constraints that do not matter to the current task.
Official guidance gives root files a narrow role
OpenAI describes AGENTS.md as persistent repository context for Codex: naming conventions, non-obvious business logic, known quirks, dependencies, verification commands, and contribution rules are reasonable examples.
Anthropic describes CLAUDE.md as context loaded into sessions. Its guidance favors specific, concise instructions and suggests keeping each file below roughly 200 lines as a rule of thumb. Task-specific procedures can move into skills or path-scoped rules.
The 200-line figure is not a Claude Code product limit, and there is no evidence that the same number is optimal for Codex. What matters most is scope: root instructions should apply to most work in the repository.
What belongs in the root file
Good root-level candidates include:
- the default build, test, and formatting commands
- repository structure that is difficult to infer from code
- prohibitions that apply to every change
- verification required before completion
- project-specific mistakes agents repeatedly make
Rules are more useful when their trigger and verification are explicit. “Write clean code” is difficult to check. “When the API response schema changes, run pnpm test:contract” tells the agent both when the rule applies and how to verify it.
## Verification
- When an API response schema changes, run `pnpm test:contract`.
- When adding a database migration, verify the rollback path.What to move out of the root file
Review these items first when a context file has grown:
- material duplicated from
package.json, formatter, or linter configuration - procedures used only for one deployment or directory
- generic programming advice and official tool tutorials
- stale paths and commands
- repeated versions of the same rule
- abstract requirements with no observable check
Codex can narrow scope with nested AGENTS.md files. Claude Code can use path-scoped rules or skills. Splitting a file only helps if the loading scope becomes narrower; importing every fragment on every task preserves the same context cost.
Decide by scope, not line count
AGENTS.md can reduce discovery work and still lower success when it adds irrelevant requirements. Current research does not identify one universally optimal length.
Prioritize information the code cannot reveal, repeated project-specific mistakes, and verifiable commands. Load task procedures only where they apply. To judge whether the file helps, compare similar tasks by success, runtime, token use, and unnecessary exploration—not by line count alone.
Sources
- On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
- Configuration Smells in AGENTS.md Files
- How OpenAI uses Codex
- Introducing Codex
- Claude Code: How Claude remembers your project
- Claude Code usage limits vs context limits