AGENTS.md vs CLAUDE.md: which tools read which

Which AI coding tools read AGENTS.md, and which read CLAUDE.md?

Sources: Claude Code memory, Codex AGENTS.md guide, Cursor rules, GitHub Copilot repository instructions, VS Code custom instructions, Copilot CLI custom instructions and its 1.0.89 release, the Codex 0.150.0 release, Antigravity CLI migration guide.

Read the table by columns. AGENTS.md is the only file every tool here reads. CLAUDE.md is read by more tools than its name suggests, but not by Codex, and Antigravity's docs do not mention it. Gemini CLI, which Antigravity CLI replaced for individual accounts on 2026-06-18, read only GEMINI.md unless context.fileName listed more.

What is CLAUDE.md, and how does Claude Code use it?

CLAUDE.md is a markdown file of instructions that Claude Code reads at the start of every session: build and test commands, conventions, the project's quirks. It loads from the repo root, from parent directories, and from ~/.claude/CLAUDE.md for your personal defaults; files in subdirectories load when Claude works there. Because it is in the prompt on every turn, every line costs tokens whether or not the task needs it. See how long should CLAUDE.md be. Loaded is not the same as followed, which is why Claude ignores CLAUDE.md at times. To see which agents load your file from where it sits, paste it into the rule-file checker.

Is it AGENTS.md or agent.md?

AGENTS.md, plural and in capitals. Loaders look for the exact name. Codex reads AGENTS.override.md, then AGENTS.md, and only reads another name if you add it to project_doc_fallback_filenames in its config. A file called agent.md is just a markdown file to most tools.

Is AGENTS.md the same as CLAUDE.md?

The content is the same kind of thing: build commands, conventions, the gotchas a new engineer would trip on. The format is the same: markdown, no schema. The difference is the loader around each file.

Claude Code gives CLAUDE.md features that other tools do not honour. @path imports pull in other files up to four hops deep. CLAUDE.local.md holds personal notes that stay out of git. Files in .claude/rules/ can carry a paths: field and load only when Claude reads, writes or edits a matching file. Codex has its own extras: an AGENTS.override.md that replaces AGENTS.md at the same level, and a 32 KiB default cap on the combined instructions (project_doc_max_bytes). Claude Code does not read AGENTS.override.md.

So an @ line written for Claude is plain text to Codex, and a Codex override is invisible to Claude. Keep tool-specific mechanics out of the shared file.

Should I symlink CLAUDE.md to AGENTS.md or use @AGENTS.md?

Both leave AGENTS.md as the one file you edit. The import is the safer default.

Claude Code skips a file it has already loaded, by path or by content, so neither setup makes Claude read the rules twice. Both also protect you from the two traps of native support: a teammate's CLAUDE.local.md, and /init writing a fresh CLAUDE.md, each of which switches the AGENTS.md fallback off without a word. The details are in does Claude Code read AGENTS.md.

Does Codex read CLAUDE.md?

Not by default. Codex walks from the repository root to the working directory and, in each directory, reads AGENTS.override.md if present, otherwise AGENTS.md. It skips empty files and stops adding once the combined size reaches project_doc_max_bytes. You can teach it other names in ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

That works, but it points the dependency the wrong way. If the rules live in CLAUDE.md, every tool has to be configured to find Claude's file, per machine. If they live in AGENTS.md, only Claude Code needs a pointer, and that pointer is one committed line.

One more condition since Codex 0.150.0, published 2026-08-26: “Untrusted projects no longer supply project-level AGENTS.md instructions.” That takes an explicit trust_level = "untrusted" for the project in ~/.codex/config.toml; a project with no entry still loads its files. The other reasons Codex skips a file are in why Codex ignores AGENTS.md.

Does Copilot CLI read AGENTS.md and CLAUDE.md?

Yes, both, along with GEMINI.md and Copilot's own files, from the repository root, the working directory and every directory between. Two September releases changed the edges. Since 1.0.86 (2026-09-17), a custom agent reads none of these unless its frontmatter sets include-custom-instructions: true. Since 1.0.89 (2026-09-28), Copilot CLI also reads Claude Code's .claude/rules files as custom instructions, so a path-scoped rule written for Claude now reaches Copilot too.

What goes in AGENTS.md and what stays in CLAUDE.md?

The shared file holds what is true of the repo for any agent: how to build and test, the conventions that differ from defaults, the decisions with their reasons. The Claude file holds what only Claude Code can act on: @ imports of other docs, notes about Claude's skills or subagents, and anything that refers to Claude's hooks. Path-scoped rules for Claude go in .claude/rules/, where a paths: field keeps them out of the prompt until Claude reads, writes or edits a matching file.

Does Cursor read AGENTS.md?

Yes. Cursor reads AGENTS.md at the project root and in subdirectories, and it reads a root CLAUDE.md the same way, applied to every conversation. Rules apply only to Agent (chat). Tab completion, Inline Edit and Bugbot reviews do not see them. The old .cursorrules file is marked legacy. How to write rules Cursor follows is in Cursor rules best practices.

AGENTS.md vs copilot-instructions.md

For the Copilot cloud agent, both load. .github/copilot-instructions.md is repository-wide, .github/instructions/*.instructions.md is path-specific with an applyTo pattern, and AGENTS.md can sit anywhere with the nearest one taking precedence. If your team also runs Claude Code or Codex, put the shared rules in AGENTS.md and keep copilot-instructions.md for what only Copilot needs. More on that pair, and what Copilot does with each, in copilot-instructions.md vs AGENTS.md.

One source of truth

The practical setup for a mixed team, as of today:

AGENTS.md                  # the rules, for every tool
CLAUDE.md                  # @AGENTS.md, then Claude-only notes
.github/copilot-instructions.md   # only if Copilot needs something extra
CLAUDE.local.md            # gitignored, yours

Avoid keeping two copies instead. When we checked 3,905 files on GitHub, 7 percent of repos with both files had copies that had drifted apart, so Claude and Codex followed different rules in the same repo. For the Cursor and Copilot files too, see all four rule files compared.

That gets every agent reading the same text. It does not make the text right. One file is one source of truth for wording, not for decisions. The webhook decision was made in #eng-payments, argued again in a pull request review, and reaches AGENTS.md only when someone copies it there. Nobody reviews whether line 40 still holds after the queue changes.

Harbor starts from the decisions instead of the file. It reads Slack, review threads and docs, puts what it finds through the gate you set, and serves Claude Code, Codex, Cursor and Copilot the facts that apply to the task. It also counts how often each rule was served and how often an answer cited it, so a dead line shows up as a number rather than a hunch. The agents docs cover what each tool gets.

Next: what in .claude/ to commit and whether AGENTS.md helps at all, per the research.