Claude Code Ignores AGENTS.md

The annoyance

I dropped AGENTS.md at the repo root because that is the cross-agent file. Cursor reads it. Codex reads it. Starter kits keep adding it. I opened Claude Code and the standing instructions were gone.

I ran /context. Memory files listed CLAUDE.md entries, or none. AGENTS.md was not there. Nothing threw. The file was in the tree. The session simply never loaded it.

I had the usual suspects. A stale CLI. A worktree. A file one directory too high. Then I read the memory page. Claude Code was never looking for that name.

What Anthropic actually says

From the official How Claude remembers your project page, under “AGENTS.md”:

“Claude Code reads CLAUDE.md, not AGENTS.md.”

The rest of that section is the fix, not a fallback. Claude Code does not read AGENTS.md if CLAUDE.md is missing. It does not fall through. The documented move is to create a CLAUDE.md that imports the file you already have:

“If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them. You can also add Claude-specific instructions below the import. Claude loads the imported file at session start, then appends the rest.”

A symlink is documented for the case where you have nothing Claude-specific to add. Windows is called out in the same paragraph:

“On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead.”

The same section mentions /import. That is a different tool:

“You can also run /import to bring a supported coding agent's configuration into Claude Code, which appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md and carries over MCP servers, commands, subagents, and skills. Requires Claude Code v2.1.213 or later.”

A one-time copy is a snapshot. If AGENTS.md changes later, the copy does not. Do not treat /import as the standing fix.

The fix

Preferred: a CLAUDE.md that starts with the import, then any Claude-specific notes. This is the official example shape:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

If you do not need Claude-specific content, the documented symlink is:

ln -s AGENTS.md CLAUDE.md

The command prints no output on success. On Windows, skip the symlink and use the import. Administrator privileges or Developer Mode are the documented requirement for creating one, and the import does not need them.

Prove it

Start a new session after the file exists. Official check:

“The command prints no output on success. In your next session, run /context and confirm CLAUDE.md appears under Memory files.”

If CLAUDE.md is missing under Memory files, Claude cannot see the import either. The standing file has to load before @AGENTS.md can.

Why it fails

I treat AGENTS.md as the file every coding agent reads. For Claude Code that is false. Same family as auto in project settings — the file looks correct, the name is the one everyone uses, and the documented field is a different one. The CLAUDE.md Diet is the next problem once the file actually loads: every line in CLAUDE.md, including what you import, enters the context window at launch. The silent Opus tax is the same class of miss: nothing tells you the default you never chose.

If you want to run this with other operators rather than on your own, we are doing that in the public Skool community, and that is https://www.skool.com/navaigate.

Sources

• Anthropic — How Claude remembers your project
• The CLAUDE.md Diet
• Auto in Project Settings Does Nothing
• The Silent Opus Tax
• NavAIgate Skool community