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

> What the data says about AGENTS.md context files: the 4% gain, the 20% cost tax, and how to write one that helps repository-level agents.

Source: https://camnangai.com/en/for/developers/agents-md-best-practices  
Published: 2026-06-12

An AGENTS.md (or CLAUDE.md) is a repository-level context file designed to steer coding agents
  like Sonnet-4.5, GPT-5.2, and Qwen3-30b.

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](https://arxiv.org/pdf/2602.11988v1) 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.

I read that as a tradeoff you budget for, not a free upgrade. These files 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.

![Illustration of an AGENTS.md file acting as a guide that steers a coding agent working inside a repository.](https://camnangai.com/articles/agents-md-best-practices/01-infographic-en.webp)

## 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](https://github.com/eth-sri/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.

![Diagram of how a coding agent loads AGENTS.md into its context window and selects the right tools.](https://camnangai.com/articles/agents-md-best-practices/02-en.webp)

Agents map their internal tools (Read, Write, Grep, 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.

![What belongs in an AGENTS.md file: gap-content categories like tooling, CI configs and non-default conventions versus the directory-tree overviews to leave out.](https://camnangai.com/articles/agents-md-best-practices/03-en.webp)

- **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)

```md
# 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.

Put those two numbers side by side and the arithmetic is ugly: a 4% ceiling on success bought with a 20% bill, and that is the good case, where a human wrote the file.

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.

![Performance comparison: human-written files add 4% success while LLM-generated files drop up to 2%, alongside a ~20% rise in inference cost.](https://camnangai.com/articles/agents-md-best-practices/04-en.webp)

## Best practices for writing AGENTS.md

Writing for the gap is what keeps a context file on the right side of the ETH Zurich numbers, and almost every failure in that study came from ignoring it.

- **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:

```bash
# General interface pattern
claude-code /init
```

> **Warning**
>
> Never ship an auto-generated file without editing it. Manual curation is the required second step: prune the redundant README content the agent copied in, and add the execution rules only the maintainer knows.
>

## References

- [AGENTS.md — Open Format for Guiding Coding Agents](https://agents.md/)
- [A Complete Guide to AGENTS.md — AI Hero](https://www.aihero.dev/a-complete-guide-to-agents-md#what-goes-where)
- [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/pdf/2602.11988v1)
- [Does AGENTS.md Actually Help Coding Agents? — Elvis Saravia](https://nlp.elvissaravia.com/p/does-agentsmd-actually-help-coding)
- [Does AGENTS.md Actually Help Coding Agents? (Notes) — Youssef Hosni](https://substack.com/@youssefhosni95/note/c-221467923)
- [How I Write My AGENTS.md Files — Best Practices (YouTube)](https://www.youtube.com/watch?v=6w88NVf2_lY)
- [Improve Your AI Code Output with AGENTS.md (YouTube)](https://www.youtube.com/watch?v=KEK_WcSTiuE&t=189s)
