AGENTS.md vs CLAUDE.md: Where Agent Context Actually Lives

AGENTS.md vs CLAUDE.md: Where Agent Context Actually Lives 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. What AGENTS.md actually is 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. Which tools actually read it This is the part that matters when you are deciding whether to migrate. Tools with native AGENTS.md support include: GitHub Copilot coding agent Cursor Amp Factory RooCode Zed Warp 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. AGENTS.md vs CLAUDE.md vs the well known directory 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. Monorepo precedence, the part everyone gets wrong 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. Migrating without breaking your existing setup 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. What to actually put in the file Keep it operational, not aspirational. An AGENTS.md that reads like a mission statement is dead weight to an agent. What earns its place: # AGENTS.md ## 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. Three things to check right now Run 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 run a monorepo, confirm precedence is doing what you think by putting a deliberately wrong instruction in a nested AGENTS.md and watching whether your agent picks up the nested version or the root one. If you are not ready to fully migrate, do the symlink move above on one low risk repo first and confirm your existing tooling still resolves CLAUDE.md correctly before touching anything that matters. 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.