AGENTS.md vs CLAUDE.md vs GEMINI.md: which file should you use?

If you use more than one coding agent, keep shared rules in AGENTS.md. Codex reads it directly. Import it from a small CLAUDE.md for Claude Code, and add AGENTS.md to Gemini CLI's context.fileName setting. Keep tool-specific behavior in the vendor file.

Quick decision table

• Codex only: root AGENTS.md, with nested files for monorepo packages when needed.
• Claude Code only: CLAUDE.md, plus .claude/rules/ for path-specific details.
• Gemini CLI only: the default GEMINI.md, or a filename selected in settings.
• Codex + Claude Code + Gemini CLI: AGENTS.md as the shared source, with thin adapters for the other two tools.

AGENTS.md is described as an open Markdown format for setup, testing, and coding instructions. It has no required fields, and in nested trees the file closest to the edited file takes precedence.[1] That makes it a useful portable base.

The tools do not load instructions the same way

Codex builds an instruction chain at session start, from global guidance through the project root to the working directory. OpenAI's documentation says files closer to the working directory appear later and can override earlier guidance; the default combined limit is 32 KiB.[2] These are OpenAI's descriptions of its own product behavior.

Claude Code does not read AGENTS.md directly. Anthropic recommends importing it from CLAUDE.md with @AGENTS.md, or using a symlink, then adding Claude-only rules below the import.[3] Anthropic also says these instructions are model context rather than enforced policy.[3]

Gemini CLI defaults to GEMINI.md. Google's documentation says it combines global, workspace, and just-in-time directory context. You can configure context.fileName to load names such as AGENTS.md, CONTEXT.md, and GEMINI.md.[5] These are Google's descriptions of its own product behavior.

A portable setup

Put only shared, verifiable rules in the root AGENTS.md:

• Install: npm ci
• Check: npm run check
• Build: npm run build
• Boundary: do not edit generated files under dist/ and never commit .env files.
• Done means: run check and build, then report changed files and failed checks.

The Claude adapter can stay small: put @AGENTS.md on the first line, then add only Claude-specific rules below it. If you want one source in Gemini CLI, use only AGENTS.md in the context.fileName list.

You can load several names, but copying the same rule into three files creates conflicts and stale instructions. Treat vendor files as compatibility layers, not copies of the shared source.

What belongs in the file?

Use AGENTS.md for setup commands, tests, directory boundaries, and a clear definition of done. Leave out secrets, temporary task notes, long product histories, and details the agent can reliably derive from the code.

If you have not chosen a tool, start with the Codex CLI vs Claude Code vs Gemini CLI guide. An instruction file does not replace model selection either; the GPT-5.6 Sol, Terra, and Luna pillar guide handles that layer separately.

Instruction files guide behavior; they do not guarantee the result. Set access with the coding-agent permission modes guide, then independently check the change with the coding-agent output verification checklist.