AGENTS.md: What Works, What Costs, and Best Practices

These files are an instruction layer that supplies the project-specific tooling and conventions raw source code often leaves out. Over 60,000 repositories have adopted the format, but adding one is not a guaranteed win — whether it helps comes down entirely to how it was written.

The data from ETH Zurich shows that human-written context files provide a 4% performance boost in task resolution across benchmarks. However, LLM-generated files often lower success rates by 0.5% to 2%. The failure mode is almost always redundancy: auto-generated files tend to repeat information already in the repository, which adds noise and confuses the agent's reasoning.

Treat these files as a deliberate engineering tradeoff. They improve adherence to specific tools, but they also impose a 20% "tax" on every execution step in higher inference costs. Unless you are prepared to manually curate these files to fill the "information gap" in niche repositories, they are more likely to bloat your CI budget than solve your bugs.

What is AGENTS.md and what problem does it solve?

Coding agents face a "context gap" when working on niche or internal repositories. Standard benchmarks like SWE-bench use popular, well-documented projects, but the ETH Zurich AGENTbench focuses on "less-popular" repositories where the code is often the only source of truth. In these cases, agents struggle with non-obvious tooling decisions, specialized CI setups, and project-specific conventions that aren't obvious from a raw file tree.

The core problem is that agents often hallucinate library usage or fail to run the correct test runner because the developer's intent isn't written down anywhere a machine can read it. AGENTS.md is a "README for agents," cutting tool errors and environment setup failures. It tells the agent exactly which commands are valid, preventing it from guessing whether to use pip, poetry, or uv.

These files only help when the information is additive. If a repository already has thorough documentation, an AGENTS.md often becomes a burden by repeating data the agent can already see. Its job is to bridge the gap for agents working where documentation is thin or non-standard.

How coding agents read and apply AGENTS.md

Technically, the file is injected directly into the agent's context window at the start of a session (as CLAUDE.md for Claude Code or AGENTS.md for Codex/Qwen). The agent treats these instructions as high-priority system rules. This works well for tool selection: mentioning the package manager uv in a context file increases its usage from near-zero to 1.6 times per task instance.

Agents map their internal tools—Read, Write, Grep, and Edit—to the instructions you provide. Give it an exact pytest command string, and the agent adapts its "Run Test" intent to match your project's environment.

The danger here is "Process over Outcome." Agents are instruction-following systems; if you give a detailed codebase overview, the agent will put following that "map" ahead of finding the bug. Data shows that giving overviews does not help the agent reach the target file faster; it just pushes the agent to go through more of the repository to follow the instructions, often at the cost of the actual fix.

What should an AGENTS.md file contain?

Your content should focus only on gap content: the non-obvious requirements a reader can't discover via ls or a standard README.

• Tooling Choices: explicit commands for uv, pytest, or ruff.
• CI/Test Configs: non-default flags or environment variables required for successful runs.
• Non-default Conventions: specific architectural patterns or libraries to avoid.

Hard requirement: do not include directory trees or codebase overviews. 100% of LLM-generated files in the ETH Zurich study included these, and they were the main cause of performance drops.

Sample AGENTS.md (human-curated style)

# Agent Guidelines
 
## Tooling & Commands
 
- Always use `uv` for dependency management.
- Test runner: `uv run pytest tests/ --cov`
- Linter: `ruff check . --fix`
 
## Project Conventions
 
- We use `pytest` fixtures instead of the `mock` library.
- New functions must include type hints (PEP 484).
- Database: CI requires `DATABASE_URL=sqlite:///:memory:`.
 
## Forbidden Actions
 
- Do not use `pip` or `venv` directly.
- Avoid modifying files in `legacy/` unless explicitly directed.

Does AGENTS.md actually help agents code better?

Data from AGENTbench and SWE-bench Lite show that while human-written files provide a 4% improvement, LLM-generated files cause a 0.5% to 2% performance drop.

The cost of this context is steep and unavoidable:

• 20% increase in total inference cost per task.
• 14% to 22% increase in reasoning tokens (for models like GPT-5.2 and GPT-5.1 mini).
• 2–4 additional steps taken per task resolution.

This results in the "Exploration Paradox." Agents with context files search more files and generate more reasoning, but they don't reach the target file any faster than agents with no context. Detailed repository overviews often distract the agent, leading it to prioritize "complying with the map" over identifying the root cause of an issue.

Best practices for writing AGENTS.md

The "write for the gap" principle is your primary defense against the performance penalties found in the ETH Zurich study.

• Kill the overviews: directory trees and README mirrors are active hazards. Agents can run ls or find; do not waste context tokens on what they can see for themselves.
• Be minimal: instructions should focus only on what is not discoverable through code analysis.
• The pruning hack: if you must use an agent to generate a context file, delete all existing documentation files (.md, /docs) from the repository first. In testing, this improved auto-generated file performance by 2.7% by forcing the agent to extract non-obvious tooling decisions rather than paraphrasing existing text.

How to get started with AGENTS.md

Most agent interfaces use initialization commands like /init. For example:

# General interface pattern
claude-code /init

References

• AGENTS.md — Open Format for Guiding Coding Agents
• A Complete Guide to AGENTS.md — AI Hero
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• Does AGENTS.md Actually Help Coding Agents? — Elvis Saravia
• Does AGENTS.md Actually Help Coding Agents? (Notes) — Youssef Hosni
• How I Write My AGENTS.md Files — Best Practices (YouTube)
• Improve Your AI Code Output with AGENTS.md (YouTube)