AGENTS.md vs CLAUDE.md: one file for every agent?

We make Shuriken. We tried to be fair; corrections welcome at office@shuriken.sh.

Quick answer#

In the AGENTS.md vs CLAUDE.md choice, make AGENTS.md the one source. Codex reads it natively. Claude Code has read it since v2.1.277, but only when the project has no CLAUDE.md, so for Claude-only lines keep a CLAUDE.md that starts with @AGENTS.md. Gemini CLI reads GEMINI.md until you point it at AGENTS.md.

Both files are a README for agents. AGENTS.md is the name many tools agreed on, and CLAUDE.md is Claude Code's own, with imports, path rules and a private layer on top. Each tool's docs below were read on 22 October 2026.

At a glance#

What AGENTS.md does well#

The AGENTS.md site calls it "a simple, open format for guiding coding agents", "now stewarded by the Agentic AI Foundation under the Linux Foundation". Its list of tools that read the file has Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Aider, goose, opencode, Zed, Warp, Junie and Amp on it, and more. A new agent you install has a good chance of finding it without any setup.

There is no syntax to learn. The site's own line is "Think of AGENTS.md as a README for agents."

In a monorepo, "the closest AGENTS.md to the edited file wins". Codex's docs give the order: from the project root down to your working folder, at most one file per folder, and "files closer to your current directory override earlier guidance because they appear later in the combined prompt."

What CLAUDE.md does well#

CLAUDE.md is Claude Code's file, and Claude Code's memory docs list what comes with it:

• @docs/git-instructions.md imports another file, up to four hops deep
• files in .claude/rules/ with a paths: list load only when Claude touches a matching file
• CLAUDE.local.md sits next to the team file for your own notes
• auto memory, Claude's own notes, loads alongside your instructions
• /memory opens the files, /context shows which ones loaded, and InstructionsLoaded hooks fire when they load

An AGENTS.md that Claude Code reads directly gets most of this. The docs list three differences: InstructionsLoaded hooks don't fire for it, an AGENTS.md in a folder added with --add-dir doesn't load, and an @path import outside your project loads only if you already approved external imports.

How to keep one source for every agent#

Each of these keeps a single AGENTS.md as the source.

AGENTS.md only#

Delete CLAUDE.md. Claude Code (v2.1.277+), Codex and the tools on the AGENTS.md list read the file as it is. Anthropic's docs flag one catch: a CLAUDE.local.md counts as a CLAUDE.md, so adding one for private notes stops Claude from reading AGENTS.md. Setting Project instructions to claude-md-and-agents-md in /config keeps both.

A CLAUDE.md that imports AGENTS.md#

This is the layout Anthropic shows, and the one that bends furthest:

@AGENTS.md

## Claude Code

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

Claude reads AGENTS.md first, then the Claude-only lines under it. It also works in sessions that can't read AGENTS.md directly, such as older versions.

A symlink#

ln -s AGENTS.md CLAUDE.md is fine while the two files never differ. The docs give two caveats. Claude's Edit tool won't write through a symlink (it edits the target instead), and on Windows Git checks a committed symlink out as a one-line text file unless core.symlinks is on. If anyone clones on Windows, use the import.

Our own repository does it the other way round: AGENTS.md is a link to CLAUDE.md, at the root and in packages/server. We develop on Macs and Linux machines, so it works for us, and the Windows caveat would apply to us too.

Gemini CLI#

Gemini CLI takes its file names from context.fileName in settings.json, so list both:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

A GEMINI.md whose only line is @AGENTS.md does the same job. Gemini CLI's docs now carry a notice for unpaid-tier and Google One users: "Gemini CLI was replaced by Antigravity CLI on June 18th, 2026." On those tiers, look up which file Antigravity CLI reads before you rely on GEMINI.md or AGENTS.md.

Where Shuriken is different#

Shuriken runs Claude Code, Codex, Gemini CLI and 64 more agents in the same project, so we met the "which file?" question early. After you add a project, Shuriken opens a sheet that makes AGENTS.md the single instruction file, with "Set up later" and "Don't ask again" if you'd rather not. What the sheet offers depends on the files it finds:

For a merge, the sheet shows the model and the rough cost first, and you review the result before anything is written. Then Shuriken points every other agent at AGENTS.md: a CLAUDE.md, GEMINI.md or QWEN.md that imports it with @AGENTS.md, a one-line reference in Copilot's instructions file, and read: AGENTS.md in Aider's config. Agents that read AGENTS.md natively get nothing extra. Scoped rule folders such as .cursor/rules stay where they are, and the originals are copied to a backup folder first. In the project's Knowledge section, the Instructions card then lists AGENTS.md as the file every agent reads, and each pointer as Linked, or as "Has its own content" once someone has typed into it.

Personal files work across accounts too. Every Claude account you add gets its own CLAUDE_CONFIG_DIR, and every Codex account its own CODEX_HOME. Shuriken links your ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md into each of those folders, so a switch to another account keeps the same instructions. Running both agents on one repo is covered in Claude Code and Codex in one project.

Cost#

Both are plain text files, and Shuriken's setup for them is on every plan. The optional merge is the one exception: that helper-model call is billed to your own source, and the sheet shows the model and its rough cost before you run it, or says the cost is unknown.

The file's real price is context. Every agent that reads it loads all of it at the start of every session. Anthropic aims for under 200 lines per file, and Codex stops adding files at 32 KiB. How to keep it short is in what Claude Code remembers between sessions; what goes in it, under either name, is in CLAUDE.md best practices.

Using them together#

Both names can live in one repository with one text behind them. Keep AGENTS.md as the shared source, with the common rules in it. CLAUDE.md, when Claude Code needs lines of its own, starts with @AGENTS.md, and GEMINI.md can do the same. Choosing between the agents themselves rather than their files is Claude Code vs Codex.