Claude Code reads AGENTS.md only when no CLAUDE.md exists; import AGENTS.md from CLAUDE.md to use both

Details

AGENTS.md is a plain Markdown file of instructions for coding agents. CLAUDE.md is the same idea, but only Claude Code reads it. Because of that, a long-standing feature request asked Claude Code to support AGENTS.md (issue 6235, opened 2025-08-21, now closed).

What Claude Code reads by default

Your repository has	Claude Code reads
AGENTS.md, no CLAUDE.md or CLAUDE.local.md in the working directory or above	AGENTS.md
AGENTS.md and a CLAUDE.md or CLAUDE.local.md	The CLAUDE.md files only
A CLAUDE.md that imports AGENTS.md	CLAUDE.md, with AGENTS.md included through the import

A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above counts for this check. Your ~/.claude/CLAUDE.md, an organization-managed CLAUDE.md and files in .claude/rules/ do not count and keep loading next to AGENTS.md.

Which tool reads which file

Tool	Reads AGENTS.md	Reads CLAUDE.md	Source
Claude Code	Yes, v2.1.277 or later, when no CLAUDE.md exists	Yes	Claude Code docs
Cursor	Yes, listed as a rule type	Not stated on the rules page	Cursor docs
GitHub Copilot	Yes	Yes, also GEMINI.md	GitHub docs

In a monorepo, agents read the nearest AGENTS.md in the directory tree, so the closest file takes precedence (agents.md, Copilot docs). The agents.md site says more than 60,000 open-source projects use the format and lists more than 20 supporting tools.

Use one source file for every tool

1. Write your instructions in AGENTS.md.
2. Create CLAUDE.md next to it with the import on its own line.
3. Add Claude-only notes below the import if you need any.
4. Start Claude Code and run /context. Confirm CLAUDE.md is listed under Memory files.

@AGENTS.md

## Claude Code

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

The docs say Claude Code skips an AGENTS.md it has already loaded, so the import never loads the file twice.

Import or symlink

ln -s AGENTS.md CLAUDE.md also works. The docs list two limits. Claude's Edit and Write tools refuse to write through a symlink and point to the target instead. On Windows, creating a symlink needs Administrator rights or Developer Mode, and Git can check a committed symlink out as a one-line text file. If anyone on the team uses Windows, use the import.

Force both files to load

Open /config in Claude Code and set Project instructions to claude-md-and-agents-md. The default is claude-md-or-agents-md. With the "and" value, CLAUDE.md loads first and AGENTS.md after it.

Common mistakes

• Adding a CLAUDE.local.md for personal notes. It counts as a CLAUDE.md, so Claude Code stops reading AGENTS.md unless you set claude-md-and-agents-md.
• Writing "read AGENTS.md" in prose inside CLAUDE.md. Claude then reads the file only if it decides to open it. Use @AGENTS.md.
• Running a version older than v2.1.277, which cannot read AGENTS.md directly. Import it instead.
• Expecting AGENTS.local.md or files under .agents/ to load. The docs say they are not read.

To check what loaded, run /memory and look for the AGENTS.md path. What to put in the file is covered in how-to-write-agents-md.