AGENTS.md vs CLAUDE.md vs GEMINI.md

What are these three files?

Each one is a markdown file of standing instructions that a coding agent reads before it works. The difference is who reads which.

AGENTS.md describes itself as a simple, open format for guiding coding agents, a README for agents. Your README is for humans, and AGENTS.md holds the extra context agents need: build steps, tests and conventions that would clutter a README. CLAUDE.md is the file Claude Code loads at the start of every session. GEMINI.md is the default name for Gemini CLI’s context files.

You do not need three copies. You need one source of truth and a way for each tool to find it.

Which agent reads which file?

As of October 2026, according to each tool’s documentation:

Claude Code reads CLAUDE.md. In versions 2.1.277 and later it also reads AGENTS.md as your project instructions, but by default only when there is no CLAUDE.md in your working directory or above it. If both exist, it reads the CLAUDE.md files. See Anthropic’s memory docs.

Codex reads AGENTS.md before it does any work. It builds a chain: a global file in ~/.codex, then one file per directory from the project root down to your current folder, with files closer to you overriding earlier ones. An AGENTS.override.md takes precedence in a directory, and the combined size stops at 32 KiB by default. See the Codex guide.

Gemini CLI reads GEMINI.md, from ~/.gemini/, from your workspace and its parent folders, and from folders it touches as it works. Its context.fileName setting accepts a list of names, and its docs show AGENTS.md as one of them. See the GEMINI.md docs.

Cursor’s CLI reads AGENTS.md and CLAUDE.md at the project root and applies them as rules next to .cursor/rules. Cursor also supports nested AGENTS.md files in subdirectories. See its CLI docs and rules docs.

What is the simplest setup that works for all of them?

Put the real content in AGENTS.md, then point the others at it.

For Claude Code, create a CLAUDE.md that imports it. Anthropic documents this pattern: a file containing @AGENTS.md, followed by anything specific to Claude, such as “Use plan mode for changes under src/billing/.” A symlink also works (ln -s AGENTS.md CLAUDE.md), but Anthropic warns that on Windows creating one needs administrator rights or Developer Mode, and that Git checks a committed symlink out as plain text unless core.symlinks is enabled. Use the import if anyone on your team uses Windows.

Watch for one trap. A CLAUDE.local.md file counts as a CLAUDE.md, so adding one to a project that relies on AGENTS.md stops Claude Code from reading AGENTS.md by default. A CLAUDE.md that imports @AGENTS.md avoids the surprise.

For Gemini CLI, add the name to your settings.json: {"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}}.

Codex and Cursor need nothing.

What belongs in the file?

Only what the agent cannot work out by reading the code. Anthropic’s best practices give a good list. Include the commands the agent cannot guess, the code style rules that differ from the defaults, how to run tests, repository etiquette such as branch names, architecture decisions specific to your project, quirks of your development environment, and gotchas that are not obvious.

A good file is short. How to install. The one command that checks everything. How to run a single test. Two or three rules that must hold, such as never editing tests/ without being asked, or asking before adding a dependency. And the gotchas that waste an hour, such as the dev server needing DATABASE_URL, so copy .env.example.

Leave out what the agent can read from your code, standard conventions it already knows, long API documentation (link to it instead), anything that changes often, and self-evident advice like “write clean code.” Anthropic’s test for each line is: would removing this cause the agent to make mistakes? If not, cut it.

Length matters. Anthropic suggests staying under 200 lines for a CLAUDE.md, because longer files consume more context and reduce adherence, and Codex stops reading at 32 KiB by default. A bloated file does not just cost tokens, it buries the rules you care about.

What should not go in it?

Secrets, for a start: the file is committed and read by every tool. And anything that must always be true.

An instructions file is advice, and Anthropic says as much: instructions are advisory, while hooks are deterministic. If “never edit the tests” must hold, enforce it with a permission rule or a hook, and keep the sentence in the file as the explanation.

How do you check that an agent loaded it?

Ask the tool. In Claude Code, run /context and confirm your instructions appear under memory files. In Codex, run codex --ask-for-approval never "Summarize the current instructions." from your project root, and it should quote your files. In Gemini CLI, /memory show prints the combined context it is using, and /memory reload rescans the files.

Then treat the file like code. Review changes to it, prune it when an agent ignores a rule, and test a change by watching whether behavior actually shifts.

One file, several agents, one window

SwarmPane’s Agent Grid runs Claude Code, Codex, Gemini CLI and other agents side by side in real terminals, so a shared instructions file earns its keep. Each CLI reads it the way its own docs describe. SwarmPane’s own Skills are reusable instructions that are included whenever you assign the skill to a teammate.

SwarmPane runs the CLIs and accounts you already have. Start with a 7-day trial for $1 and run your agents on one shared file.