Your AGENTS.md file might be making your AI coding agent slower and more expensive — even if you wrote it carefully. A February 2026 benchmark study from ETH Zurich tested 138 real-world software engineering tasks and found that a poorly constructed context file doesn’t just fail to help — it actively hurts performance. Learning how to write AGENTS.md the right way means understanding not just what to include, but what to ruthlessly leave out. This guide walks through the research findings, a practical four-category framework for what belongs in the file, and a minimal template you can adapt today.
The Uncomfortable Research Finding Every Developer Needs to See First
Before you get into templates and tactics, you need to know what the research says — because it contradicts most of the advice you’ll find online.
In February 2026, researchers at ETH Zurich published a benchmark study (Gloaguen et al., arXiv:2602.11988) evaluating AGENTS.md files across 138 real-world software engineering tasks, using Claude Code (Sonnet 4.5), OpenAI Codex (GPT-5.2 and GPT-5.1 mini), and Qwen Code (Qwen3-30b-coder). They wanted a simple answer: do these context files actually help?
The results were uncomfortable:
- Human-written AGENTS.md files improved task success rates by ~4% on average — but increased inference costs by up to 19%
- LLM-generated files (the kind produced by `/init` commands) reduced success rates by 2–3% compared to providing no file at all — while still raising costs by more than 20%
- GPT-5.2 (Codex) showed a 22% increase in reasoning token usage whenever an AGENTS.md file was present, regardless of its quality
The takeaway isn’t “don’t use AGENTS.md.” It’s that every line you put in that file carries a cost, so make sure it’s earning its place.
Why Auto-Generating Your AGENTS.md with /init Is a Mistake
Most tools offer a quick-start path: run `/init` (or the equivalent), let the AI scan your repo, and watch it produce a comprehensive AGENTS.md in seconds. It feels efficient. The file looks thorough — sections on architecture, coding conventions, testing, PR format.
It also makes your agent measurably worse.
The ETH Zurich study found that LLM-generated context files reduce task success rates by 2–3% compared to having no file at all. The problem isn’t that AI can’t write coherent instructions. The problem is what it chooses to write.
When an AI generates your AGENTS.md, it does what feels natural: it reads your codebase, synthesizes what it finds, and produces a narrative summary. That summary is accurate. It’s also almost entirely redundant with what the agent would have discovered by reading your README, your docs folder, and your source tree.
You’re paying 20%+ more in inference costs for the agent to be told things it already knows.
The `/init` shortcut is tempting precisely because it produces something that looks useful. Don’t let the comprehensiveness fool you. Length isn’t quality here — specificity is.
The Redundancy Problem: Why Most AGENTS.md Files Just Repeat Your README
Here’s the core insight from the research, and it’s worth sitting with: agents already read your documentation.
Before an agent touches a single line of code, it typically reads your README, scans your docs folder, checks your `pyproject.toml` or `package.json`, and infers project conventions from existing code. By the time it reaches your AGENTS.md, it already has significant context.
An AGENTS.md that says “This is a Python web application using FastAPI and SQLAlchemy, organized into modules for auth, core, and utils” isn’t helping. The agent read your README. It saw your imports. It knows.
The ETH Zurich team tested this directly. They stripped all other documentation from the test repositories — no READMEs, no docs folders — and re-ran the benchmarks. In that stripped environment, LLM-generated AGENTS.md files improved performance by 2.7%. The same files that had been actively hurting agents became mildly helpful once the redundancy was removed.
That single experiment explains the entire problem. When the context file is the only source of information, it adds value. When it competes with a project’s existing documentation, it adds noise.
This means the question to ask about every line in your AGENTS.md isn’t “is this accurate?” It’s: “Is this information available anywhere else the agent will read?” If yes — cut it.
The 4-Category Framework: What to Actually Put in Your AGENTS.md
Given what the research shows, your AGENTS.md should only contain information the agent genuinely cannot infer from the rest of your repository. That narrows things down considerably — but it also makes the task much clearer.
Four categories are worth including:
1. Non-standard tooling commands
If your project uses `uv` instead of `pip`, `bun` instead of `npm`, or a custom Makefile target instead of a standard test runner, document it explicitly. The agent has no way to infer your tool preference from the codebase itself.
“`
# Use uv for all Python package operations — never pip
# Run tests with: uv run pytest tests/ -x
“`
2. Non-obvious test runners or validation steps
Standard projects run `pytest` or `npm test`. Anything that deviates from convention belongs here — custom test environments, required environment variables, test database setup, or steps that must happen in a specific order.
3. Bespoke PR and commit conventions
If your team uses a non-standard commit message format, requires issue numbers in PR titles, or has specific branch naming conventions that aren’t in a CONTRIBUTING.md, include them. If there’s already a CONTRIBUTING.md that covers this, don’t repeat it — skip it entirely.
4. Repo-specific gotchas with no other documentation
This is the most valuable category. These are the things that bite new contributors (and agents) precisely because they’re undocumented:
- “Never modify `src/generated/` — these files are auto-generated by the build step”
- “The `legacy/` directory uses Python 2 syntax and is excluded from linting”
- “Database migrations must be run manually with `make migrate` after schema changes”
A 5-line context file targeting your project’s actual quirks will outperform a 2,000-word auto-generated overview that restates the README.
Notice what’s missing from this framework: architecture overviews, directory structure maps, technology stack descriptions, coding philosophy sections. The ETH Zurich study specifically found that codebase architecture overviews and directory maps do not help agents navigate — they add noise and trigger unnecessary exploration steps across all three tested agents.
How to Use Directory Nesting to Scope Instructions (Like OpenAI Does With 88 Files)
One of the most underused features of AGENTS.md is the directory hierarchy system. The rule is simple: the closest file to the code being edited wins.
If you have an AGENTS.md at your repo root, it applies globally. But if you also have one inside `packages/billing/`, that file takes precedence for everything in that directory. Instructions don’t automatically merge — the most local file governs.
This matters more than it sounds. A monolithic root-level AGENTS.md trying to cover every subpackage’s quirks becomes exactly the kind of bloated, redundant file the research warns against. The solution is the same one OpenAI uses in their own monorepo: distributed, scoped files.
OpenAI’s monorepo contains 88 individual AGENTS.md files spread across nested subdirectories (per OpenAI Codex documentation). Each file is small, specific, and relevant only to the code it lives beside. The root file covers global tooling conventions. A `services/payments/` AGENTS.md covers payment-specific testing requirements. A `scripts/` AGENTS.md covers how to run deployment tooling safely.
Practical guidance for when to split files:
- Split when a subdirectory has its own tech stack, build system, or testing setup
- Split when a module has gotchas that only matter for that module
- Keep at root only truly cross-cutting conventions that apply everywhere
- Watch the 32 KiB cap — OpenAI Codex silently drops content beyond 32,768 bytes, so a bloated root file can truncate without warning
Smaller, scoped files are cheaper to process and far easier to maintain. When something changes in the payments module, you update one small file — not hunt through a 1,500-word monolith.
AGENTS.md vs. CLAUDE.md vs. copilot-instructions.md: One Source of Truth
If you use multiple AI coding tools — Claude Code, Cursor, GitHub Copilot, and Windsurf — you’ve probably felt the friction of maintaining separate config files for each. CLAUDE.md for Claude Code. `.cursorrules` for Cursor. `copilot-instructions.md` for Copilot. They inevitably drift apart.
AGENTS.md is the cross-tool universal standard. With over 60,000 public repositories already using it (per the Agentic AI Foundation / Linux Foundation), it has the widest support across tools. The right architecture isn’t one file per tool — it’s one source of truth that the others defer to.
The practical pattern:
AGENTS.md — your canonical context file. All non-redundant, high-signal instructions live here.
CLAUDE.md — if Claude Code has Claude-specific behaviors to configure (hooks, MCP server settings), put those here. For everything project-related, reference AGENTS.md rather than duplicating it.
.cursorrules — scope this to Cursor-only UI preferences. Don’t re-document project conventions already in AGENTS.md.
copilot-instructions.md — same principle. Defer to AGENTS.md where possible.
The goal is to never update the same project convention in more than one file. When you fix a gotcha in AGENTS.md, every tool benefits automatically.
One caution worth noting: always review AGENTS.md files before using them from third-party repositories. Security researchers have identified “Rules File Backdoor” attacks that use hidden Unicode characters to inject malicious instructions into agent system prompts. Treat third-party AGENTS.md files with the same scrutiny you’d apply to any third-party code.
How to Write AGENTS.md: A Minimal, Annotated Template
Here’s a template built on the four-category framework. Notice what isn’t here: no architecture overview, no directory map, no “this project uses Python” preamble.
“`markdown
# Project Context
Tooling
# Use `uv` for all Python operations — never `pip` or `pip3`
# Install dependencies: uv sync
# Run tests: uv run pytest tests/ -x –tb=short
# Lint: uv run ruff check . && uv run mypy src/
Testing Notes
# Integration tests require a running Postgres instance.
# Start it with: docker compose up -d db
# Use TEST_DATABASE_URL env var (see .env.example — never commit .env)
PR Conventions
# Commit format:
# Types: feat, fix, chore, docs, test, refactor
# PR titles must reference a GitHub issue: “feat(auth): add OAuth2 (#123)”
Gotchas
# Never modify src/generated/ — rebuilt by `make codegen`
# The legacy/ directory uses Python 2 syntax; exclude from linting
# After schema changes: uv run alembic upgrade head
“`
That’s roughly 130 words. Compare that to a typical `/init`-generated file that runs 800–2,000 words and covers architecture, file structure, coding philosophy, and a dozen generic conventions your agent already knows.
A few things to notice about this template:
- Every line answers a question the agent couldn’t answer from existing docs
- Tooling commands are exact, runnable strings — not descriptions of what the tools do
- “Never modify `src/generated/`” protects against a costly class of agent mistakes
- The PR format section only exists because it’s not already in a CONTRIBUTING.md
Adjust this for your project. If you have nothing to say in a category, omit the section entirely. A shorter file is almost always better.
How to Keep Your AGENTS.md From Going Stale
An outdated AGENTS.md is worse than no file. If you document `pip install` as the install command, then migrate to `uv` and forget to update the file, your agent will use the wrong tool — and it won’t question it, because you explicitly told it not to.
A few practices that help:
Treat AGENTS.md like a config file, not documentation. Review it when you change tooling, refactor directory structure, or add a major dependency with non-standard conventions.
Add an AGENTS.md check to onboarding. When a new team member gets confused by something project-specific, ask: “Is this in AGENTS.md? Should it be?”
Keep a “last reviewed” comment at the top. Something like `` gives future-you a clear signal when the file might be out of date.
Delete sections when they become redundant. If you write a proper CONTRIBUTING.md that covers your PR conventions, remove those conventions from AGENTS.md. The goal is always to have each piece of information in exactly one place.
The file should stay small because it stays current. That’s the discipline that makes writing AGENTS.md less about writing and more about editing.
Write Less, Gain More
The research makes the tradeoff explicit: how to write AGENTS.md comes down to one discipline — include only what the agent cannot infer from anywhere else. A 4% performance gain is available with a well-crafted file, but a 2–3% penalty waits for anyone who leans on auto-generation or comprehensive documentation.
Start with the four categories: non-standard tooling, test runners, bespoke conventions, and project-specific gotchas. Keep each file scoped to the directory it lives in. Pick AGENTS.md as your single source of truth and let tool-specific files defer to it.
Then resist the urge to add more. Your agent’s performance — and your token bill — depend on it.
Audit your current AGENTS.md against the four-category framework. If a line restates something already in your README or docs, delete it. Then run a task your agent has struggled with before and see what changes.