On Claude Code v2.1.223, a repo with a perfectly good AGENTS.md gave Claude Code nothing.
No warning. No error. No hint in the output.
I tested it. Same instruction, three setups. With only AGENTS.md in the repo, Claude Code answered UNKNOWN.
Update, 3 November 2026: Claude Code v2.1.277 (18 September 2026) now reads AGENTS.md when there is no CLAUDE.md in your working directory or above it. Where this post says Claude Code does not read AGENTS.md, it describes v2.1.223, the version I tested. The import and the symlink still work. The loader point still holds.
Then I tried the Windows case. A symlinked CLAUDE.md, cloned the way a Windows checkout does by default, became a nine-byte file. Claude Code loaded those nine bytes with no error.
Both results say the same thing. The difference between CLAUDE.md and AGENTS.md is the loader, not the file.
When I tested, Anthropic's docs said Claude Code reads CLAUDE.md and does not read AGENTS.md at runtime. They recommended a one-line @AGENTS.md import in your CLAUDE.md instead.
AGENTS.md is a filename, not a standard. It has no schema, no version number, and no MUST/SHOULD language anywhere. What differs between tools is the loader: where it looks, what order it merges, and what it does when both files exist.
Three tools publish that order. Most publish nothing.
So the question that settles which file to write is which loader you are feeding. And what that loader does when both files sit in the same repo.
I checked fourteen tools against their own documentation on 7 August 2026. I also ran Claude Code against repos with one file, the other, or a symlink between them. The symlink tip breaks on Windows, and it breaks silently.
One test matters more than any filename. Every line in the file has to pass it: could Claude have inferred this from the code? If yes, delete it. The end of the post has the steps.
The test comes first. The table follows.
Does Claude Code read AGENTS.md?#
Not in v2.1.223, the version I tested.
The memory docs put it in one sentence: "Claude Code reads CLAUDE.md, not AGENTS.md."
Since v2.1.277 it does, but only when there is no CLAUDE.md in your working directory or above it. If a CLAUDE.md exists, Claude reads that and ignores AGENTS.md unless you import it or change the Project instructions setting in /config.
I tested it
Three directories. Same instruction. Claude Code v2.1.223. 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.
| Setup | Answer |
|---|---|
AGENTS.md only | UNKNOWN |
AGENTS.md plus a CLAUDE.md containing @AGENTS.md | TUATARA |
AGENTS.md plus a symlinked CLAUDE.md, cloned with core.symlinks=false | UNKNOWN |
The first row is the whole argument. The instructions are not there.
The third row is the Windows failure. It gets its own section below.
To see the same thing on your own repo, run /context in a real session and check the Memory files list.
For a permanent record, the InstructionsLoaded hook logs exactly which instruction files loaded and when.
The one exception is generation, not loading
Running /init reads Cursor rules and .github/copilot-instructions.md. It 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. 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. It was closed as completed on 17 August 2026, with a reply that pointed to the import and symlink workarounds. Claude Code v2.1.277 then added direct support on 18 September 2026.
Claude Code agents.md support: the two documented workarounds#
Anthropic documents both. It now recommends the import over the symlink.
Since v2.1.277 you only need them when you also keep a CLAUDE.md, or when you run an older version.
The import. Put this at the top of your CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Anthropic documents this with an example.
Claude loads the imported file at session start. Then it 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. It is the option Anthropic's own docs steer you to on Windows.
Two caveats:
- Imports load at launch and enter the context window in full. Splitting content across files organizes your repo. It does not reduce what you pay per session.
- 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 tip I want to look at. It is the least portable option available. And the failure is the bad kind: silent.
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 -sin Git Bash produces copies rather than links. - Git documents that with
core.symlinks=false, symbolic links are checked out as small plain files containing the link text. A file, not an error. This is the part that bites.
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.mdNow 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.mdYour CLAUDE.md is now a nine-byte text file. Its entire contents are the string AGENTS.md.
Claude Code loads it, faithfully. Your teammate gets nine bytes of context instead of your project instructions.
That is the third row of the test table above.
One wrinkle. I reran that clone with tools enabled, and Claude answered TUATARA. The string AGENTS.md in the context looked like a pointer, so the agent went and opened the file.
So the failure is intermittent, not absolute. That makes it harder to spot. Sometimes it works and nobody investigates.
The behavior spans clients. GitHub Desktop issue #20269 was opened on 27 March 2025 and is still open as of 3 November 2026. Windows checkouts turn symlinks into text files. 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.
My 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.
It is a portability warning: fine for a solo or all-Mac/Linux repo, risky once anyone checks out on Windows without symlinks enabled.
I have not tested CI or Docker behavior. I have not found a primary source documenting a specific AGENTS/CLAUDE symlink failure in a container. Treat that as untested, not broken.
Who reads what#
Everything in this table comes from the vendor's own documentation, retrieved 7 August 2026.
| Tool | Reads AGENTS.md | Reads CLAUDE.md | Documented order when both exist |
|---|---|---|---|
| Claude Code | No (only via @AGENTS.md import, or /init under a flag) | Yes: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, managed policy paths | N/A, it only loads one of the two |
| OpenAI Codex CLI | Yes: AGENTS.override.md, then AGENTS.md, then configured fallbacks | No | N/A |
| Copilot coding agent | Yes, root and nested | Yes, single file at repo root | No. Nested AGENTS.md precedence is documented; AGENTS vs CLAUDE is not |
| Copilot in VS Code | Yes at root; nested behind chat.useNestedAgentsMdFiles | Yes: root, .claude/CLAUDE.md, ~/.claude/CLAUDE.md, CLAUDE.local.md | No. Docs say all files are combined and no specific order is guaranteed |
| Cursor | Yes, root and subdirectories | Not documented | No. Precedence is only documented for Team > Project > User rules |
| Gemini CLI | Only if you add it to context.fileName | Only if you add it to context.fileName | N/A, default is GEMINI.md |
| Google Jules | Yes, repo root, automatically | Not documented | N/A |
| Sourcegraph Amp | Yes: cwd, parents to $HOME, subtrees, plus system paths | Yes, as a per-directory fallback | Yes. Per directory: AGENTS.md, else AGENT.md, else CLAUDE.md |
| Windsurf / Devin Cascade | Yes, case-insensitive, root plus subdirectory glob rules | Not documented | N/A |
| Zed | Yes: personal ~/.config/zed/AGENTS.md plus project files | Yes, in the project priority list | Yes. A nine-entry ordered list, AGENTS.md above CLAUDE.md |
| opencode | Yes, local traversal plus ~/.config/opencode/AGENTS.md | Yes, local plus ~/.claude/CLAUDE.md | Yes. AGENTS.md wins locally; opencode global wins over Claude global |
| Cline | Yes: project root and ~/.agents/AGENTS.md | Not documented | Workspace beats global; AGENTS vs CLAUDE not addressed |
| Aider | No automatic discovery | No automatic discovery | N/A. You pass files with /read, --read, or read: in config |
| Roo Code | Repository archived, last commit 15 May 2026. No current runtime claim is supportable | ||
Read the fourth column on its own.
Only three of the fourteen rows publish which file wins when both exist. Five tools read both names by default: the two Copilot products, Amp, Zed and opencode. Two of those five, the Copilot products, do not say which one wins. That is the state of "the standard".
The Claude Code row is the August snapshot. It changed in v2.1.277: with no CLAUDE.md in the folder, Claude Code now reads AGENTS.md. Check any other row against the vendor's current docs before you rely on it.
The three tools that publish a real resolution order#
This is what good documentation looks like here.
opencode traverses upward from the current directory looking for AGENTS.md and CLAUDE.md. Then it 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, the day before I checked.
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.mdPersonal instructions live at ~/.config/zed/AGENTS.md, or %APPDATA%\Zed\AGENTS.md on Windows. 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. A repo can end up mixing sources by folder.
Everyone else describes discovery and stops. VS Code at least says so: multiple instruction files are combined and "no specific order is guaranteed."
If you have both files and rely on one to override the other, on most tools you are relying on undefined behavior.
agents.md and Copilot: two hosts, two behaviors#
Most of the confusion on this topic comes from Copilot. "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. It 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. That is a broader Claude surface than most tools bother with.
Then comes the part that matters. Personal instructions take highest priority, then repository, then organization. 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.
AGENTS.md specifies almost nothing#
People argue about this file as though there is a spec to be right about. What exists is a convention page and an FAQ.
Its 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. The core rules have not changed since.
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
- 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
@pathimports 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. None of it is in the format.
The site does state two behavioral 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 3 November 2026.
Claude Code, Cursor and Copilot already ship path-scoped rules. Claude Code has .claude/rules/ with paths: frontmatter, added in December 2025. Copilot's coding agent has .github/instructions/**, added in July 2025. The AGENTS.md proposal for the same thing opened in April 2026 and is still open as of 3 November 2026.
Stewardship moved to the Agentic AI Foundation under the Linux Foundation. That is a governance signal, not a technical one. It does not add a schema.
CLAUDE.md vs skills: a different axis#
This comes up in the same searches. It is a category difference, not a comparison. It takes thirty seconds.
CLAUDE.md is context. Anthropic's docs are explicit: its content is delivered as a user message after the system prompt, not as part of the system prompt. Claude treats it as context, not enforced configuration.
There is no compliance guarantee. Vague or conflicting instructions get followed unreliably. 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. 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 wrote "never commit directly to main" in a CLAUDE.md and got disappointed, a hook 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#
This is the page that says no. That 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. 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. It is a reason to keep yours short. It says nothing about which name you put on the file.
What I would 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. On v2.1.277 or later, Claude reads it when there is no CLAUDE.md. If you have Claude-specific instructions, or run an older version, write a CLAUDE.md that is one line:
@AGENTS.md. Add the Claude-specific instructions underneath it. This is Anthropic's documented recommendation, and it survives every checkout. - Mixed team with Windows. Same as above. Do not rely on the symlink unless everyone has symlinks enabled. 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.mdto.aider.conf.ymlor pass--read AGENTS.md.
Keep the file short regardless. Claude Code's docs target under 200 lines per file. The arXiv result is a reason to take that seriously, not a stylistic preference.
The question the filename argument is hiding#
Look at what every row of the table has in common, not 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 a standing charge. You pay for line 140 on every task that has nothing to do with line 140. Forever, until somebody removes it.
And nobody removes it. There is no moment in anyone's week called "prune the context file".
That is what the arXiv result measures. Repository context files did not generally improve task success, and they raised inference cost by over 20% on average.
The charge lands because most of what ends up in these files is something the agent could have read off the codebase. It gets billed for it anyway.
So the real question is different: 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. A year later nobody can say whether it still does anything, or whether Claude would have gotten it right without it.
Start by doing this#
- 2 mins: Run
/contextin 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 AGENTS.md is missing from that list, or you run a version before 2.1.277, create a CLAUDE.md containing the single line
@AGENTS.md. Rerun/contextand confirm it loaded. - 10 mins: Open whichever file you just confirmed and run the admission test over it line by line. Ask of each line whether Claude could have inferred it from the code. Delete the ones that fail.
Frequently asked questions
- Does Claude Code read AGENTS.md?
- Yes, since v2.1.277 (18 September 2026), when there is no CLAUDE.md in your working directory or above it. Before that, no. When I tested v2.1.223, Anthropic's memory documentation stated directly that Claude Code reads CLAUDE.md, not AGENTS.md. If a CLAUDE.md exists, Claude reads that and ignores AGENTS.md unless you import it or change the Project instructions setting in /config. The one exception is generation, not loading. Running /init with CLAUDE_CODE_NEW_INIT=1 reads AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules, and folds the relevant parts into the CLAUDE.md it writes. After that the generated file does not stay in sync. The feature request for native support, anthropics/claude-code#6235, was opened on 21 August 2025 and closed as completed on 17 August 2026.
- What is the difference between CLAUDE.md and AGENTS.md?
- The filename, and therefore which tools load it. Neither is a format in any technical sense. AGENTS.md's own FAQ says it is standard Markdown with no required fields. CLAUDE.md is also plain Markdown. The real differences are in the loaders. Claude Code supports @path imports, .claude/rules/ with path-scoped frontmatter, managed policy files, and CLAUDE.local.md. AGENTS.md has none of those in the format itself, though individual tools add their own. Ask which loader you are feeding, not which file is better.
- How do I use AGENTS.md with Claude Code?
- On v2.1.277 or later with no CLAUDE.md, there is nothing to do. Claude reads AGENTS.md. Otherwise, create a CLAUDE.md whose first line is @AGENTS.md. Claude Code expands the import at session start, and you can add Claude-specific instructions below it. This is Anthropic's documented approach. A symlink (ln -s AGENTS.md CLAUDE.md) also works on macOS and Linux. On Windows checkouts it degrades to a plain text file, so the import is the portable choice.
- Is AGENTS.md a standard?
- Not in the technical sense. There is no version number, no schema, no RFC, and no MUST/SHOULD/MAY conformance language in the canonical material. The FAQ states there is no required format and that it is standard Markdown. It documents two behavioral rules in prose: the closest AGENTS.md to the edited file wins, and explicit user prompts override everything. Stewardship sits with the Agentic AI Foundation under the Linux Foundation. That is governance, not specification. A proposal for a standardized path-scoped rule format, issue #179, has been open since 15 April 2026 and was still open on 3 November 2026.
- Should I use both AGENTS.md and CLAUDE.md in the same repo?
- Only if you know what your tools do when both exist. Most of them do not say. Three publish a rule: opencode uses AGENTS.md and ignores CLAUDE.md when both are present locally. Zed has a nine-entry ordered list with AGENTS.md above CLAUDE.md. Amp falls back per directory from AGENTS.md to AGENT.md to CLAUDE.md. GitHub Copilot in VS Code reads both and states that no specific order is guaranteed. The safe pattern is one source of truth plus a one-line import, not two files with real content in them.
- Does the ln -s AGENTS.md CLAUDE.md symlink trick work?
- On macOS and Linux, yes. On Windows it is the least portable option available. Creating a symlink normally needs SeCreateSymbolicLinkPrivilege, held by Administrators, or Developer Mode. Git for Windows disables symlink support by default in common cases. Git documents that with core.symlinks=false, symlinks are checked out as small plain files containing the link text. I reproduced this. The checked-out CLAUDE.md became a nine-byte text file containing the string AGENTS.md. Claude Code loaded those nine bytes with no error. GitHub Desktop issue #20269 has tracked the same behavior since 27 March 2025 and is still open as of 3 November 2026.
- Does Cursor support AGENTS.md?
- Yes. Cursor reads AGENTS.md or agents.md in the project root and in subdirectories. It presents this as a plain-Markdown alternative to .cursor/rules for simple cases. Cursor documents precedence among Team Rules, Project Rules, and User Rules. It publishes no conflict order between AGENTS.md and .cursor/rules, and does not document reading CLAUDE.md.
- Does Gemini CLI read AGENTS.md?
- Not by default. Gemini CLI's default context filename is GEMINI.md, with a global file at ~/.gemini/GEMINI.md. AGENTS.md is loaded only if you add it to the context.fileName setting in settings.json, which accepts an array of filenames. Issue google-gemini/gemini-cli#28227, opened 1 July 2026 and still open as of 3 November 2026, tracks AGENTS.md being silently ignored because it is absent from the default list.
- Which coding agents read AGENTS.md automatically?
- Verified as of 7 August 2026: OpenAI Codex CLI, GitHub Copilot coding agent, GitHub Copilot in VS Code, Cursor, Google Jules, Sourcegraph Amp, Windsurf and Devin Cascade, Zed, opencode, and Cline. Gemini CLI requires a settings change. Aider does not auto-discover any convention file and needs an explicit --read or a read: entry in .aider.conf.yml. Claude Code reads it only when there is no CLAUDE.md, from v2.1.277. Before that it did not read it at all.