CLAUDE.md vs AGENTS.md: the difference is the loader, not the file

You are trying to decide which file to write. That is the wrong question, and it is the reason every page on this topic reads like a shrug.

The right question is which loader you are feeding, and what that loader does when both files exist in the same repo.

I checked sixteen tools against their own documentation on 7 August 2026, and ran Claude Code against a repo with both files to see what it actually loads. The results are below, including the two places the popular advice is wrong.

I build anvil, a set of Claude Code skills that write to these files, so I had to answer this properly rather than pick a side. The table comes first. The part I care about most is at the bottom.

TL;DR

AGENTS.md is a convention page, not a specification. Its own FAQ answers "is there a required format?" with: "No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." No version number, no RFC, no schema, no conformance keywords. The repo was created on 19 August 2025 and the core rules have not changed since.

Claude Code reads CLAUDE.md, not AGENTS.md. Anthropic states this in one sentence in the memory docs. The supported bridge is an @AGENTS.md import at the top of your CLAUDE.md, which Anthropic documents with an example.

Three tools publish a real resolution order for the both-files case: opencode, Zed, and Amp. Everybody else documents discovery and stops, or says nothing at all. GitHub Copilot in VS Code goes further and tells you outright that "no specific order is guaranteed."

The symlink advice is the least portable option available. ln -s AGENTS.md CLAUDE.md fails quietly on Windows checkouts, and I reproduced the exact failure below. Anthropic's own docs now recommend the import over the symlink for this reason.

Who reads what

This is the table. Everything in it comes from the vendor's own documentation, retrieved 7 August 2026.

Read the fourth column on its own. Eleven of the tools that read both filenames have no published rule for which one wins. That is the actual state of "the standard".

AGENTS.md specifies almost nothing

People argue about this file as though there is a spec to be right about. There isn't.

Here is what the canonical material does not contain: imports or includes, a frontmatter contract, a file-glob grammar, size limits, a machine-readable schema, and any notion of user, enterprise, or managed layers. Every one of those exists in some tool as a vendor extension.

