AGENTS.md: What It Is, and Whether It Actually Helps

AGENTS.md is one Markdown file, sitting at the root of a repository, that tells a coding agent what a new teammate would otherwise have to ask about out loud: the command that actually starts the app, the test that has to pass before a change ships, the two or three files nobody should touch without a second thought. It reads like a README written for a different audience. The format asks for nothing beyond headings and plain sentences, with no YAML frontmatter or proprietary schema to learn, so any agent can open the file and follow it the way a person would. That’s also why it spread fast: Codex, Cursor, Jules, Gemini CLI, and dozens of other tools all read the same file, so a team doesn’t maintain one instruction set per vendor.

The open question is whether reading it helps. A study out this year says usually not, and the answer has more to do with what a rule actually says than with whether the file exists at all. Writing one well is still one of the cheapest fixes for an AI-built app that gets harder to change every week: it costs an afternoon, not a rewrite.

What is AGENTS.md, and why did it need to exist

Before AGENTS.md, every agent read something different. Claude Code looked for CLAUDE.md. Cursor read .cursorrules, then later a folder of .mdc files. Aider, Windsurf, and half a dozen others each wanted their own filename in the same spot, so a repository that supported four tools carried four near-duplicate instruction files, and the moment one of them fell out of sync nobody noticed until an agent did the wrong thing confidently. AGENTS.md, now stewarded by the Agentic AI Foundation under the Linux Foundation, is the fix for that specific problem: one file, one place, and the format is deliberately boring. There’s no required section list and no enforced ordering, so a five-line file and a two-hundred-line one are both valid, and the only real constraint is that an agent parses it the way it parses any other page of text.

Which tools actually read AGENTS.md

Coverage is wider than most guides let on, but it isn’t universal, and the one gap that actually matters for a lot of teams is Claude Code.

That list runs to more than twenty tools on the format’s own site, and OpenAI’s own repository, by the same source, carries 88 separate AGENTS.md files across its subprojects, one per package rather than one giant root file. Claude Code is the visible exception, and Anthropic’s own wording on it is specific enough to quote directly rather than paraphrase. Reading the same file is only the first column, though, and what each of those tools hands you at ship time scores the rest of them.

AGENTS.md vs CLAUDE.md: do you need both?

You don’t need two files that say the same thing twice, and Anthropic says so directly. Claude Code’s own documentation states it flatly: “Claude Code reads CLAUDE.md, not AGENTS.md.” The same page gives the fix in two lines. Either a symlink, ln -s AGENTS.md CLAUDE.md, which works everywhere except Windows without admin rights, or a one-line import at the top of CLAUDE.md: @AGENTS.md, with anything Claude-specific added underneath it. Both point every tool at one source of truth instead of two files quietly drifting apart every time someone edits only the one they had open.

The real decision is narrower than “AGENTS.md versus CLAUDE.md” makes it sound: whether you have anything genuinely Claude-specific to say. Nothing to add means symlink and stop maintaining two files. Something to add, a note about when to use plan mode, a path where you want Claude to ask before editing, means the import keeps that addition in one place while the shared rules still live in AGENTS.md for every other tool that reads it.

Do AGENTS.md files actually help?

A team of researchers at ETH Zurich tested that question directly rather than assuming the answer, in a paper first posted in February 2026 and revised that June: coding agents working through established SWE-bench tasks paired with LLM-generated context files, plus a separate, purpose-built collection of real repository issues paired with the context files those repositories had already committed themselves, once with the file present and once without, across multiple models and agents. Their finding, in their own words: providing a context file “does not generally improve task success rates, while increasing inference cost by over 20% on average,” a result the paper states plainly holds “across different LLMs, coding agents, and for both LLM-generated and developer-committed context files.”

The paper’s own explanation for why is the useful part. Agents follow the instructions in a context file closely; that isn’t in dispute. What doesn’t help is the other half of what most onboarding advice recommends: a repository overview, a tour of the folder structure, a summary of the architecture. Agents already reconstruct that from the code faster than a paragraph can describe it, so a file that spends its first half doing that is paying real tokens for something the agent didn’t need explained. The discussion this produced on Hacker News split roughly the way you’d expect: one camp read a single-digit percentage gain as marginal and not worth the extra cost, another called even that gain a “must-have” once you count the mistakes it prevents on a real, messy codebase rather than a benchmark task. Both sides were arguing about the same paper. Neither side was wrong about the number; they disagreed about what it’s worth.

