Blog
Published: September 23, 2026
Both are plain markdown instructions an agent reads at session start. AGENTS.md is the shared name that Codex, Cursor, Copilot and others read. CLAUDE.md is Claude Code's own. Since v2.1.277 Claude Code also reads AGENTS.md, but by default only when no CLAUDE.md exists. Keep the rules in AGENTS.md and import it.
Every fact below was checked against the vendor's own docs on 2026-09-23. Tool support for these files has changed several times this year, so the date matters.
Which AI coding tools read AGENTS.md, and which read CLAUDE.md? #
| Tool | Reads by default | AGENTS.md | CLAUDE.md |
|---|---|---|---|
| Claude Code 2.1.280 | CLAUDE.md ,.claude/CLAUDE.md ,CLAUDE.local.md ,.claude/rules/ |
Yes, when the project has no CLAUDE.md ; both with theclaude-md-and-agents-md mode. Needs fetched feature flags. |
Yes |
| OpenAI Codex | AGENTS.override.md orAGENTS.md , global then repo root down to the working directory |
Yes | Only if you add it to project_doc_fallback_filenames |
| Cursor | .cursor/rules/*.mdc ,AGENTS.md ,CLAUDE.md |
Yes, root and subdirectories | Yes, at the project root, applied to every conversation |
| Copilot cloud agent | .github/copilot-instructions.md ,.github/instructions/*.instructions.md |
Yes, anywhere; the nearest one wins | Yes, a single one at the repo root (or GEMINI.md ) |
| Copilot in VS Code | copilot-instructions.md ,*.instructions.md |
Yes ( chat.useAgentsMdFile ); nested files behindchat.useNestedAgentsMdFiles , off by default |
Yes, behind chat.useClaudeMdFile |
| Gemini CLI | GEMINI.md |
Only if listed in context.fileName |
Only if listed in context.fileName |
Sources: Claude Code memory, Codex AGENTS.md guide, Cursor rules, GitHub Copilot repository instructions, VS Code custom instructions, Gemini CLI context files.
Read the table by columns. AGENTS.md is the only file every tool here can read, Gemini CLI after one setting. CLAUDE.md is read by more tools than its name suggests, but not by Codex.
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.
Is it AGENTS.md or agent.md? #
AGENTS.md, plural and in capitals. s 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 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 opens 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.
| Symlink | @AGENTS.md import | |
|---|---|---|
| Setup | ln -s AGENTS.md CLAUDE.md |
A CLAUDE.md whose first line is@AGENTS.md |
| Claude-only notes | Not possible; the two files are one | Write them below the import |
| Windows clones | Git checks the link out as a one-line text file unless core.symlinks is enabled |
Works everywhere |
| Claude editing the file | Edit and Write refuse to write through the link and point at AGENTS.md | Claude edits either file directly |
| Other tools | Cursor and Copilot read both names, so they may load the same rules twice | Only Claude Code documents the @ import; the others readAGENTS.md on their own |
| Sessions without feature flags | Works | Works |
Claude Code skips a file it has already loaded, by path or by content, so neither setup makes Claude read the rules twice. The import also keeps working in sessions where native AGENTS.md support is off, such as Bedrock or telemetry disabled. The details of that 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.
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 a matching file is opened.
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.
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.
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
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, holds what it finds for approval under the gate you set, and serves Claude Code, Codex and Cursor 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.
Questions #
Is AGENTS.md the same as CLAUDE.md?
Both are plain markdown instructions an agent reads at session start. The difference is the : CLAUDE.md gets Claude Code features such as @ imports, CLAUDE.local.md and path-scoped rules, while AGENTS.md is the name most other coding agents read.
Does Cursor read CLAUDE.md?
Yes. Cursor reads a CLAUDE.md at the project root the same way it reads AGENTS.md and applies it to every Agent conversation. Rules do not apply to Tab completion, Inline Edit or Bugbot.
Does Codex read CLAUDE.md?
Not by default. Codex reads AGENTS.override.md or AGENTS.md in each directory from the repo root down, and reads other names only if you list them in project_doc_fallback_filenames in ~/.codex/config.toml.
Should I symlink CLAUDE.md to AGENTS.md?
It works, but an @AGENTS.md import in a real CLAUDE.md is safer. The import survives Windows clones, lets you add Claude-only notes below it, and works in sessions where Claude Code's native AGENTS.md support is off.