Almost every serious team using AI coding agents has an AGENTS.md file. It’s become a default best practice: put project context, conventions, and instructions in a single file at the root of the repo, and your agent will pick it up and work better. The idea is sensible. The execution, it turns out, usually isn’t.
An ETH Zurich study published in February 2026 tested context files systematically across hundreds of real-world GitHub issues using four different coding agents. The headline finding: in 5 out of 8 tested configurations, LLM-generated AGENTS.md files reduced task success rates compared to having no context file at all. They added 2.45 to 3.92 extra reasoning steps per task. They increased inference costs by 20-23%. Human-curated files outperformed LLM-generated ones by roughly 4 percentage points on the AGENTbench benchmark.
We’ve spent months writing context files and the research is now clear: most of them are making our agents work harder, not smarter.
Why Agents Are “Too Obedient”
The research team identified what they call the “obedience trap.” Coding agents are trained to follow instructions. When an AGENTS.md file exists, agents try to comply with it — even when the instructions are unnecessary, redundant with what the agent could figure out itself, or actively counterproductive.
A typical AGENTS.md includes a codebase overview, directory structure explanation, naming conventions, testing guidelines, CI/CD instructions, and style rules. For a human joining the team, this is useful onboarding material. For an agent, it’s mostly overhead.
The problem is that agents are already good at discovering file structure on their own. The ETH Zurich study found that “codebase overviews and directory listings did not help agents navigate faster” — agents simply explore the repo themselves more efficiently than they can process a written description of it. Reading a manual listing consumes reasoning tokens and adds cognitive overhead that slows the agent down.
When you tell an agent “tests are in the /tests directory,” it spends tokens processing that instruction. Without the instruction, it would just look for the tests directory. The instruction isn’t harmful in isolation, but an AGENTS.md full of such instructions creates compounding overhead.
What LLM-Generated Files Get Wrong
Many teams generate their AGENTS.md using an LLM: “summarize this codebase and create a context file for AI coding agents.” The ETH Zurich results show why this backfires.
LLM-generated files are verbose. They try to be comprehensive. They include information about every directory, every configuration choice, every convention — because that’s what comprehensive documentation looks like. But comprehensiveness is the wrong goal for agent context. An agent doesn’t need to know everything about the codebase; it needs clear signals about the few things it can’t figure out itself.
LLM-generated files are also often redundant with what’s already in the codebase. If your naming conventions are enforced by a linter, telling the agent about naming conventions is redundant — it will see the linter feedback anyway. If your test runner is defined in package.json, the agent can read that file. Writing it again in AGENTS.md means the agent processes the same information twice, and when the two sources disagree (they will, eventually), the agent has to resolve the conflict.
What Human-Curated Files Do Right
The research found that human-curated context files outperformed LLM-generated ones across all four tested agents. The pattern in effective human-curated files:
They describe what agents can’t figure out from the code itself. Business logic context, architectural trade-offs that aren’t obvious from the implementation, known gotchas, and constraints that exist outside the codebase (external service behaviors, deployment peculiarities, historical decisions). This is information that a new human teammate would need a conversation to learn — not something discoverable by reading files.
They’re short. The study found diminishing returns beyond a few hundred tokens of context. A 50-line AGENTS.md consistently outperformed a 500-line one. The best-performing files focused on 3-5 critical facts rather than trying to document everything.
They specify behaviors, not facts. “Always run the integration test suite before submitting a PR” is more useful than “the integration tests are in /tests/integration.” The first tells the agent what to do; the second tells it something it would find anyway.
They use specific, unambiguous language. “Do not modify files in /legacy” is more effective than “the legacy directory contains older code that should be handled carefully.” Agents take instructions literally; vague qualifiers create ambiguous signals.
The Four Structural Variables That Matter
The ETH Zurich paper identifies four variables that account for most of the performance difference between effective and ineffective context files:
- Length — shorter is better, with a cliff around 500 tokens where performance starts dropping
- Specificity — concrete behavioral instructions outperform general descriptions
- Redundancy — information the agent can get from the codebase itself hurts, not helps
- Instruction conflict — when context file instructions conflict with what the agent observes in the code, it adds resolution steps; eliminate conflicts by not duplicating what’s already encoded
A Practical AGENTS.md Template
Based on the research findings, an effective AGENTS.md for a typical backend service looks something like this:
# Agent Context
## Critical constraints
- Do NOT modify files in /legacy — these are third-party integrations with no tests
- Do NOT change database schema files without creating a migration in /migrations
- The service runs in a multi-tenant context — user data isolation is enforced by the TenantContext middleware; always verify it's in scope for data queries
## External behaviors that aren't obvious from code
- The payment processor (Stripe) has a 5-second timeout; retries must use exponential backoff with jitter
- The feature flags service caches values for 60s; tests that rely on flag values must account for this
## Run before submitting
- `make lint && make test-unit` must pass
- For changes to /api/v2/* also run `make test-integration`That’s it. No directory listing. No architecture overview. No style guide. Those are all either discoverable from the code or better enforced through tooling.
When to Not Have an AGENTS.md At All
The research suggests that for simple, well-structured codebases where conventions are consistently enforced by tooling, the optimal context file is no context file. The overhead of processing instructions — even short ones — only pays off when the instructions encode information the agent genuinely can’t get elsewhere.
The right question isn’t “what should I put in AGENTS.md?” It’s “what does this agent genuinely need to know that it cannot discover on its own?” If that list is short, your AGENTS.md should be short. If the list is empty, consider deleting the file.
Measuring Whether Your Context File Helps
If you’re maintaining an AGENTS.md, measure its impact. This is easier than it sounds:
- Run the same set of tasks with your current AGENTS.md
- Run the same tasks with a minimal AGENTS.md (3-5 critical constraints only)
- Run the same tasks with no AGENTS.md
- Compare: task success rate, steps per task, and token cost
Most teams that do this measurement find their current AGENTS.md is net negative. The honest follow-up: delete it, rebuild it from scratch starting with only the constraints that failed in the no-context run.
The ETH Zurich result isn’t that context files are bad. It’s that bad context files are bad, and most context files are bad. The fix is not more detail — it’s ruthless curation of what the agent genuinely needs.
Thuận Lương is a Tech Lead with 15+ years of experience in .NET, cloud architecture, and AI systems. He writes about lessons from building real production systems.