# AGENTS.md vs CLAUDE.md: Where Claude Code, Codex and Cursor Read Their Instructions (2026)

Source: https://lotsnotes.com/blog/agents-md-vs-claude-md
Published: 2026-10-14T03:31:13.099927+00:00

Claude Code reads `CLAUDE.md`, and since v2.1.277 it also reads `AGENTS.md`, but by default only when no `CLAUDE.md` or `CLAUDE.local.md` sits in your working directory or above it. Codex, Cursor and GitHub Copilot's agents read `AGENTS.md`; Gemini CLI reads `GEMINI.md` unless you tell it to read `AGENTS.md`. The setup that works everywhere: keep your instructions in one `AGENTS.md` and add a `CLAUDE.md` whose first line is `@AGENTS.md`.

I run every LotsTech agent from shared instructions, so I care which file each tool actually opens. I read each vendor's own docs on 13 October 2026 (links at the end). Here is what they say today, file by file, and the setup I'd use.

## AGENTS.md vs CLAUDE.md at a glance

Checked on 13 October 2026 in each vendor's own documentation.

| Tool | File name(s) | Where it looks | Which wins | Imports | Notes |
|---|---|---|---|---|---|
| **Claude Code** | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md`; `AGENTS.md` and `.claude/AGENTS.md` | Managed policy file, `~/.claude/CLAUDE.md`, every directory from the root down to where you launch, subdirectories on demand | Nothing overrides: all files are concatenated, root first, so the file closest to you is read last. `AGENTS.md` loads only if no `CLAUDE.md` or `CLAUDE.local.md` exists on the path (default setting) | Yes, `@path`, up to four hops deep | Reads `AGENTS.md` directly from v2.1.277. Never reads `AGENTS.override.md`, `AGENTS.local.md` or `.agents/` |
| **Codex** | `AGENTS.md`, `AGENTS.override.md`, plus any names in `project_doc_fallback_filenames` | `~/.codex` (or `CODEX_HOME`), then every directory from the Git root down to where you run it | At most one file per directory, override first. Files are joined root first, so closer files override earlier guidance | Not covered on the AGENTS.md page | Stops at 32 KiB combined (`project_doc_max_bytes`) |
| **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md`, User Rules, Team Rules | Project rules folder, `AGENTS.md` in the root and any subdirectory, Customize settings, team dashboard | Team Rules, then Project Rules, then User Rules; nested `AGENTS.md` combine with parents, more specific wins | `@file` mentions are not inlined; the agent opens the file when it needs it | A plain `.md` file in `.cursor/rules` is ignored: rules need the `.mdc` extension |
| **Gemini CLI** | `GEMINI.md` by default; any names in `context.fileName` | `~/.gemini/GEMINI.md`, workspace directories and their parents, then directories a tool touches | All found files are concatenated and sent with every prompt | Yes, `@file.md`, relative or absolute | Set `"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}` to read `AGENTS.md` |
| **GitHub Copilot** (on GitHub) | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `AGENTS.md`, or one root `CLAUDE.md` or `GEMINI.md` | Repository; personal and organization instructions too | Nearest `AGENTS.md` wins; personal instructions first, then repository, then organization | Not covered on the instructions page | Path files use `applyTo` globs; code review reads instructions from the head branch |

## Claude Code: CLAUDE.md first, AGENTS.md when there is no CLAUDE.md

Anthropic's memory docs list four places for `CLAUDE.md`, loaded from broadest to most specific:

1. **Managed policy**, set by IT: `/Library/Application Support/ClaudeCode/CLAUDE.md` on macOS, `/etc/claude-code/CLAUDE.md` on Linux and WSL, `C:\Program Files\ClaudeCode\CLAUDE.md` on Windows. Users can't exclude it.
2. **User**: `~/.claude/CLAUDE.md`, for your own preferences in every project.
3. **Project**: `./CLAUDE.md` or `./.claude/CLAUDE.md`, committed for the team.
4. **Local**: `./CLAUDE.local.md`, your personal notes for one project; add it to `.gitignore`.

