CLAUDE.md vs AGENTS.md: which file each tool reads and how to keep one source

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is Claude Code's own instructions file; AGENTS.md is an open format that many coding agents read, including Codex, Cursor, GitHub Copilot and, under certain conditions, Claude Code. Both are plain Markdown that tells an agent your build commands, conventions and project layout. The difference is who reads them.

That makes the choice simple for most teams. Use only Claude Code? A CLAUDE.md is fine. Use several agents? Keep the shared content in AGENTS.md once and point Claude Code at it. This guide covers which tool reads which file, exactly how Claude Code decides, and three ways to keep a single source. For the file formats themselves, see the CLAUDE.md guide and the AGENTS.md guide.

Which tools read CLAUDE.md and which read AGENTS.md?

Here is what each tool's official docs say as of 24 October 2026:

Sources: Claude Code's memory docs, OpenAI's Codex AGENTS.md docs, Cursor's rules docs, GitHub's repository instructions docs, Gemini CLI's context file docs and Google's Antigravity CLI migration guide.

The pattern is clear: AGENTS.md is the file most tools agree on, and CLAUDE.md is mostly read by Claude Code.

How does Claude Code handle AGENTS.md?

Claude Code's docs say it "can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting." By default it follows this table:

A few details matter in practice:

• What counts as having a CLAUDE.md: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. Your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and .claude/rules/ files don't count, and keep loading alongside AGENTS.md.
• What loads: every AGENTS.md and .claude/AGENTS.md from your working directory up, at session start. A subdirectory's AGENTS.md loads when Claude opens a file there and that folder has no CLAUDE.md of its own.
• How you can tell: an interactive session shows a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
• What it ignores: AGENTS.local.md, AGENTS.override.md and anything under a .agents/ directory.

One trap: because CLAUDE.local.md counts, adding one for your own notes stops Claude Code from reading the team's AGENTS.md. The fix is the setting in the next section.

Direct AGENTS.md reading needs Claude Code v2.1.277 or later. It is also off if you disabled the built-in plugin that reads it, and in some cases in your first session after upgrading from v2.1.276 or earlier.

How do you change which files Claude Code loads?

Type /config in a session and set Project instructions to one of these values:

• claude-md-or-agents-md: the default. CLAUDE.md files, or AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md.
• claude-md-and-agents-md: both, with each directory's CLAUDE.md files first and its AGENTS.md after them.
• claude-md: CLAUDE.md files only.
• managed-only: only your organization's managed CLAUDE.md and auto memory at launch.

You can set the same value in ~/.claude/settings.json. Claude Code ignores this entry in project and local settings files:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

The docs note that before v2.1.285 the plugin ID was agents-md@builtin, and v2.1.285 and later read either ID.

How do you keep one source of instructions?

Pick one of three setups. Each leaves AGENTS.md as the file every tool shares.

1. AGENTS.md only. Delete or never create a CLAUDE.md. Claude Code reads AGENTS.md directly, and so do Codex, Cursor and Copilot. This is the simplest option when you need nothing Claude-specific.

2. A short CLAUDE.md that imports AGENTS.md. Put @AGENTS.md at the top and add Claude-only notes below. Claude reads the imported file first, then the rest:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

This also covers sessions where Claude Code can't read AGENTS.md directly, such as older versions. The docs say keeping the import "never makes Claude read AGENTS.md twice."

3. A symlink. If you need no Claude-specific content, link the files:

ln -s AGENTS.md CLAUDE.md

Check two constraints first. Claude's Edit and Write tools refuse to write through a symlink and edit AGENTS.md instead. And on Windows, creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled. If anyone on the team uses Windows, use the import.

With setups 2 and 3, run /context in a new session and confirm CLAUDE.md appears under Memory files. With setup 1, run /memory and look for the AGENTS.md path in the list.

For other tools, the same idea applies in reverse. Gemini CLI can load AGENTS.md if you list it in context.fileName, and Codex can load other names through project_doc_fallback_filenames.

Where does AGENTS.md behave differently from CLAUDE.md in Claude Code?

When Claude Code reads AGENTS.md through the Project instructions setting, three things differ from a CLAUDE.md:

If you rely on any of these, use setup 2. Hooks fire as usual for an AGENTS.md that a CLAUDE.md imports or symlinks to.

What should you do with an old AGENTS.md workaround?

Many repos added a workaround before Claude Code read AGENTS.md on its own. The docs give a verdict for each:

• A CLAUDE.md containing @AGENTS.md: you can leave it. Remove the CLAUDE.md if it holds nothing else.
• A CLAUDE.md that says in words "read AGENTS.md": Claude only sees AGENTS.md if it decides to open it. Delete the CLAUDE.md or replace the sentence with @AGENTS.md.
• A symlink: nothing to do. Claude reads the content once.
• A SessionStart hook that prints AGENTS.md: remove it, or Claude gets a second copy.

Which should you pick?

Use AGENTS.md as the main file when:

• Your team uses more than one coding agent, such as Claude Code with Codex, Cursor or Copilot.
• You want one place to update build commands and conventions.
• The repo is open source and contributors bring their own tools.

Use CLAUDE.md as the main file when:

• Claude Code is the only agent anyone uses on the repo.
• You need InstructionsLoaded hooks or --add-dir loading to work on the file.
• You want Claude-specific instructions, like plan mode rules, without other agents reading them.

The combined setup, a CLAUDE.md that starts with @AGENTS.md, works for both cases and is the safest default for mixed teams. Whichever file you pick, Anthropic's advice holds: "target under 200 lines per CLAUDE.md file," and move multi-step procedures into skills or path-scoped rules. The Claude Code memory guide covers rules and auto memory.

Keep the long instructions somewhere you own

Instruction files work best when they stay short, which means the detailed checklists and workflows need another home. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Claude Code or Codex with one npx skills add command. To turn a long section of your CLAUDE.md into a skill, paste it into the free SKILL.md generator.