If you have opened three different repos this month and found three different context files (AGENTS.md in one, CLAUDE.md in another, both in a third, out of sync), you are not imagining the mess. AGENTS.md is now an open, vendor neutral standard that most major coding agents read, but CLAUDE.md has not gone away, and knowing which file wins where saves you from an agent quietly following stale instructions.
AGENTS.md started as a proposal from Sourcegraph's Amp team to fix a specific problem: every coding agent invented its own context file, so teams ended up maintaining CLAUDE.md, .cursorrules, .windsurfrules, and whatever else, all describing the same project. OpenAI and Google backed the standard, and it has since moved under the Linux Foundation's Agentic AI Foundation. Guides tracking adoption report 28+ supporting tools and more than 60,000 open source repos containing the file (secondary source, treat the exact counts as approximate, not audited).
The pitch is simple: one Markdown file, one format, every agent reads the same source of truth instead of you hand syncing five files that drift within a week.
This is the part that matters when you are deciding whether to migrate. Tools with native AGENTS.md support include:
Notice what is not confirmed on that list. Reports that Claude Code reads AGENTS.md natively circulate in comparison guides, but I could not verify this against Anthropic's own changelog, so I am stating it qualitatively here rather than as fact: treat it as unconfirmed until you see it in Anthropic's own docs, and keep CLAUDE.md in place as your safety net if you rely on Claude Code specifically.
Three layers get conflated constantly, and they solve different problems.
| Layer | What it is | Scope |
|---|---|---|
| AGENTS.md | Vendor neutral project context file | Repo or monorepo package level |
| CLAUDE.md | Anthropic specific context file for Claude Code | Repo or monorepo package level |
| well known agents directory | Emerging discovery layer for agents to find capabilities at a domain, similar in spirit to robots.txt | Domain or service level |
AGENTS.md and CLAUDE.md compete for the same job (project context for a coding agent). The well known directory is not competing with either, it is a discovery mechanism, closer to how a search engine finds a sitemap than to how an agent reads project instructions. Do not treat these as three versions of the same thing.
In a monorepo, the nearest AGENTS.md wins. A file at packages/api/AGENTS.md
overrides anything set at the repo root for that package, the same pattern you already know from .eslintrc
or .gitignore
cascading. If you have context that applies everywhere (coding style, commit conventions), put it at root. If a package has its own build tooling or test runner that the root context does not know about, give that package its own file.
CLAUDE.md follows the same nested pattern in Claude Code specifically. If you keep both files, keep the precedence rules identical across them, otherwise you get an agent that behaves differently depending on which tool opened the repo.
You do not need to pick one file and delete the other overnight. The recommended migration is a rename plus a symlink, so legacy tools that only look for the old filename keep working:
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md
Now AGENTS.md is your source of truth, tools that support the open standard read it directly, and Claude Code (or any tool still hardcoded to look for CLAUDE.md) follows the symlink and gets identical content. No duplicate maintenance, no drift between two files that were supposed to say the same thing.
For a monorepo, run this per package that has its own context file, not just at root.
Keep it operational, not aspirational. An AGENTS.md that reads like a mission statement is dead weight to an agent. What earns its place:
## Setup
npm install
cp .env.example .env
## Test
npm run test -- --watch=false
## Build
npm run build
## Conventions
- All API routes live in src/app/api, not src/pages/api
- Use the shared Zod schemas in src/lib/schemas, do not redefine types inline
- Never commit generated files in dist/
Commands the agent can run verbatim, project specific conventions it cannot infer from the code alone, and nothing that is already obvious from package.json or the folder structure. If your AGENTS.md is longer than your README, you are probably explaining things the agent should be reading from the code directly.
find . -iname "AGENTS.md" -o -iname "CLAUDE.md"
from your repo root and see how many context files you actually have, and whether any two of them disagree.If you want a deeper look at how agent context and enterprise agent stacks fit together, I cover it in more detail on my site.
Writing the actual instructions inside AGENTS.md well is its own skill. I built a free agent system prompt builder if you want a starting structure instead of a blank file.
If you want this wired up across a real monorepo end to end, that is exactly the kind of work I take on.
Curious how many context files you are all secretly juggling right now. Drop your count in the comments, and whether they agree with each other.