Every coding agent you point at your repository now looks for the same file first. Claude Code, OpenAI's Codex CLI, Cursor, Aider, Gemini CLI, GitHub Copilot, Windsurf, and Amazon Q all read AGENTS.md natively as of early 2026. In December 2025 the format was donated to the Agentic AI Foundation under the Linux Foundation, which effectively settled the format wars: this is the README for agents, and it is not going away.
That makes AGENTS.md the highest-leverage file in your project. It is also the one most teams get wrong. The instinct is to ask the agent to generate it, then keep stuffing rules in until the file is a thousand lines of "best practices." The data says that approach actively hurts you.
Auto-generated files perform worse than no file
The counterintuitive finding from 2026's context-engineering research is that an LLM-generated AGENTS.md gives negative returns. Measured across coding tasks, auto-generated files reduced task success rates by roughly 0.5 to 2 percentage points while raising inference cost more than 20 percent. You pay more tokens to get worse output.
Human-curated files flip the sign: a deliberately written file improved task success by about four percentage points over having none. The difference is not the format or the length. It is whether a person decided each line earned its place.
The mechanism is straightforward once you think about how agents consume the file. Every line in AGENTS.md is loaded into context on every task. A generic rule like "write clean, maintainable code" costs tokens, displaces more useful context, and tells the model nothing it does not already assume. Bloat is not neutral. It dilutes signal and crowds out the few instructions that actually change behavior.
Keep it sparse, exact, and obviously useful
The job of AGENTS.md is to encode what an agent cannot infer by reading your code. It already knows idiomatic TypeScript. It does not know that your CI rejects PRs unless you run pnpm lint --fix first, or that the legacy/ directory is frozen and changes there need a migration ticket. Write down the second category and skip the first.
A useful file usually fits on one screen and covers a short list of things:
- The exact build, test, and lint commands, written so they can be copy-pasted and run. "Run the tests" is useless;
pnpm test --filter webis actionable. - Conventions that are not obvious from the code, such as which package manager is canonical, how environment variables are loaded, or where generated files live so the agent does not edit them by hand.
- Hard constraints and landmines: directories that are off-limits, APIs that are deprecated internally, the one service that must not be touched without a feature flag.
- How to verify work before declaring it done, because an agent that knows your acceptance check will run it.
If a line is not a command, a convention, or a constraint, question whether it belongs. Aspirational prose about code quality is the first thing to cut.
Treat it like code, because it is
AGENTS.md lives at the repository root and gets version-controlled like any source file. The discipline that follows from that is the part teams skip.
When you introduce a new convention, update AGENTS.md in the same pull request. A reviewer who approves "all database access goes through the repository layer" should also see that rule land in the agent's instructions, because otherwise the next agent-authored PR will violate it and you will blame the model. The file drifts the same way comments drift, and a stale instruction is worse than a missing one: it confidently points the agent in the wrong direction.
For monorepos, the format supports nested files. A root AGENTS.md carries the shared rules, and a package can ship its own to override or extend them. Agents read the nearest file, so package-specific quirks stay local instead of polluting the global context that every task pays for.
A practical test for any line: would a new senior engineer joining the team need to be told this, and would they be annoyed if they were not? If yes, it belongs. If a competent person would already know it, the model does too.
A minimal starting point
Resist the urge to scaffold something elaborate. Start with the commands you actually type every day, the two or three conventions a newcomer always gets wrong, and the one directory nobody is allowed to touch. Commit it, then add a line only when you watch an agent make a mistake the file could have prevented. That feedback loop, observe a failure then encode the fix, produces a file that earns its tokens.
The reason this works is the same reason the auto-generated approach fails. Curation is the value. The format is open and the parsing is trivial; what the agent cannot do is decide which of your project's thousand facts are the ten that matter. That judgment is yours, and for now it is one of the more durable things a developer brings to an agent-assisted workflow.