AGENTS.md vs CLAUDE.md: does Claude Code read AGENTS.md?

2026-09-09 · 5 min read claude code codex agents md claude md monorepo ai coding agents

No. Claude Code reads CLAUDE.md and ignores AGENTS.md entirely. Three ways to bridge them so one file drives both, and the design difference that breaks a naive port: AGENTS.md lets the nearest file win, while CLAUDE.md concatenates every file it finds.

Short answer, since that is what you came for: Claude Code reads CLAUDE.md, not AGENTS.md. Put an AGENTS.md in your repo and Claude Code will not load it. No setting turns it on.

That is worth knowing because AGENTS.md has become the closest thing to a standard. It is an open format, over twenty agents read it, including OpenAI Codex, Cursor, GitHub Copilot, VS Code, Jules, and Devin, and it sits at your repository root as plain markdown with no required fields. Claude Code is the notable holdout, and if you run both Codex and Claude Code you now maintain two files unless you bridge them.

Three ways to bridge

Import it. The recommended pattern, because it leaves room for Claude-specific additions:

@AGENTS.md

## Claude Code

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

Claude loads the imported file at session start, then appends the rest. AGENTS.md stays the single source of truth and Claude gets the extra instructions the other agents do not need.

Symlink it, if you have nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md

Silent on success. On Windows this needs Administrator privileges or Developer Mode, so use the import there.

Copy it once with /import, which appends a one-time copy of instruction files like AGENTS.md into the matching CLAUDE.md, and also carries over MCP servers, commands, subagents, and skills from a supported agent's configuration. Use it for a migration, not for staying in sync, since it is a copy rather than a live reference.

Related: /init already reads Cursor rules from .cursor/rules/ or .cursorrules and Copilot instructions from .github/copilot-instructions.md when generating a CLAUDE.md. Set CLAUDE_CODE_NEW_INIT=1 and it also reads AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules.

Whichever you pick, verify it. Run /context and check that CLAUDE.md appears under Memory files. If it is not in that list, Claude cannot see it, and every debugging theory after that is wasted.

The difference that breaks a naive port

This is the part that costs people a day, and it is not a syntax difference.

AGENTS.md resolves by nearest file. Agents read the closest one in the directory tree and it takes precedence. That is why the pattern scales to monorepos with dozens of them: a subproject's file replaces the root's for work in that subproject. The OpenAI repo reportedly has 88 of them.

CLAUDE.md concatenates. Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, and all discovered files are concatenated into context rather than overriding each other. Order runs from the filesystem root down, so the file closest to where you launched is read last, and within each directory CLAUDE.local.md is appended after CLAUDE.md.

So a monorepo layout that works cleanly under AGENTS.md, where packages/api/AGENTS.md quietly replaces the root file, becomes root instructions plus package instructions under Claude Code. If those two disagree, Claude picks one arbitrarily. Symlinking eleven AGENTS.md files to eleven CLAUDE.md files reproduces the layout and not the semantics.

Two tools for that. claudeMdExcludes skips files by path or glob, which is the fix when other teams' files keep getting picked up:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

And files in subdirectories below your working directory behave more like AGENTS.md than you would expect: they are not loaded at launch, only when Claude reads files in those directories.

What CLAUDE.md has that AGENTS.md does not

If you are choosing where to put something rather than just bridging, these are the capabilities that only exist on the Claude side.

Imports. @path/to/file expands at launch, relative paths resolve against the file containing the import, recursion is capped at four hops, and parsing skips code spans and fenced blocks. Write `@README` in backticks to mention a path without importing it. Note that imports help organization and do nothing for context size, since imported files load at launch too.

An import in a project file that resolves outside your working directory is treated as external and triggers a one-time approval dialog listing the files. Decline and the imports stay disabled permanently, without the dialog reappearing. That exists because someone else can commit a project file; user-scope files like ~/.claude/CLAUDE.md are yours, so their imports load without the prompt.

Four scopes. Managed policy (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux, and the Program Files path on Windows), user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md), and local (./CLAUDE.local.md, gitignored). The managed one cannot be excluded by individual settings, which is the point of it.

Path-scoped rules. .claude/rules/*.md with paths: frontmatter load only when Claude touches matching files:

---
paths:
  - "src/api/**/*.ts"
---

- All API endpoints must include input validation

This is the real answer to a growing instruction file, and it is closer in spirit to AGENTS.md's nearest-file model than plain nested CLAUDE.md files are. Rules without paths load unconditionally at launch.

Auto memory, which is a different thing entirely: notes Claude writes itself into ~/.claude/projects/<project>/memory/, indexed by a MEMORY.md whose first 200 lines or 25KB load every session. We covered how the layers fit together separately.

Gotchas worth carrying over

Size. Target under 200 lines. Claude Code loads a CLAUDE.md up to 4 MiB in full and skips a larger file entirely, which is a silent failure at exactly the moment you would least suspect it. /doctor will propose trims, cutting what Claude can derive from the code and keeping the pitfalls and conventions.
Neither file is enforcement. CLAUDE.md content arrives as a user message after the system prompt. It shapes behavior; it does not guarantee it. For something that must happen at a specific point, write a hook, which runs regardless of what the model decides.
HTML comments are stripped before injection, so  costs no tokens. Comments inside code blocks survive.
Compaction. Project-root CLAUDE.md is re-read from disk and re-injected after /compact. Nested files and path-scoped rules reload only when Claude next touches a matching file, so an instruction that "disappeared" was usually one of those, or was only ever said in chat.
Contradictions are not resolved for you. Two files disagreeing means Claude picks one arbitrarily. This matters more under concatenation than under nearest-file-wins, which is the whole point of the section above.

What we would do

Keep AGENTS.md as the single source of truth, since more tools read it than read CLAUDE.md, and bridge with a one-line @AGENTS.md import so Claude-specific instructions have somewhere to live. Keep the root file short and push anything that is only relevant to part of the tree into .claude/rules/ with paths:, rather than scattering nested CLAUDE.md files that will all load at once.

The general rule that survives both formats: these files are the things you would otherwise re-explain every session, and every line you add is a line loaded into every request you make for the rest of the project.