Claude Code loads every `CLAUDE.md` and `CLAUDE.local.md` from your working directory and each directory above it at launch, and picks up files in subdirectories when it reads or edits a file there. Nothing overrides anything: the files are joined, root first, so the instructions nearest to where you started are read last. If two of them contradict each other, the docs say Claude may follow either one. Keep each file under about 200 lines; imports help you organize a long file but don't reduce its context cost.

**Imports.** Write `@path/to/file` anywhere in a `CLAUDE.md` and Claude Code expands that file into context at launch. Paths are relative to the file that holds the import, imports can nest four hops deep, and an import inside backticks stays plain text. The first time a project imports a file from outside your working directory, Claude Code asks you to approve it.

**AGENTS.md.** This is the change most older articles miss. Claude Code now reads `AGENTS.md` without any setup, through a built-in plugin, from v2.1.277. By default it reads your `AGENTS.md` only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. Your `~/.claude/CLAUDE.md`, the managed file and `.claude/rules/` don't count, so they keep loading alongside it. When it does load one, you see a line such as `no CLAUDE.md found; AGENTS.md loaded`.

You can change that in `/config` under **Project instructions**:

| Value | What Claude reads |
|---|---|
| `claude-md-or-agents-md` (default) | `CLAUDE.md` files, or `AGENTS.md` when there is no `CLAUDE.md` or `CLAUDE.local.md` |
| `claude-md-and-agents-md` | Both, each directory's `CLAUDE.md` first and its `AGENTS.md` after |
| `claude-md` | `CLAUDE.md` only |
| `managed-only` | Only the organization's managed file and auto memory at launch |

One trap: adding a `CLAUDE.local.md` for your own notes in a repository that relies on `AGENTS.md` stops Claude from reading `AGENTS.md`, unless you switch to `claude-md-and-agents-md`.

## Codex: AGENTS.md, with overrides

OpenAI's Codex docs describe an instruction chain built once per run:

1. **Global:** in `~/.codex` (or wherever `CODEX_HOME` points), Codex reads `AGENTS.override.md` if it exists, otherwise `AGENTS.md`.
2. **Project:** from the project root (usually the Git root) down to your current directory, Codex checks each directory for `AGENTS.override.md`, then `AGENTS.md`, then any fallback names you set. It takes at most one file per directory.
3. **Merge:** files are joined root first, so the ones closer to your current directory override earlier guidance.

Empty files are skipped, and Codex stops adding files at 32 KiB combined unless you raise `project_doc_max_bytes`. To make Codex read a file with another name, list it in `project_doc_fallback_filenames` in `~/.codex/config.toml`. Codex code review on GitHub also reads a `## Code Review Rules` section from the `AGENTS.md` closest to the code.

## Cursor: rules, plus AGENTS.md

Cursor's rules docs name four kinds of instructions: Project Rules in `.cursor/rules`, User Rules in Customize, Team Rules from the dashboard (Team and Enterprise plans), and `AGENTS.md`.

- **Project Rules** are `.mdc` files with frontmatter. `alwaysApply: true` puts a rule in every chat; `globs` attaches it when matching files are in context; a `description` alone lets the agent decide; none of them means you @-mention it. A plain `.md` file in `.cursor/rules` is ignored.
- **AGENTS.md** is the plain Markdown option, read in the project root and in any subdirectory. Nested files combine with their parents, and the more specific one takes precedence.
- **Precedence:** Team Rules, then Project Rules, then User Rules. All of them are merged; earlier sources win when guidance conflicts.
- **References aren't imports.** A file mention like `@service-template.ts` in a rule tells the agent where to look. Cursor doesn't paste the file into the prompt, so anything that must always be in context belongs in the rule body.

## Gemini CLI: GEMINI.md, or AGENTS.md if you say so

Gemini CLI reads `~/.gemini/GEMINI.md`, then `GEMINI.md` files in your workspace directories and their parents, then files in directories a tool touches. It concatenates all of them and sends them with every prompt. `@file.md` imports work with relative and absolute paths. `/memory show` prints the combined context, and `/memory reload` re-scans.

