CLAUDE.md vs AGENTS.md vs GEMINI.md: keep one source of truth across three tools

Run Claude Code, Codex and Gemini CLI on the same repository and you end up with three context files: CLAUDE.md, AGENTS.md and GEMINI.md. Write the same content in three places and they drift apart with every update.

This article compares how the three files are loaded, then shows a layout where one source file feeds all three tools.

The three files side by side

Aspect	CLAUDE.md (Claude Code)	AGENTS.md (Codex and others)	GEMINI.md (Gemini CLI)
User scope	~/.claude/CLAUDE.md	~/.codex/AGENTS.md	~/.gemini/GEMINI.md
Project scope	CLAUDE.md or .claude/CLAUDE.md at the root	AGENTS.md at the root	GEMINI.md at the root
Personal, untracked	CLAUDE.local.md	— (use .gitignore)	— (use .gitignore)
Subdirectories	Supported, loaded when working in that directory	Supported, deeper files take precedence	Supported
Pulling in other files	@path import syntax	— (reference the path in prose)	— (reference the path in prose)
Renaming the file	Not possible	Not possible	Possible via context.fileName in settings.json
Scaffold command	/init	/init	/init
Check what loaded	/context	/status	/memory show

All three play the same role: background the agent should have before it starts. The content you want in them is the same too, so the only real difference is the loading mechanism, which leaves plenty of room to share.

Option 1: make AGENTS.md the source and import it from CLAUDE.md

AGENTS.md is a format several tools already read, which makes it a good source file. Claude Code can pull in other files with @ import syntax.

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code specifics
- Use plan mode to propose an approach before touching more than three files
- Use the code-reviewer subagent for reviews

Claude Code now reads both the shared content and the Claude-specific instructions.

Option 2: point Gemini CLI at AGENTS.md

Gemini CLI lets you change the filename it loads.

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

Put this in ~/.gemini/settings.json for user scope or .gemini/settings.json for the project. The documentation states that context.fileName accepts either a single string or an array of strings. Use the array form to load AGENTS.md for shared content and GEMINI.md for tool-specific instructions. If one file is enough, write "fileName": "AGENTS.md" and keep the Gemini-specific notes as a section inside AGENTS.md.

Option 3: symlink

This is the fallback when neither imports nor configuration are available.

ln -s AGENTS.md GEMINI.md

Git tracks symlinks, but teammates on Windows get inconsistent behavior. Prefer options 1 and 2 when they are available to you.

Recommended layout

repository/
├── AGENTS.md            # Source: shared commands, conventions, do-not-touch list, workflow
├── CLAUDE.md            # @AGENTS.md plus Claude Code specifics
├── .gemini/
│   └── settings.json    # context.fileName pointing at AGENTS.md (plus GEMINI.md)
├── GEMINI.md            # Gemini CLI specifics (optional)
└── docs/
    └── architecture.md  # Long documents live separately, referenced by path

Write AGENTS.md in a way that names no particular tool.

# Project overview
(one or two lines)

## Commands
- Test: `pnpm test`
- Lint and typecheck: `pnpm lint && pnpm typecheck`

## Conventions
- ...

## Do not change
- ...

## How to work
- Read the related tests before changing anything
- Propose an approach before a change that spans multiple files
- Do not report completion while tests are failing

## References
- Architecture: docs/architecture.md

Feature names that belong to one tool, such as plan mode or subagents, go in that tool's own file.

What belongs in the tool-specific file

Tool	Examples of tool-specific instructions
Claude Code	When to use plan mode, which subagents to use, which skills exist
Codex	Preferred profile name, when to use codex exec
Gemini CLI	Using checkpoints, what to store with /memory add

For how to write each file, see How to write CLAUDE.md and Installing Gemini CLI and writing GEMINI.md. For a broader comparison of two of the tools themselves, see Codex vs Claude Code.

Subdirectories

All three tools support context files in subdirectories. In a monorepo, put the overall policy at the root and package-specific rules in each package. Keep the same pattern there: the source is the AGENTS.md at each level, and the CLAUDE.md beside it holds just the @AGENTS.md line.

Summary

• The three files have the same role and the same content; only the loading mechanism differs
• Make AGENTS.md the source, import it from CLAUDE.md, and point Gemini CLI at it with context.fileName
• Tool-specific feature names (plan mode, profile names) belong in that tool's own file
• Avoid copy-based syncing and use each tool's referencing mechanism instead