I spent way too long writing the perfect AGENTS.md for one of my projects. Project structure, coding conventions, style preferences, the works. Three pages of carefully crafted instructions telling the agent exactly how to behave.
Then researchers from ETH Zurich published a study that made me rethink the whole thing.
The attention problem
They analyzed how AGENTS.md files affect coding agent performance. The headline number? About 4% improvement. Sometimes less. Sometimes negative.
The agents followed instructions just fine. That wasn’t the issue. The issue was focus.
More instructions means more steps to track. More constraints to satisfy. More context competing with the actual task. The agent starts optimizing for your rules instead of solving your problem.
And if you’re copying stuff from your README and docs into AGENTS.md, you’re just burning tokens on information the agent would find on its own in seconds.
What actually belongs there
The stuff that’s impossible to infer from the repo. That’s it.
Non-standard tooling. If you use bun instead of npm, or vitest instead of jest — say so. An agent will default to the obvious choice unless you tell it otherwise.
Hidden constraints. “Never overwrite files in generated/” or “always run migrations through the CLI, never raw SQL.” The kind of thing a new developer would break on day one because nothing in the code makes it obvious.
Build quirks. If your project has a weird setup step, an unusual environment variable, or a build pipeline that doesn’t follow conventions — that’s worth documenting.
What to leave out
Project structure. The agent will explore your repo faster and more accurately than you can describe it. Your hand-written directory tree is already outdated by the time you commit it.
Coding style. In any established codebase, the patterns are already there in the code. The agent reads existing files and mirrors them. A style guide in AGENTS.md just adds noise.
Vague platitudes. “Write clean, maintainable code” tells the agent nothing. What’s clean? What’s maintainable? Without specific, measurable criteria, you’re burning tokens on vibes.
Try cutting 80%
Disclaimer — the study was done on Python with a relatively small sample. Take the exact numbers with a grain of salt.
But the core insight tracks with what I’ve seen across Reddit and X. People trimming their AGENTS.md down to the bare essentials and noticing zero regression. Some say the output got better.
Strip yours down to the stuff the agent genuinely can’t figure out on its own. The non-obvious, the non-standard, the hard constraints.
Everything else is just you talking to yourself.