If you use AI coding agents on a real repo, you've probably noticed they keep making the same avoidable mistakes — running the wrong test command, touching files they shouldn't, inventing a table name that doesn't exist. AGENTS.md is the fix, and it's quietly becoming a cross-tool standard. But there's a catch most people miss: a lazily written AGENTS.md can actually make your agent worse. So it's worth doing properly.
What it actually is
AGENTS.md is a machine-readable context file that agent runtimes load straight into the model's context at the start of a session. It's not documentation for humans — it's a runtime instruction set. The nice part is that it's not tied to one tool: Cursor, Codex, Claude Code, Copilot, Devin, Windsurf, and Gemini CLI all understand it. Write it once, and every agent you throw at the repo benefits.
And it measurably works — developer-written files have been shown to improve task success and cut agent-generated bugs meaningfully. Emphasis on developer-written; more on that below.
The sections that earn their place
Not everything belongs in here. The high-value sections are the ones that encode things the model cannot infer from the code alone:
- Commands — the single highest-ROI section. Exact, copy-pasteable commands with the right flags and environment variables. Don't make the agent guess how to run your tests; give it
pytest tests/ -v --cov=srcverbatim. - Boundaries — a three-tier model that saves you from disasters: always do (safe, no confirmation needed), ask first (needs your sign-off), never do (hard stops — and name the specific tables, files, or actions, not vague principles).
- Project structure — a flat map of what lives where, with purpose annotations like "
src/transforms/contains pure functions only." Not an architecture essay. - Code style — show it as actual code snippets, not prose. "Prefer this pattern" with an example beats a paragraph describing it.
- Testing — framework, mocking strategy, coverage threshold.
- Git workflow — branch naming, commit format, PR rules.
If your agents touch data, add explicit sections for certified data sources, PII columns named by name, and who to escalate to. Specificity is the whole game.
The rules that keep it useful
This is where most AGENTS.md files go wrong. A few hard rules I'd follow:
- Keep it short. Aim for under ~150 lines. Long files bury the important instructions.
- Don't LLM-generate it. This one surprised me: generated files have been found to perform worse than having no file at all in most tested cases. The value comes from a developer encoding real, specific project knowledge — exactly the thing a model can't invent about your repo.
- Don't duplicate your README. Repeating what's already documented just inflates the context (and cost) for no benefit.
- Cut the generic advice. "Write clean code" helps nobody. Every line should tell the agent something specific to this project.
What to leave out
Generic engineering principles. Anything already in your docs. Architectural overviews with no file pointers. Prose descriptions of code style. Table names you're recalling from memory. And, again, LLM-generated filler.
Placement and precedence
Start with one AGENTS.md at the repo root. Only add subdirectory files when a part of the codebase genuinely needs different rules — and remember they override the root file rather than merging with it. If you're on Claude Code specifically, you can layer a CLAUDE.md for Claude-only overrides on top, but AGENTS.md is the right primary standard for a multi-tool setup.
The habit that makes it durable
The failure mode for these files is drift — six months on, the agent is hallucinating a column name because the file describes a schema that changed. The most robust teams regenerate the factual sections (data sources, ownership) from a real source of truth in CI rather than hand-maintaining them. For a code repo, the lightweight version of that discipline is simply: treat AGENTS.md as part of the codebase, review changes to it in PRs, and update it the same day you change the thing it describes.
Get this file right and every agent you use gets sharper for free. That's a rare deal in tooling — take it.