A rules file helps exactly as much as its lines are checkable, and hurts the moment they turn into vague prose fighting the agent’s own context window for space.

AGENTS.md best practices: how to write the lines worth keeping

How to write an AGENTS.md line worth keeping comes down to one filter, simpler than most guides make it sound: a line earns its place by being checkable. Either the thing it describes happened, or it didn’t, and something downstream can tell the difference. “Write clean, maintainable code” fails that test outright; there’s no way to look afterward and say whether it was followed. “Never touch webhook.ts without the signature test passing” passes it, because the test either ran green or it didn’t, and the agent’s own tool output settles the argument.

One of my own production apps makes the point better than a benchmark could. It’s a WhatsApp AI-agent platform, one of the five of my own apps that went through the same audit, and every route on its server carried rate-limiting middleware except one: the inbound message webhook, the exact route that triggers a paid OpenAI call on every text a stranger sends it. The other routes got protected because someone remembered to ask for it explicitly. The AI route got missed because nobody wrote down that it needed asking about at all. In the AxonBuild audit corpus, that’s not a one-off: 16 of the 18 AI-featured apps I’ve now checked, third-party repositories and four of my own included, had a confirmed path where a stranger could run up the owner’s model bill with nothing capping it, the same denial-of-wallet gap AI coding tools ship by default. A single line in an AGENTS.md would have caught the exact gap my own app shipped with, the same way it would have caught most of that 16.

Here’s an AGENTS.md example built around exactly that lesson, roughly what it looks like once you write it down instead of assuming it:

## Fragile areas
- Never touch `routes/whatsapp-webhook.ts` without `npm test denial-of-wallet`
  passing: it asserts the model call rejects an unverified sender and stops
  after a fixed number of messages per hour.
- Never edit `supabase/migrations/*` without a test that signs in as a
  second account and confirms it can't read the first account's row.

## Secrets
Read keys from `process.env`. Never paste a literal key into a committed
file, including this one.

Three checkable rules and a secrets line, short and specific enough to verify. Writing one is a five-minute edit. Whether the test behind it actually exists and actually runs is a separate question, the exact one an audit that checks the path itself, not just the rule describing it spends most of its time answering.

Nested AGENTS.md: scoping without frontmatter

Cursor’s .mdc rules get scoping from frontmatter: a glob pattern, an alwaysApply flag. AGENTS.md gets the same result with no frontmatter at all, just the filesystem. Drop a second AGENTS.md inside a subfolder and an agent working in that folder reads the nearest one first, closest file wins, so a monorepo can carry one root file with company-wide rules and a package-level file with rules specific to that package:

repo/
├── AGENTS.md              (root-level rules)
└── apps/
    └── billing-service/
        └── AGENTS.md      (billing-specific rules, read first here)

It’s a plainer mechanism than a globs field, and it’s the reason that same OpenAI repository splits into that many separate files rather than one long one: each package gets rules sized to what actually lives in it, so the three relevant lines aren’t buried in someone else’s section.

Common questions about AGENTS.md

Do AGENTS.md files work?

Sometimes, and the ETH Zurich study says the deciding factor is what’s inside the file, not whether one exists. A repository overview rarely earns its tokens back; a checkable rule pinned to a real test usually does. Write fewer of the first kind and more of the second.

AGENTS.md or CLAUDE.md, which do I actually need?

AGENTS.md if you use more than one coding tool, which most teams eventually do. CLAUDE.md on top of it only if you have Claude-specific instructions to add, in which case a one-line @AGENTS.md import keeps both in sync instead of maintaining two files by hand.

Does Cursor read AGENTS.md?

Yes, natively, alongside its own .mdc rules in .cursor/rules/. The two aren’t in competition: AGENTS.md carries the instructions every tool should see, and .mdc files add Cursor-specific scoping (globs, alwaysApply) on top when a rule shouldn’t load into every single request.

What actually belongs in an AGENTS.md file?

Setup and test commands first, since those are the two things every agent needs before it can verify anything. After that, a short “fragile areas” list naming the two or three paths where a plausible-looking wrong edit costs money or leaks data, plus one line on how secrets are read. The file tells the agent what to do; what an MCP server lets a coding agent reach is the separate setting that decides what it can touch while doing it. Skip the architecture tour; the research above is specific about that part not paying for itself. Those lines are a small, cheap slice of the larger question of whether the app itself is actually ready to launch; they don’t answer it on their own.