Where each AI coding tool reads its instructions

Every coding agent reads a file of project instructions before it starts: the commands, the conventions, the folders not to touch. They all agree that this file should exist. They do not agree on its name.

That matters the moment a project is shared between people who use different tools, or the day you switch. A rule written in the wrong file is not followed badly — it is not read at all, and nothing warns you.

The four tools at a glance

Each row was checked against the vendor’s own page: the Claude Code memory docs, Codex’s AGENTS.md guide, Gemini CLI’s GEMINI.md docs and Cursor’s rules docs. These details move, so when something behaves differently, the vendor’s page wins over this table.

Claude Code

CLAUDE.md is the file Claude Code was built around. It reads one from your working folder and every folder above it, plus your personal ~/.claude/CLAUDE.md, and joins them all rather than picking one.

AGENTS.md is read too, but only when none of these is in your working folder or above it: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md. If one is there, Claude reads the CLAUDE.md files only. You have two ways to keep AGENTS.md in play:

• put @AGENTS.md on the first line of your CLAUDE.md, which imports the file;
• or open /config and set Project instructions to claude-md-and-agents-md, which reads both.

Two catches worth knowing. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md counts as having a CLAUDE.md, so it quietly switches AGENTS.md off for you. And Claude Code never reads AGENTS.override.md or AGENTS.local.md — those are other tools' conventions.

Codex

Codex treats AGENTS.md as its own file. It reads one from its home folder first, then walks from the project root down to your current folder, and in each folder it takes AGENTS.override.md if there is one, otherwise AGENTS.md. Files nearer to you are added later, so their guidance overrides what came before.

Two settings shape this: project_doc_fallback_filenames lists other file names it should accept, and project_doc_max_bytes caps how much it reads in total. Once the files it has gathered reach that cap, it stops adding more, so a long file near the top of the project can crowd out the ones nearest to you. For the fine print of the chain, see Codex’s AGENTS.md guide.

Gemini CLI

Gemini CLI reads GEMINI.md: a global one in ~/.gemini/, the ones in your workspace and its parent folders, and subfolder files as it starts working in them. It joins them and sends the result with every prompt. /memory show prints what it loaded, and /memory reload re-reads the files after you edit them.

It does not read AGENTS.md unless you tell it to. The context.fileName setting in settings.json takes a name or a list of names:

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

Cursor

Cursor has two places for project instructions. Project Rules live in .cursor/rules/ as .mdc files, each with a small header that says when it applies: always, when the agent judges it relevant, when a file matches a pattern, or only when you mention it with @. A plain .md file in that folder is ignored, because it has no header.

The simpler option is AGENTS.md — plain Markdown, no header — at the root, and in any subfolder for instructions that only apply there. Nested files are combined with their parents, and the more specific one wins.

On top of the project sit User Rules (yours, for every project) and Team Rules (from a team dashboard). When they conflict, Team Rules come first, then Project Rules, then User Rules.

One file for everyone

If more than one of these tools touches the project, keep the shared rules in a single AGENTS.md and add only what each tool needs on top:

1. AGENTS.md holds the commands, conventions and no-go folders. Codex and Cursor read it as it is.
2. Claude Code reads it too, as long as there is no CLAUDE.md. When you need Claude-specific lines, add a short CLAUDE.md that starts with @AGENTS.md and puts those lines below it.
3. Gemini CLI gets "fileName": ["AGENTS.md", "GEMINI.md"] in its settings.
4. Cursor needs nothing. Reach for .cursor/rules/*.mdc only for rules that should apply to some files and not others.

Whatever the tool, the same test tells you the file worked: ask the agent what its project instructions say, or use its own view of what loaded — /context in Claude Code, /memory show in Gemini CLI.