To have it read your `AGENTS.md`, set the file name in `.gemini/settings.json`:

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

## GitHub Copilot: three kinds of instructions, and it accepts CLAUDE.md

GitHub's docs list repository-wide instructions in `.github/copilot-instructions.md`, path-specific files named `NAME.instructions.md` under `.github/instructions` (with an `applyTo` glob), and agent instructions in `AGENTS.md` files anywhere in the repository, where the nearest one takes precedence. Instead of `AGENTS.md`, you can use a single `CLAUDE.md` or `GEMINI.md` in the repository root. Personal instructions come first, then repository, then organization, and Copilot receives all of them.

## The setup I'd use: one AGENTS.md, one CLAUDE.md that imports it

Write your instructions once, in `AGENTS.md`, and point each tool at it. Every step below comes from the vendor docs above.

### Step 1: Put everything shared in AGENTS.md

At the repository root:

```markdown
# AGENTS.md

## Commands
- Install: pnpm install
- Test: pnpm test (run before every commit)

## Rules
- API handlers live in src/api/handlers/
- Never edit generated files in dist/
```

Concrete, checkable lines work best. Anthropic's example: "Use 2-space indentation" instead of "Format code properly". For a monorepo, add an `AGENTS.md` inside each package; Codex, Cursor and Copilot all pick up nested files, and the closest one takes precedence.

### Step 2: Add a CLAUDE.md that imports it

```markdown
@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.
```

Claude Code would read a lone `AGENTS.md` on its own, so why add this file? The import keeps working in three cases where direct reading doesn't: sessions on Claude Code before v2.1.277, a teammate who adds a `CLAUDE.local.md`, and a **Project instructions** setting of `claude-md`. Anthropic's docs say the import never makes Claude read `AGENTS.md` twice, whichever setting you use. Put Claude-only lines below the import.

Skip the alternative of a `CLAUDE.md` that says "read AGENTS.md" in words: Claude sees the file only if it decides to open it. A symlink (`ln -s AGENTS.md CLAUDE.md`) also works, but it breaks for anyone who clones on Windows without symlink support, and Claude's edit tools refuse to write through it and edit `AGENTS.md` instead.

### Step 3: Point Gemini CLI at AGENTS.md

Add `"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}` to `.gemini/settings.json`, as shown above. Codex, Cursor and Copilot need nothing.

### Step 4: Keep personal preferences out of the shared file

Use `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex, User Rules for Cursor and `~/.gemini/GEMINI.md` for Gemini CLI. If you keep a `CLAUDE.local.md`, set Claude Code's **Project instructions** to `claude-md-and-agents-md` or keep the import from step 2.

### Step 5: Check what each tool loaded

- **Claude Code:** run `/memory` or `/context` and look for your files under Memory files.
- **Codex:** `codex --ask-for-approval never "Summarize the current instructions."` from the repository root.
- **Gemini CLI:** `/memory show`.
- **Copilot Chat on GitHub:** expand the references on a response and look for the instructions file.

## Where repository files stop

These files live in one repository on one machine. That is right for build commands and code style. It falls short for the context that isn't about code: what you sell, who it's for, how you sound, what you decided last week. Claude in the browser, ChatGPT and cloud agents that never clone the repository don't see a line of it, and a second repository means a second copy to keep in sync.

That is the gap LotsNotes fills for me. LotsNotes keeps your business context as notes that every agent reads over MCP or the REST API, and it uses the same convention: a note titled `AGENTS.md` holds the instructions agents read first.

- **One shared AGENTS.md at workspace level.** Workspace notes come back with every folder's notes, so a workspace `AGENTS.md` reaches every agent, whatever it's working on.
- **Folder-level notes per product, client or agent.** A folder can hold its own `AGENTS.md`, plus the notes for that work. Agents find notes by title and read only the ones they need.
- **Any agent, same notes.** Claude, ChatGPT, Codex and Cursor connect to `https://api.lotsnotes.com/mcp` and sign in with OAuth; cloud agents and scripts use the REST API with a key. Setup for each agent is on the [connect page](https://lotsnotes.com/mcp).

