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

What each file is

Both are plain Markdown that an agent loads into its context at the start of a session. You write build and test commands, code style, project layout and rules such as "never edit generated files". They are instructions, not enforced settings: the agent treats them as guidance.

• CLAUDE.md is specific to Claude Code. It can live at the project root (./CLAUDE.md or ./.claude/CLAUDE.md), in ~/.claude/CLAUDE.md for all your projects, and in subfolders. A CLAUDE.local.md holds private notes for one project.
• AGENTS.md is an open format described on agents.md, a README for agents. Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Zed and many others read it. In a monorepo, an AGENTS.md in a subfolder applies to that part, and the closest file wins.

The content is the same kind of thing. What differs is which tool picks the file up.

What Claude Code does with AGENTS.md

Claude Code's documentation describes three cases, for version 2.1.277 or later:

• Only an AGENTS.md in your project, no CLAUDE.md: Claude Code reads the AGENTS.md.
• Both files in your project: Claude Code reads the CLAUDE.md files only.
• A CLAUDE.md that imports AGENTS.md with @AGENTS.md: Claude reads the CLAUDE.md with AGENTS.md included.

That second case is the one that surprises people. If you add a CLAUDE.md, even a tiny one, to a repository that has an AGENTS.md, Claude stops reading the AGENTS.md unless the CLAUDE.md imports it. The same goes for a CLAUDE.local.md. Older Claude Code versions read CLAUDE.md only, which is why the import is still the safe choice. The docs also describe a Project instructions setting in /config to have Claude read both files together.

Keeping one set of instructions

Pick one file as the source of truth. Two ways are documented:

1. Import AGENTS.md from CLAUDE.md

   Create a CLAUDE.md next to AGENTS.md whose first line is @AGENTS.md, then add Claude-only instructions below. Imports use the @path syntax, relative paths resolve from the file that contains them, and imported files can import others up to four levels deep.

2. Symlink CLAUDE.md to AGENTS.md

   Run ln -s AGENTS.md CLAUDE.md if you have nothing Claude-specific to add. The docs warn that Claude's edit tools will not write through a symlink, and that on Windows a committed symlink can check out as a one-line text file, so the import is the safer choice for a shared repository.

Avoid a third approach: a CLAUDE.md that says "read AGENTS.md" in words. Claude sees the file only if it decides to open it, while an import loads it every time.

A shared AGENTS.md

Put what any agent needs in AGENTS.md:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Keep it short and specific. The Claude Code docs suggest staying under about 200 lines per CLAUDE.md, because longer files cost context and are followed less reliably.

Common mistakes

• Two files that drift apart. One copy gets updated, the other does not. Use the import.
• Adding a CLAUDE.md and losing the AGENTS.md. See above: import it.
• Putting secrets in either file. They are committed and loaded into every session.
• Vague rules. "Write clean code" does nothing. "Run npm test before saying you are done" does.
• Contradicting rules in a parent folder's file and a subfolder's file.

Reading and reviewing these files

Both are ordinary Markdown, so DotMD opens CLAUDE.md and AGENTS.md like any .md file, with an outline and a history of every change, and shows what an agent changed in them. Reading is free. See also Claude Code and Codex with DotMD.

Questions about CLAUDE.md and AGENTS.md

More questions