AGENTS.md vs CLAUDE.md

The short version

• AGENTS.md is an open format, described at agents.md as "a README for agents". It has no required fields: "AGENTS.md is just standard Markdown." Codex, Cursor, GitHub Copilot, VS Code, Zed, Jules, Aider and many others read it. Cursor and Copilot also have their own formats (see Cursor rules and Copilot custom instructions), and Gemini CLI can be told to read AGENTS.md (see GEMINI.md for Gemini CLI).
• CLAUDE.md is Claude Code's instruction file. It adds Claude-specific features: @path imports, CLAUDE.local.md for personal notes, a user-level ~/.claude/CLAUDE.md, and rules in .claude/rules/.
• Claude Code reads AGENTS.md since v2.1.277, but by default only when you have no CLAUDE.md. If you have both, it reads CLAUDE.md and ignores AGENTS.md, unless CLAUDE.md imports it.

What Claude Code reads

Anthropic's memory docs give the default behaviour as a table. Paraphrased with the exact outcomes:

Three details from the same section matter:

• CLAUDE.local.md counts. Adding a personal, git-ignored CLAUDE.local.md to a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you. Your ~/.claude/CLAUDE.md and .claude/rules/ files do not count, and keep loading alongside AGENTS.md.
• Subfolders work too. A subfolder's AGENTS.md loads when Claude opens a file there, if that folder has no CLAUDE.md of its own. Inside AGENTS.md, @path imports are expanded just as in CLAUDE.md.
• You can change the default. The Project instructions setting (in /config) has a claude-md-and-agents-md value that loads both, each folder's CLAUDE.md first and its AGENTS.md after.

In an interactive session that picked up AGENTS.md you will see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Run /context to check what loaded.

What Codex reads

The Codex AGENTS.md docs describe a different discovery model:

• A global file first: ~/.codex/AGENTS.override.md, else ~/.codex/AGENTS.md.
• Then, from the Git root down to your working folder, in each folder AGENTS.override.md, then AGENTS.md, then any names you list in project_doc_fallback_filenames.
• Codex "concatenates files from the root down", so "files closer to your current directory override earlier guidance because they appear later in the combined prompt."
• A size cap: Codex "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)." In Codex's source, the file that crosses the limit is cut off at it, and the files after it are not read.

That last point is the one that surprises people. A 30 KB root AGENTS.md leaves almost no room for the nested ones, and the instructions closest to the code you are working on are the ones that get dropped. If you see Codex ignoring a subfolder's AGENTS.md, check the total size first.

Differences that bite

The comment row matters for review. A comment in a shared AGENTS.md is invisible on GitHub's rendered view but is plain text to an agent. Read the raw file, or see how to spot hidden instructions in AGENTS.md.

Keeping one file for every agent

If your team uses more than one agent, keep the shared instructions in AGENTS.md and make CLAUDE.md a thin wrapper. This is the pattern Anthropic's docs show:

@AGENTS.md

## Claude Code

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

Claude Code reads AGENTS.md once through the import, whichever Project instructions value is set, and you have a place for anything Claude-specific. Codex, Cursor and the rest read AGENTS.md directly and ignore CLAUDE.md.

A symlink (ln -s AGENTS.md CLAUDE.md) also works if you need no Claude-specific lines, with two caveats from the docs: Claude Code's Edit and Write tools refuse to write through a symlink and edit the target instead, and on Windows a committed symlink can check out as a one-line text file unless core.symlinks is enabled. If anyone on the team uses Windows, prefer the import.

Avoid the other common workaround, a CLAUDE.md that says in words "read AGENTS.md". The docs point out that Claude "sees AGENTS.md only if it decides to open the file."

Which should you use?

• Only Claude Code on the project: CLAUDE.md. You get imports, local notes and rules with no extra file.
• Several agents, or an open-source project where contributors bring their own: AGENTS.md as the source of truth, plus a two-line CLAUDE.md that imports it.
• An existing repository with only AGENTS.md: nothing to do on Claude Code v2.1.277 or later, as long as nobody adds a CLAUDE.local.md. Check with /context.
• A large monorepo used with Codex: keep the root AGENTS.md short. Moving detail into nested AGENTS.md files does not get you round the 32 KiB cap: every file from the root down to your working folder shares it, and the nested ones are cut first. Codex only reads that one chain of folders, so files in sibling packages do not add up, but the root file plus the nested files on any one path must fit in 32 KiB. Put long reference material in ordinary docs the agent can open when it needs them, or raise project_doc_max_bytes.

Whichever you choose, the writing advice is the same: short, concrete and free of contradictions. See CLAUDE.md best practices, and for what each file costs, how many tokens a CLAUDE.md costs.

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

Sources, read on 14 October 2026: Claude Code docs, AGENTS.md section of How Claude remembers your project; OpenAI, Codex AGENTS.md discovery and agents_md.rs in the Codex source; agents.md. Quotes are exact. Behaviour can change between releases; the version numbers are those the docs give. Related: Cursor rules, GitHub Copilot custom instructions, GEMINI.md for Gemini CLI.