This is how LotsTech runs. My agents' shared rules are one workspace `AGENTS.md` note, and each agent has a folder with its own `AGENTS.md`, plan, handoff, ledger and memory. For this article I asked the LotsNotes MCP for the blog agent's context with one `find_context` call (workspace plus folder). It returned the workspace `AGENTS.md` as a workspace note and the blog folder's own `AGENTS.md`, handoff, ledger, memory and plan among the folder notes, each with its lotsnotes.com link.

In each repository, the local `AGENTS.md` is a short pointer: it names the LotsNotes workspace and folder and tells the agent to read the `AGENTS.md` notes there first, then its handoff and memory. Coding agents still load that local file on their own, as above; the business rules live in one place, and editing them on lotsnotes.com updates every agent at once.

LotsNotes is free for one person: 1 workspace, 3 folders, unlimited notes and checklists, MCP and REST access. LotsNotes Pro is one payment of $99 for unlimited workspaces, folders and team members with roles, and it's included while you have a Pro or Business plan of LotsSocial, LotsBlog, LotsTeam or LotsCRM. Details on the [pricing page](https://lotsnotes.com/pricing). If you're comparing places to keep business context for agents, I covered ten tools in [the best knowledge base and notes tools with MCP support](https://lotsnotes.com/blog/best-knowledge-base-tools-with-mcp-support).

## FAQ

### Does Claude Code read AGENTS.md?

Yes, from v2.1.277. By default it reads `AGENTS.md` only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. Set **Project instructions** to `claude-md-and-agents-md` in `/config` to read both, or import it with `@AGENTS.md` in your `CLAUDE.md`.

### If a repository has both AGENTS.md and CLAUDE.md, which one does Claude Code use?

With the default setting, only your `CLAUDE.md` files. If that `CLAUDE.md` contains `@AGENTS.md`, Claude reads both, and Anthropic's docs say the import never loads `AGENTS.md` twice.

### Can CLAUDE.md import AGENTS.md?

Yes. Put `@AGENTS.md` in a `CLAUDE.md` next to it. Imports can be relative or absolute, nest up to four hops, and load at launch.

### Where does Codex look for AGENTS.md?

First in `~/.codex` (or `CODEX_HOME`) for `AGENTS.override.md` or `AGENTS.md`, then in every directory from the project root down to your current directory, one file per directory. Closer files override earlier ones, and the combined limit is 32 KiB by default.

### Does Cursor read AGENTS.md?

Yes, in the project root and in subdirectories. Nested files combine with their parents, and the more specific file takes precedence. Project Rules in `.cursor/rules` must be `.mdc` files.

### Does Gemini CLI read AGENTS.md?

Not by default: it reads `GEMINI.md`. Set `context.fileName` in `.gemini/settings.json` to `["AGENTS.md", "GEMINI.md"]` and it reads both.

### Does GitHub Copilot read CLAUDE.md?

Yes. GitHub's docs say you can use a single `CLAUDE.md` or `GEMINI.md` in the repository root instead of `AGENTS.md` files, alongside `.github/copilot-instructions.md`.

## Sources

All opened on 13 October 2026:

- Anthropic, [How Claude remembers your project](https://code.claude.com/docs/en/memory)
- OpenAI, [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- Cursor, [Rules](https://cursor.com/docs/rules)
- Google, [Provide context with GEMINI.md files](https://geminicli.com/docs/cli/gemini-md/)
- GitHub, [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)
- [AGENTS.md](https://agents.md/), the open format, now stewarded by the Agentic AI Foundation under the Linux Foundation

## Write it once

Keep code rules in `AGENTS.md`, import it from `CLAUDE.md`, and put the business context every agent needs where every agent can read it. [Connect your agent to LotsNotes](https://lotsnotes.com/mcp) and start with one `AGENTS.md` note.