Codex sets a 32 KiB default limit on combined project documents via project_doc_max_bytes. That is a Codex number, not a format number. Claude Code supports @path imports up to four hops deep. That is an Anthropic feature. Windsurf turns a subdirectory file into a generated glob rule for <directory>/**. That is a Windsurf mechanism. None of it is portable, and none of it is in the format.

The site does state two behavioural rules in its own words: the closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything. That is the entire conformance surface, written as prose in an FAQ.

A proposal to add path-scoped rules, issue #179, "Proposal: Standardized rule format for .agents/rules/", was opened on 15 April 2026. It is still open as of today. Claude Code shipped the same capability as .claude/rules/ with paths: frontmatter, and Copilot shipped it as .github/instructions/**. The format is behind its implementers by about a year on the one feature people actually want.

Stewardship moved to the Agentic AI Foundation under the Linux Foundation, which is a governance signal rather than a technical one. It does not add a schema.

The three tools that publish a real resolution order

If you want to know what good documentation looks like here, it looks like this.

opencode traverses upward from the current directory looking for AGENTS.md and CLAUDE.md, then falls back to globals: ~/.config/opencode/AGENTS.md, then ~/.claude/CLAUDE.md. The first matching file wins in each category. When both names exist locally, AGENTS.md is used and CLAUDE.md is not. The page was last updated on 6 August 2026, which is yesterday.

Zed publishes a nine-entry ordered list for project instructions:

.rules
.cursorrules
.windsurfrules
.clinerules
.github/copilot-instructions.md
AGENT.md
AGENTS.md
CLAUDE.md
GEMINI.md

Personal instructions live at ~/.config/zed/AGENTS.md, or %APPDATA%\Zed\AGENTS.md on Windows, and project instructions override them on conflict.

Amp documents a per-directory fallback: "If no AGENTS.md exists in a directory, but a file named AGENT.md (without an S) or CLAUDE.md does exist, that file will be included." Note the scope. It is per directory, not per repo, so a repo can end up mixing sources by folder.

Everyone else describes discovery and stops. VS Code is at least honest about it: multiple instruction files are combined and "no specific order is guaranteed." If you have both files and you are relying on one to override the other, on most tools you are relying on undefined behaviour.

Does Claude Code read AGENTS.md

No, not at runtime. The memory docs put it in one sentence: "Claude Code reads CLAUDE.md, not AGENTS.md."

There is one narrow exception, and it is generation rather than loading. Running /init reads Cursor rules and .github/copilot-instructions.md and folds the relevant parts into the CLAUDE.md it generates. With CLAUDE_CODE_NEW_INIT=1 set, /init also reads AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules. That happens once, when the file is written. It is not session loading, and the generated CLAUDE.md does not stay in sync with the AGENTS.md it was built from.

The feature request to support AGENTS.md natively, anthropics/claude-code#6235, was opened on 21 August 2025 and is still open today, almost a year later.

I tested it

Three directories, same instruction, Claude Code v2.1.223, Sonnet, tools disabled so the answer reflects only what was loaded into context.

Every directory contained the same AGENTS.md:

# Project rules
 
The project codeword is TUATARA. When asked for the codeword, reply
with exactly that word and nothing else.

The prompt was the same in all three: ask for the codeword, answer only from context, say UNKNOWN if you do not know.

That first row is the whole argument. A repo with a perfectly good AGENTS.md gives Claude Code nothing. No warning, no error, no hint in the output. The instructions are simply not there.

The third row is the Windows failure, and it gets its own section.

Run /context in a real session and check the Memory files list to see the same thing on your own repo. If you want a permanent record, the InstructionsLoaded hook logs exactly which instruction files loaded and when.

Claude Code agents.md support: the two documented workarounds

Anthropic documents both, and now recommends one over the other.

The import. Put this at the top of your CLAUDE.md:

@AGENTS.md
 
## Claude Code
 
Use plan mode for changes under `src/billing/`.

Claude loads the imported file at session start, then appends whatever Claude-specific content you add below it. This is the portable answer. It is plain text in a plain file, it survives any checkout on any filesystem, and it is the option Anthropic's own docs steer you to on Windows.

Two caveats worth knowing. Imports load at launch and enter the context window in full, so splitting content across files organises your repo without reducing what you pay per session. And an import whose path resolves outside your working directory triggers an approval dialog the first time Claude Code sees it in a project.

The symlink. ln -s AGENTS.md CLAUDE.md works, on a machine where symlinks work. Keep reading.

The symlink advice is wrong on Windows, and it fails silently

ln -s AGENTS.md CLAUDE.md is the single most repeated tip on this topic. It is also the least portable option available, and the failure mode is the bad kind.

Three things stack up.

Windows symbolic link creation normally requires SeCreateSymbolicLinkPrivilege, which is assigned by default only to Administrators. Windows 10 Developer Mode relaxes this for non-administrators.

Git for Windows disables symlink support by default in common cases. It is enabled with core.symlinks=true. Without it, ln -s in Git Bash produces copies rather than links.

And then the part that actually bites. Git documents that with core.symlinks=false, symbolic links are checked out as small plain files containing the link text. Not an error. A file.

I reproduced it. Source repo on macOS with a real symlink, committed as mode 120000:

$ ls -l CLAUDE.md
lrwxr-xr-x  CLAUDE.md -> AGENTS.md
 
$ git ls-tree HEAD
100644 blob bffb2d4...  AGENTS.md
120000 blob 47dc3e3...  CLAUDE.md

Now clone it the way a Windows checkout does by default:

$ git clone -c core.symlinks=false repo clone
$ ls -l clone/CLAUDE.md
-rw-r--r--  9 bytes  clone/CLAUDE.md
 
$ cat clone/CLAUDE.md
AGENTS.md

Your CLAUDE.md is now a nine-byte text file whose entire contents are the string AGENTS.md. Claude Code loads it, faithfully, and your teammate gets nine bytes of context instead of your project instructions. That is the third row of the test table above.

One honest wrinkle. When I reran that clone with tools enabled, Claude answered TUATARA, because the string AGENTS.md in the context looked like a pointer and the agent went and opened the file. So the failure is intermittent rather than absolute, which makes it harder to spot, not easier. Sometimes it works and nobody investigates.

This is not one client's bug. GitHub Desktop issue #20269 was opened on 27 March 2025 and is still open: Windows checkouts turn symlinks into text files, and git config --global core.symlinks true is the reported workaround. Desktop users end up with a different working tree from command-line users on the same repo. Git LFS issue #4908, created 7 March 2022 and closed as completed, is the same class of failure in a different client.

The honest conclusion: symlinks work fine when you control the filesystem, the checkout config, and the permissions. On a solo macOS or Linux machine, use one if you like. On a team with any Windows in it, two real files or an import are more portable. That is a portability warning, not a prohibition.

I have not tested CI or Docker behaviour and I have not found a primary source documenting a specific AGENTS/CLAUDE symlink failure in a container. Treat that as untested rather than broken.

agents.md and Copilot: two hosts, two behaviours

Copilot is where most of the confusion on this topic comes from, because "Copilot" is two products with different loaders.

The coding agent reads a root AGENTS.md for the whole repo and nested files for parts of it. The documented rule is that "the nearest AGENTS.md file in the directory tree will take precedence." It also reads .github/copilot-instructions.md and .github/instructions/**/NAME.instructions.md, and supports a single root CLAUDE.md or GEMINI.md as an alternative. When both repository-wide and path-specific instructions match, both are used.

