AGENTS.md vs CLAUDE.md: how Codex and Claude Code read project instructions

Write one AGENTS.md at the repository root and let both tools read it. Claude Code reads AGENTS.md as your project instructions whenever you have no CLAUDE.md or CLAUDE.local.md in your working directory or above it, and Codex reads only AGENTS.md and AGENTS.override.md, so AGENTS.md is the one file that reaches both. Reach for CLAUDE.md when you have instructions for Claude Code specifically, and understand that adding one switches AGENTS.md off by default.

That last clause is the part that surprises people, so the rest of this page is the exact rules each tool applies, where they differ, and how to keep one file without losing Claude-specific instructions.

#Which file should you write?

It depends on how many agents touch the repository, and the decision is not symmetrical.

If more than one does, AGENTS.md is the portable choice. Codex reads it. Claude Code reads it when no CLAUDE.md is in the way. Cursor's documentation says "Cursor supports AGENTS.md in the project root and subdirectories." Google Antigravity's rules page places AGENTS.md or GEMINI.md in your workspace folder and in any parent folder up to the repository root, and reads the same pair under ~/.gemini/. Antigravity searches upward rather than downward: the same page says it does not load rules from subfolders below the workspace folder, even when the agent reads or edits files there. One file, four tools.

If only Claude Code touches it, CLAUDE.md gives you more: imports, path-scoped rules under .claude/rules/, CLAUDE.local.md for uncommitted personal notes, and the hooks and extra-directory behaviour in the comparison below. Anthropic's documentation describes AGENTS.md support as letting "a repository already set up for other coding agents" work "without adding a CLAUDE.md, an import, or a setting", which is the honest framing: it is compatibility, not the richer of the two paths.

What you should not do is write both and expect both to be read. By default, that combination means Claude reads your CLAUDE.md files only.

#When does Claude Code read AGENTS.md, and when does it ignore it?

Reading AGENTS.md directly requires Claude Code v2.1.277 or later. Above that version, the rule is a single test: does a CLAUDE.md sit in your working directory or above it?

Anthropic's documentation splits your files into two groups for that test:

• Count, so Claude reads them instead of AGENTS.md: a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it.
• Do not count, and keep loading alongside AGENTS.md: your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files.

So a personal user-level CLAUDE.md does not disable AGENTS.md, and a project-level one does. The documentation calls out the trap explicitly: because CLAUDE.local.md counts, "adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you."

When nothing counts, Claude reads every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it at session start, and in an interactive session prints a line such as:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

As Claude then works in subdirectories, a subdirectory's AGENTS.md loads when Claude opens a file there with the Read tool and that subdirectory has none of the three CLAUDE.md files of its own.

You are not stuck with the default. /config sets Project instructions to one of four values:

The same value can go in a settings file under pluginConfigs, keyed to the built-in plugin that reads AGENTS.md. Anthropic documents a scope restriction here: Claude Code reads that entry from ~/.claude/settings.json, a --settings file, or managed settings, and ignores it in project and local settings files. Putting the block in a repository's own .claude/settings.json is silently ignored, with no error and no loaded AGENTS.md.

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

One versioning wrinkle to know if your settings file is shared across machines: before v2.1.285 the plugin's ID was agents-md@builtin and an entry under the newer ID was ignored. v2.1.285 and later read either ID.

#How does Codex find and merge AGENTS.md?

Codex walks the tree rather than testing for one file, and it concatenates rather than choosing.

Per its documentation, "Starting at the project root (typically the Git root), Codex walks down to your current working directory", and "If Codex cannot find a project root, it only checks the current directory." In each directory along that path "it checks for AGENTS.override.md, then AGENTS.md", and "Codex includes at most one file per directory."

The merge order is what makes nesting useful: "Codex concatenates files from the root down, joining them with blank lines", and "Files closer to your current directory override earlier guidance because they appear later in the combined prompt." So a subdirectory does not replace the root file, it is appended after it and wins on conflicts by position.

There is also a global level, in the Codex home directory, which defaults to ~/.codex unless CODEX_HOME is set. There Codex checks AGENTS.override.md before AGENTS.md and "uses only the first non-empty file at this level". AGENTS.override.md exists for the case the documentation describes as needing "a temporary global override without deleting the base file".

And there is a hard ceiling. Codex "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)", with the advice to "Raise the limit or split instructions across nested directories when you hit the cap." Worth knowing which end gets truncated: files are added from the root down, so when you hit the cap it is the files nearest your working directory, the most specific ones, that fall off.

If you need Codex to read a differently named file, the documented hook is project_doc_fallback_filenames, whose examples on that page are TEAM_GUIDE.md and .agents.md.

#Where do the two tools actually disagree?

These are the differences that change behaviour, rather than naming.

