CLAUDE.md vs AGENTS.md vs GEMINI.md: One Project, Three Agents

Your team runs Claude Code on the backend, someone else drives Codex CLI against the same repository from a script, and a third person tried Gemini CLI last week because it came free with their Google account. Three tools, one codebase, and now three instruction files sitting in the project root with no guarantee any of them are reading the same rules. This post is a straight field-by-field comparison of what CLAUDE.md, AGENTS.md, and GEMINI.md each actually do, followed by three concrete ways to keep one source of truth instead of three copies drifting apart. It does not tell you which agent to run; that's a separate decision.

The one-line version of each file

CLAUDE.md is Claude Code's own instruction file: markdown you write, loaded at the start of every session, read from your working directory up through every parent directory, the same directory-scoped pattern behind keeping one client's rules from bleeding into another's repo. AGENTS.md is a vendor-neutral standard, described by its own maintainers as "a README for agents," read natively by more than 20 tools including Codex CLI, Cursor, Aider, and Devin. GEMINI.md is Gemini CLI's equivalent, assembled from a global file in your home directory, the project root and its ancestors, and a live scan of the directory you're working in. All three do the same basic job: give an agent standing context about a codebase before it touches any code. Where they diverge is location, how multiple files combine, how big they can get, and whether the agent itself can add to them.

CLAUDE.md, AGENTS.md, and GEMINI.md side by side

Every row in that table is doing real work later in this post, so it's worth reading closely once before moving on.

CLAUDE.md: nested files, imports, and the practical line ceiling

Claude Code's own documentation describes the resolution order in its memory guide: CLAUDE.md and CLAUDE.local.md load from the working directory and every directory above it, concatenated from the filesystem root down, so a project-level file is read after a user-level one and effectively carries more weight. Nested CLAUDE.md files inside subdirectories aren't loaded at launch; Claude picks them up on demand as it reads files in that subdirectory, which is also how a monorepo's per-package rules stay out of context until they're relevant. The same doc covers @path/to/file imports, which pull in a README or a shared guide at launch, with recursive imports capped at a maximum depth of four hops. None of that changes the practical ceiling: Claude Code recommends under 200 lines per file, and files longer than that measurably reduce how consistently instructions get followed, a failure mode covered in more depth in why a bloated CLAUDE.md gets ignored. The hard technical limit sits far above that, at 4 MiB, past which Claude Code skips the file rather than truncating it.

AGENTS.md: the cross-vendor format, and Codex CLI's 32 KiB cap

AGENTS.md isn't any one vendor's file. Its own site describes it as an open, unopinionated markdown format, deliberately separate from README.md so that "build steps, tests, and conventions" don't clutter documentation meant for people. The written standard describes precedence as closest-file-wins, not concatenation: for a monorepo, "place another AGENTS.md inside each package" and "the closest one takes precedence." Codex CLI's own implementation goes further than the spec requires and concatenates anyway. The standard itself sets no size limit, but its heaviest reader does. Codex CLI's own guide states plainly that Codex "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)," walking up from wherever you're working to the directory containing .git and concatenating whatever AGENTS.md files it finds along the way, closest one last. Files past the cap are truncated silently, which is the actual production failure: a root AGENTS.md plus a few nested ones in a large repo hits 32 KiB more easily than it looks, and nothing in the terminal tells you a section got dropped. project_doc_max_bytes = 65536 in ~/.codex/config.toml is the fix once you notice.

GEMINI.md: hierarchical assembly and the /memory command

Gemini CLI's own documentation describes three tiers: a global ~/.gemini/GEMINI.md for defaults across every project, a project-root file for the current repository, and subdirectory files the CLI discovers by scanning ancestors up to a trusted root as it works. All discovered files get concatenated and sent to the model with every prompt, and like CLAUDE.md, GEMINI.md supports breaking a large file into pieces with an @file.md import, accepting both relative and absolute paths. The distinct feature is /memory, a command with four documented sub-commands: add appends text to the file directly from chat, show prints the full concatenated memory so you can see exactly what the model is seeing, refresh re-scans every GEMINI.md location after you've edited one by hand, and list prints the paths currently in use. That add sub-command is backed by a save_memory tool the model can call on its own, which means GEMINI.md is the only one of the three where writing to the file is a documented, first-class capability rather than something you do with a text editor.