Copilot in VS Code auto-detects a root AGENTS.md. Nested AGENTS.md files are experimental and need chat.useNestedAgentsMdFiles turned on. VS Code also auto-detects CLAUDE.md at the workspace root, .claude/CLAUDE.md, ~/.claude/CLAUDE.md, and CLAUDE.local.md, which is a broader Claude surface than most tools bother with.

The important difference is what happens next. Personal instructions take highest priority, then repository, then organisation. Within that, all relevant files are combined and "no specific order is guaranteed." If your AGENTS.md and CLAUDE.md contradict each other in VS Code, the docs are telling you not to rely on the outcome.

CLAUDE.md vs skills: a different axis

This one comes up in the same searches and it is worth thirty seconds because it is a category difference, not a comparison.

CLAUDE.md is context. Anthropic's docs are explicit that its content is delivered as a user message after the system prompt, not as part of the system prompt, and that Claude treats it as context rather than enforced configuration. There is no compliance guarantee. Vague or conflicting instructions get followed unreliably, and two CLAUDE.md files that disagree mean Claude picks one arbitrarily.

Skills load on demand when you invoke them or when Claude judges them relevant, so they cost nothing until they are used.

Hooks are the only enforcement layer. An instruction in a file is a request. A PreToolUse hook that blocks the edit is enforcement. If you have written "never commit directly to main" in a CLAUDE.md and been disappointed, that is the mechanism you wanted. I wrote up the failure modes in when your Claude Code hook is not firing.

The same distinction applies to AGENTS.md, more so: it has no hook layer at all, in any tool, because it has no execution model.

What the evidence does not support

Being the page that says no is the point.

There is no head-to-head study. Nobody has measured AGENTS.md against CLAUDE.md as filenames. You cannot, cleanly. The filename is confounded with the loader, the model, where the content lands in the prompt, how large it is, and what tasks you ran. Anyone telling you one format performs better is making a category error.

The 60,000 figure is not a measurement you can cite. agents.md links a live GitHub code search described as showing over 60,000 open-source projects using the file. The page is undated and the query is live. It supports "broadly visible". It does not support a time series, a growth rate, or a market-share comparison, because there is no dated CLAUDE.md count to compare it against.

The 88-files example is one repository. agents.md says OpenAI's main repo had 88 AGENTS.md files at time of writing. That is a per-repo file count, not a repo count.

The AGENTS.md paper is not about filenames. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (Gloaguen, Mündler, Müller, Raychev, Vechev) studies repository-level context files in general. Its v1 landed 12 February 2026 and v2 on 23 June 2026, and the abstract softened between them. The v2 wording is that providing context files "does not generally improve task success rates, while increasing inference cost by over 20% on average." If you cite it, cite v2. Most people are still quoting v1.

That finding is about context files as a category, and it is a reason to keep yours short. It says nothing about which name you put on the file.

What I would actually do

Pick based on the loaders your team runs, not on which name feels more standard.

Claude Code only. Write CLAUDE.md. Nothing else to decide.

