CLAUDE.md vs AGENTS.md: which file each coding agent reads

CLAUDE.md is Claude Code’s own instruction file; AGENTS.md is the shared format that Codex, GitHub Copilot, Cursor and others read. Since v2.1.277, Claude Code also reads AGENTS.md, but by default only in directories where no CLAUDE.md or CLAUDE.local.md exists. If you use several agents, keep the rules in AGENTS.md and import it from CLAUDE.md:

@AGENTS.md

## Claude Code only
- Use plan mode for changes touching more than three files.

Applies to: Claude Code 2.1.296 (changelog), Codex, GitHub Copilot, Cursor and Gemini CLI docs as of October 12, 2026. Last checked: October 12, 2026.

On this page

Which file does each agent read?

Sources for each row are in the sections below.

Does Claude Code read AGENTS.md?

Yes, with a condition. Anthropic’s memory docs say Claude Code loads AGENTS.md in a directory when there is no CLAUDE.md or CLAUDE.local.md on that path. A repository that already has a CLAUDE.md keeps working exactly as before; the AGENTS.md next to it is ignored unless you import it.

You can change that behaviour in /config under “Project instructions”. The values the docs list:

The underlying setting is pluginConfigs."cc-plugin-agents-md@builtin".options.instructionFiles (named agents-md@builtin before v2.1.285). It is read only from user settings, --settings or managed settings, so a repository cannot switch it for you.

Claude Code does not read AGENTS.local.md, AGENTS.override.md or an .agents/ folder; those are other tools’ conventions.

How do I use one file for Claude Code and Codex?

Two options from the Claude Code docs:

1. Import. Put @AGENTS.md on its own line in CLAUDE.md, then add anything Claude-specific below it. Claude Code expands the import when it loads the file, and the other agents keep reading AGENTS.md directly.
2. Symlink. ln -s AGENTS.md CLAUDE.md makes both names point to one file. On Windows, symlinks need Developer Mode or admin rights and git’s core.symlinks setting, so the import is the safer choice for mixed teams.

If you already have rules for another tool, /init in Claude Code reads them when it drafts a CLAUDE.md, and /import (v2.1.213 or later) pulls in rules from other agents’ files. For how to write the rules themselves, see our CLAUDE.md best practices.

What does Codex read?

The Codex AGENTS.md guide describes a chain:

• Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md.
• Project: from the repository root down to the working directory, in each folder Codex takes AGENTS.override.md, then AGENTS.md, then any name listed in project_doc_fallback_filenames.
• Size: combined instructions stop at project_doc_max_bytes, 32 KiB by default.

So Codex ignores CLAUDE.md unless you add it as a fallback name in ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

More on Codex itself in what is Codex.

What do Copilot, Cursor and Gemini CLI read?

GitHub Copilot. GitHub’s repository instructions page lists .github/copilot-instructions.md, path-specific .instructions.md files, and agent instructions in AGENTS.md files, where the nearest AGENTS.md in the tree takes precedence. As an alternative, it accepts a single CLAUDE.md or GEMINI.md in the repository root. Our Copilot custom instructions guide covers the setup.

Cursor. The Cursor rules docs support AGENTS.md in the project root and in subdirectories, as a plain-Markdown alternative to .cursor/rules. The page does not mention CLAUDE.md. See Cursor rules, .mdc and AGENTS.md.

Gemini CLI. It loads GEMINI.md by default. The GEMINI.md docs show context.fileName in settings.json, which accepts a list of names:

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

Which should I use?

• Only Claude Code in the team: CLAUDE.md. You get CLAUDE.local.md, .claude/rules/ and imports without any extra setting.
• Claude Code plus Codex, Copilot or Cursor: AGENTS.md as the shared source, and a short CLAUDE.md that imports it and adds Claude-only notes.
• A repo with both files already: decide which one holds the shared rules. With the default setting Claude Code reads only CLAUDE.md there, so rules that exist only in AGENTS.md are invisible to it until you import the file or switch to claude-md-and-agents-md.