What all three share, and the one thing none of them do

Strip away the filenames and the mechanism is identical: a hierarchy of markdown files, walked from broad to specific, concatenated into context before the agent does anything else. All three are static by default and all three assume a human wrote most of what's in them. Where they actually diverge is what happens once an agent learns something mid-session that's worth keeping. Claude Code's auto memory can write that down, but it's explicitly machine-local: a teammate on a different laptop, or the same repo cloned fresh in CI, starts from zero. AGENTS.md has no write path in the spec at all; it's a document you maintain, not one the agent updates. Gemini CLI's save_memory tool comes closest to a real answer, but it still writes into a file that lives on one machine unless someone commits it, and nothing distinguishes an entry the model wrote from one a person typed. None of the three formats gives a team a durable, shared record of what a project has already learned that every session, and every person's agent, reads automatically. That's the specific gap Trail is built around: project reference memory that lives outside any one agent's config, written by whichever session hits a gotcha, and read by the next session that opens the same project folder, whether that's a teammate's Claude Code, their own Codex CLI, or Gemini CLI six weeks later.

Strategy A: one real file, two symlinks

The cheapest fix is to stop maintaining three files and admit you only have one. Keep AGENTS.md as the canonical document, since it's the one format none of the three agents treats as second-class. Claude Code's own docs give you the exact command: ln -s AGENTS.md CLAUDE.md, which "prints no output on success" and shows up under Memory files the next time you run /context. Gemini CLI doesn't need a symlink at all; its context.fileName setting in settings.json accepts an array, so setting "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } points it at the same file directly. One edit, three agents reading it, zero drift. The tradeoff is real: you lose the ability to say something Claude-only or Gemini-only without it showing up for the other tool too, and on Windows, symlinks need Administrator rights or Developer Mode, so the @AGENTS.md import Claude Code also supports is the safer default there.

Strategy B: a thin file per agent, one shared document

When the agents genuinely need different instructions, split the difference instead of forcing one file to serve three masters. Keep the shared rules in AGENTS.md, then give each agent a thin file that imports it and adds a few lines of its own. Claude Code's documentation shows exactly this pattern: @AGENTS.md on the first line of CLAUDE.md, followed by a short "## Claude Code" section with Claude-specific instructions like "use plan mode for changes under src/billing/." The same shape works for GEMINI.md. You keep genuine per-agent flexibility, at the cost of three files to check whenever the shared instructions change, since an import only pulls content in, it doesn't warn you the source moved.

Strategy C: keep instructions in the files, move knowledge out of them

Both strategies above assume the problem is duplication. Sometimes the real problem is that the file is doing two jobs: holding instructions ("always run make lint before committing") and holding knowledge ("the payments webhook silently retries three times before failing, we found this the hard way in March"). Instructions belong in the file because every session needs them immediately. Knowledge like that gotcha doesn't need to sit in context on every single prompt; it needs to be findable the moment it's relevant, the same argument covered in why an agent keeps repeating the same mistake. Moving that second category out to an external tracker or memory system keeps all three instruction files short enough to stay under their respective ceilings, and it stops three people from independently discovering and re-writing the same gotcha into three different files.

Which strategy fits which team size

What breaks when a second person joins the repo, and what to do about it

Every strategy above works fine for one person. It's the second person that exposes the gap: they clone the repo, get the shared AGENTS.md or its symlinked copies through git, and immediately miss everything that lived only in someone's local auto memory or a personal GEMINI.md /memory add session. Nothing in any of the three formats is built to survive that handoff, because none of them were designed as team-shared, agent-written memory in the first place; they're instruction files that happen to be committed to git, not project journals.

If you're one developer on one agent, Strategy A costs nothing and solves the whole problem: one file, two links, done. If your team is small but genuinely running Claude Code, Codex CLI, and Gemini CLI side by side with real per-agent differences, Strategy B is worth the extra file. Once a second or third person is regularly hitting the same discovered gotchas independently, or a CLAUDE.md keeps creeping past 200 lines because gotchas keep getting stuffed into it, that's the signal to stop treating the instruction file as the record of everything the project knows and start keeping that knowledge somewhere built for it. The wider comparison of what those tools look like is covered in agent-native issue trackers compared, and for teams weighing a local-first, file-based option against a hosted one, Beads against a hosted tracker's local-first limits lays out that tradeoff directly.