AGENTS.md Won. The Agent I Actually Use Still Doesn't Read It.

Standards fights in this industry usually end with three competing specs and a committee. This one ended with a Markdown file.

AGENTS.md — a plain AGENTS.md at your repo root telling agents how to build, test, and change your project — is now read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, Factory, Jules and twenty-odd other tools, sits in over 60,000 repositories, and is stewarded by the Linux Foundation's Agentic AI Foundation alongside MCP. That is a settled standard by any definition I'd accept.

Claude Code, which is the agent I actually spend my day in, has no native support for it. The requests are open and unshipped. So this is the practical post: what to put in the file, how to make Claude Code read it anyway, and the footnote about auto-ingested instruction files that this month made a lot less theoretical.

Why the boring format won

AGENTS.md was formalised in August 2025 by OpenAI, Google, Cursor, Factory and Sourcegraph, and its defining feature is a refusal: no schema. No required sections, no YAML front matter, no validator. It's Markdown, and the consumer is a language model.

Every instinct I have as an engineer wanted a schema. I was wrong, and the reason is worth internalising: a schema is a contract between two programs. This is a contract between a human and a reader that already understands prose. Adding structure would have added a parser, a spec version, and a migration — and bought nothing, because the thing on the other end reads English better than it reads JSON. The format won because it declined to become a spec.

It also solves a real problem I'd been living with. Before it, a repo shared by a team running different tools accumulated CLAUDE.md, .cursorrules, and a Copilot instructions file, all saying the same thing and drifting apart within a month.

The Claude Code workaround

Don't wait for native support and don't maintain two files. Keep AGENTS.md as the single source of truth and make CLAUDE.md a pointer to it:

# CLAUDE.md

Project instructions live in AGENTS.md. Read it first.

@AGENTS.md

# anything Claude-Code-specific goes below, and only that

Three lines, one source of truth, and the tool-specific file shrinks to the handful of things that genuinely are tool-specific. Every other agent in the repo reads AGENTS.md directly. This is the pattern I'd recommend to any team where people run different agents by preference — which, in 2026, is every team.

What actually earns its place in the file

The failure mode I see most is a 400-line AGENTS.md restating the README. Every line in that file is in the context window on every single request — it's a permanent tax, so the bar is high. What's paid for itself in mine:

The exact build, test, and lint commands — including the one with the non-obvious flag that everyone gets wrong. The things that are not discoverable from reading the code: which directory is generated, which module is deprecated but still imported, why the odd thing is odd. Conventions the codebase follows but doesn't enforce with a linter. And a short list of what to never touch without asking. That's it. If a competent new hire would figure it out in ten minutes of reading, leave it out.

This is the same discipline as choosing which MCP servers and skills a team actually installs: context is a budget, and everything you add competes with the user's actual question.

The footnote that stopped being theoretical

An instruction file that every agent auto-ingests as trusted input is, viewed from a slightly different angle, a prompt-injection delivery mechanism that ships in the repo.

That's not hypothetical any more. In this month's symlink RCE across six coding agents, the instruction file is step three of the chain: the repo's AGENTS.md or CLAUDE.md is what politely asks the agent to perform the file operation that the symlink then redirects. The standard's greatest strength — every tool reads it automatically, no configuration — is exactly the property the attack needs.

I'm not suggesting you stop using it. I'm suggesting one rule: read the AGENTS.md of any repo you didn't write before you point an agent at it, the same way you'd skim a postinstall script before npm install. It's a config file that executes, and it should be reviewed in pull requests with the seriousness of one. When I rebuilt my agent after the Monero incident, the rule I landed on was that anything taking untrusted input and acting on it is already compromised. An instruction file from a repo you cloned qualifies.

The verdict

Write the AGENTS.md. Keep it under a screen. Import it from whatever tool-specific file your agent insists on. Review it in PRs like code, because it is.

The larger pattern is the one I keep noticing this year. MCP went to a foundation and shipped a deliberately boring stateless spec. AGENTS.md won by being a text file. The agentic stack is converging on the least clever option available at every layer — and given how much of my year has been spent cleaning up after clever, I think that's the healthiest signal in the ecosystem.

Sources

Adoption counts, the native-support tool list, and the Claude Code import workaround are documented in Morph's AGENTS.md spec guide and this 2026 complete guide. The Agentic AI Foundation's own five-run benchmark of AGENTS.md is the most honest measurement of whether the file helps — worth reading before you write a long one. Stewardship details are in the AAIF formation announcement. Claude Code's native-support status is accurate as of writing; check the issue tracker before you take my word for it.