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

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.

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:

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:

{
  "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:

# 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

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

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

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
• OpenAI, Custom instructions with AGENTS.md
• Cursor, Rules
• Google, Provide context with GEMINI.md files
• GitHub, Adding repository custom instructions for GitHub Copilot
• 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 and start with one AGENTS.md note.