# Where each AI coding tool reads its instructions

Course: Which AI Coding Tool? — https://zero2vibecode.com/learn/ai-coding-tools
Canonical URL: https://zero2vibecode.com/learn/ai-coding-tools/1-4-where-each-tool-reads-its-instructions
Verified against: Claude Code v2.1.306 (2026-10-22)
Last updated: 2026-10-22

Claude Code, Codex, Gemini CLI and Cursor each read project instructions from a different file, in a different order. One AGENTS.md can serve all four, if you know which of them needs an extra line.

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

| Tool | Project file | Other places it reads | When files overlap | Reads AGENTS.md? |
|---|---|---|---|---|
| Claude Code | `CLAUDE.md` or `.claude/CLAUDE.md` | your `~/.claude/CLAUDE.md`, a personal `CLAUDE.local.md`, `.claude/rules/`, subfolders as it works there | all files are joined, broadest first, so the one nearest your folder is read last | Yes, when there is no `CLAUDE.md` |
| Codex | `AGENTS.md` | the Codex home folder (`~/.codex`), then every folder from the project root down to yours | files nearer your folder come later and override earlier guidance | Yes — it is the main file |
| Gemini CLI | `GEMINI.md` | `~/.gemini/GEMINI.md`, parent folders, subfolders as it works there | all files are joined and sent with every prompt | Only if you add it to `context.fileName` |
| Cursor | `.cursor/rules/*.mdc` | `AGENTS.md`, User Rules, Team Rules | Team Rules, then Project Rules, then User Rules — earlier ones win a conflict | Yes, at the root and in subfolders |

Each row was checked against the vendor's own page: the [Claude Code memory docs](https://code.claude.com/docs/en/memory), [Codex's AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [Gemini CLI's GEMINI.md docs](https://www.geminicli.com/docs/cli/gemini-md) and [Cursor's rules docs](https://cursor.com/docs/context/rules). 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](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

## 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:

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

**Check which CLI your account gets.** 
For unpaid-tier and Google One accounts, Google has replaced Gemini CLI with Antigravity CLI — the notice sits at the top of the [Gemini CLI README](https://github.com/google-gemini/gemini-cli). If that is your account, check Antigravity's own docs for where it reads instructions instead of relying on this section.

## 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.

**Check the file itself.** 
The [CLAUDE.md checker](https://zero2vibecode.com/claude-md-checker) flags the mechanical problems — vague rules, missing commands, an AGENTS.md mentioned but never imported — and has annotated before-and-after examples to start from.