Three asymmetries are worth lifting out of that table. AGENTS.override.md is a Codex idea that Claude Code specifically declines: Anthropic lists AGENTS.local.md, AGENTS.override.md and anything under a .agents/ directory among the files it does not read. Codex takes one file per directory while Claude Code can take two. And only Claude Code expands @path imports inside your instruction file, which is the lever for keeping a long file organized.

Anthropic also documents three ways an AGENTS.md read through the setting behaves differently from a CLAUDE.md: InstructionsLoaded hooks do not fire for it, though they do fire for an AGENTS.md that a CLAUDE.md imports or symlinks to; directories added with --add-dir while CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set contribute their CLAUDE.md but not their AGENTS.md; and an @path import pointing outside your working directory loads without a prompt if you have already approved external imports for the project, where a CLAUDE.md would ask.

#How do you keep one file and still have Claude-specific instructions?

Put an @AGENTS.md import in a CLAUDE.md beside it, and write the Claude-only part underneath. Anthropic's documented shape:

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

Claude reads the imported file first, then the rest. This is also the approach to use in sessions where direct AGENTS.md support is unavailable: a version before v2.1.277, a session where the built-in plugin has been disabled via /plugin, and in some cases the first session after upgrading from v2.1.276 or earlier. Anthropic documents a fourth case: before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md files only, and the remedy on those versions is to update Claude Code.

A symlink works when you have no Claude-specific content:

ln -s AGENTS.md CLAUDE.md

Check two constraints before preferring it to the import. The Edit and Write tools refuse to write through a symlink, directing Claude to edit the target instead. And on Windows, creating one needs Administrator privileges or Developer Mode, and git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md instead of your instructions. For any repository that might be cloned on Windows, use the import.

Either way, run /context in your next session and confirm the file appears under Memory files. If you already had a workaround in place, Anthropic's guidance is specific about retiring it: a CLAUDE.md holding only @AGENTS.md can stay, since keeping the import never makes Claude read the file twice; a CLAUDE.md that merely tells Claude in words to read AGENTS.md should be deleted or have the sentence replaced with the import, because Claude sees the file only if it decides to open it; and a SessionStart hook that prints AGENTS.md should be removed, because it now adds a second copy to the context.

Our CLAUDE.md memory guide goes deeper on the Claude Code side, and where agent skills go covers the neighbouring question of directory layout across agents.

#What about moving instructions between tools?

Codex documents an import path rather than reading Claude's files in place. Its import page says the desktop app can import from Claude Code, Claude Cowork and Cursor, and that "Codex CLI can import from Claude Code or Cursor." The importable items include instruction files, settings.json, skills, plugins, project folders, project memories, recent chats, MCP server configuration, hooks, slash commands and subagents, with a row for "Project memories from Claude Code".

Note what that is and is not. It is a one-time migration that brings content across, not a live compatibility layer: nothing on that page says Codex reads a CLAUDE.md where it lies, and the page does not name CLAUDE.md at all. In the other direction, Claude Code's /init reads other tools' instruction files when generating a CLAUDE.md, covering Cursor rules in .cursor/rules/ or .cursorrules and Copilot rules in .github/copilot-instructions.md, and with CLAUDE_CODE_NEW_INIT=1 set it also reads AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules.

For the platforms themselves, the Claude Code hub and the Codex hub are where we keep the verified facts.

#What should you do today?

For a repository more than one agent works in:

1. Put your instructions in AGENTS.md at the repository root.
2. Delete any project CLAUDE.md that holds nothing Claude-specific, or reduce it to @AGENTS.md plus the Claude-only part.
3. Check your Claude Code version is v2.1.277 or later, since below that AGENTS.md is not read directly.
4. Watch CLAUDE.local.md. If you keep one, set Project instructions to claude-md-and-agents-md or you will silently lose AGENTS.md.
5. If your combined instructions are large, keep Codex's 32 KiB cap in mind and remember it truncates from the far end of the walk, dropping your most specific files first.
6. Run /context in Claude Code and confirm what loaded under Memory files, rather than assuming.

#What we could not confirm

Precedence between AGENTS.md and .cursor/rules in Cursor. Cursor's rules page describes both and states a merge order for Team, Project and User rules, but does not state an order between AGENTS.md and .cursor/rules, so this page does not either.

Precedence between AGENTS.md and GEMINI.md in Antigravity. Its rules page treats the two as equivalent in name and placement and says nothing about which wins when both are present.

Whether Codex expands @path imports inside an AGENTS.md. Its AGENTS.md page documents nesting and a size cap but not an import syntax, and absence from that one page is not proof the feature does not exist elsewhere in its documentation, so we make no claim either way.

We did not run these tools to observe the behaviour above. Every rule on this page is drawn from the vendors' own documentation, first fetched on 12 October 2026 and re-verified on 1 November 2026.