Claude Code plus one AGENTS.md-native tool. Write AGENTS.md as the source of truth, then a CLAUDE.md that is one line: @AGENTS.md. Add Claude-specific instructions underneath it if you have any. This is Anthropic's documented recommendation and it survives every checkout.

Mixed team with Windows. Same as above. Do not use the symlink. The failure is silent and produces a nine-byte file.

opencode, Zed, or Amp in the mix. These read both and publish the order, so you can rely on it. On opencode and Zed, AGENTS.md wins. On Amp the fallback is per directory, so keep one canonical file at the root rather than scattering both names through the tree.

Aider. Neither file is discovered. Add read: AGENTS.md to .aider.conf.yml or pass --read AGENTS.md.

And keep the file short regardless. Claude Code's docs target under 200 lines per file, and the arXiv result is a reason to take that seriously rather than a stylistic preference.

The question the filename argument is hiding

Look back at the table one more time, but at what every row has in common instead of what separates them.

Whichever file your tool reads, it reads the whole thing at the start of every session. Claude Code loads CLAUDE.md in full regardless of length. Codex concatenates project docs up to 32 KiB. Copilot combines everything it finds and does not promise an order. None of these are lazy.

So a line in that file is not a note. It is a standing charge. You pay for line 140 on every task that has nothing to do with whatever line 140 says, forever, until somebody removes it. And nobody removes it, because there is no moment in anyone's week called "prune the context file".

That is what the arXiv result is measuring. Repository context files did not generally improve task success, and cost over 20% more per run. Not because writing things down is wrong. Because most of what ends up in these files is something the agent could have read off the codebase in the first place, and it gets charged for it anyway.

Which makes the real question neither AGENTS.md nor CLAUDE.md. It is: what earns a line, and what takes one away?

Almost nobody has an answer to the second half. Files grow. A rule goes in after a bad session, and a year later nobody can tell you whether it is still doing anything, or whether Claude would have got it right without it.

What I built for this

anvil is a set of Claude Code skills that treat context as a budget rather than a scratchpad.

The rule it is built on is the opposite of how most people write these files:

A line in a context file is paid every time the command that reads it runs, forever. So the default answer to "should this go in a context file?" is no.

Corrections do not go straight into a file. Every command logs them as they happen, along with the moments Claude stalled or had to guess, into two append-only logs. A separate /feedback pass is the only thing that reads those logs and the only thing that writes to context files, and a lesson has to get past three questions to be admitted:

1. Could Claude have inferred this from the code? If yes, drop it.
2. Is it stated as a direct constraint rather than a suggestion? If not, rewrite it until it is.
3. Does it fit on one line? If not, it is two lessons, or it is not a lesson.

Most corrections fail the first question and die in the logs. That is the system working.

What survives is written at the narrowest scope that holds it, and only moves outward on evidence. A lesson scoped to one command has to recur in two separate tickets before it applies to that command generally, and in three before anvil will even propose it as a line in the global file every session pays for. Nothing reaches the global tier on first sighting.

And the budgets are hard ceilings, not warnings. When a file is at its limit, adding a line means removing one, and /feedback has to name the line it evicted and say why the new one beats it. That is the part almost nothing else does: it makes every addition a ranking decision instead of an append, so pruning happens continuously rather than on a schedule nobody keeps.

Two more things worth knowing before you look at it. The logs are permanent, so nothing you corrected is ever actually lost, only evicted from the files that get read. And anvil never writes your global instruction file itself. It drafts the line and you accept or reject it, because that file is yours.

docs/FILE_CONTRACT.md is the whole thing written down: every file, its purpose, its line budget, and who is allowed to write it. If you only read one page, read §1.

Start by doing this

2 mins: Run /context in a repo that has an AGENTS.md and check the Memory files list. If AGENTS.md is not in it, that is your answer, and it took two minutes.

5 mins: If your repo has an AGENTS.md and no CLAUDE.md, create a CLAUDE.md containing the single line @AGENTS.md. Rerun /context and confirm it loaded.

10 mins: Open whichever file you just confirmed and run the admission test over it line by line. Ask of each one whether Claude could have inferred it from the code. Delete the ones that fail. Most repos lose a third of the file, and nothing gets worse.

Then: if you want that to happen continuously instead of once, anvil is the mechanism.