AGENTS.md vs CLAUDE.md. Claude Code reads AGENTS.md on its own until you add a CLAUDE.md
How AGENTS.md and CLAUDE.md differ, when Claude Code reads AGENTS.md with no help, and how to keep one source of rules for every coding agent.
Part of the guideClaude Code, the complete guide. From installation to your own skills and plugins
In this article
In short
From version 2.1.277 Claude Code reads AGENTS.md on its own, but only when the project has no CLAUDE.md or CLAUDE.local.md. When you need both files, AGENTS.md stays the single source and CLAUDE.md starts with the line @AGENTS.md. On Windows use the import instead of a symlink.
The repository has two files with almost the same content. AGENTS.md for Codex and Cursor, CLAUDE.md for Claude Code. Someone changed the test command in one of them, and the other still has the old one. From then on two agents work by two different sets of rules and nobody notices. You can avoid that, because AGENTS.md and CLAUDE.md can be kept as one source.
This article is part of our Claude Code guide. It is based on Anthropic's documentation on Claude Code memory, as of 10 November 2026.
How AGENTS.md and CLAUDE.md differ
Both are plain Markdown files with instructions for an agent that works on code. The difference is who reads them and where they can live.
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Format | open, described on agents.md | Claude Code file |
| Read by | Codex, Cursor, Copilot and others | Claude Code |
| In Claude Code | read when there is no CLAUDE.md | always read |
| Personal files | in Codex ~/.codex/AGENTS.md | ~/.claude/CLAUDE.md and CLAUDE.local.md |
CLAUDE.md also has things other tools do not know about. For example a Compact Instructions section that says what to keep when the conversation is summarised, or rules in .claude/rules/ that load only when Claude works on matching files. What AGENTS.md itself is and how Codex reads it is covered in What is AGENTS.md.
One source of rules for Claude and Codex
Without a CLAUDE.md, newer versions of Claude Code read AGENTS.md on their own.
When Claude Code reads AGENTS.md
From version 2.1.277 Claude Code reads AGENTS.md with no import and no extra setting. Anthropic's documentation describes it in a table.
| The repository has | Claude reads |
|---|---|
| AGENTS.md, no CLAUDE.md or CLAUDE.local.md | AGENTS.md |
| AGENTS.md and a CLAUDE.md or CLAUDE.local.md | CLAUDE.md only |
a CLAUDE.md that imports @AGENTS.md | CLAUDE.md with AGENTS.md included |
What counts is any CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder where you start Claude Code and in every folder above it. Your personal ~/.claude/CLAUDE.md, your company's managed file and the rules in .claude/rules/ do not count, so they keep loading alongside AGENTS.md. When Claude loads AGENTS.md at the start, the conversation shows a line beginning with no CLAUDE.md found and the path to the file.
There is a catch. If someone adds a CLAUDE.local.md for private notes, Claude stops reading AGENTS.md for that person. Claude Code also never reads AGENTS.local.md, AGENTS.override.md or anything in an .agents/ folder. Codex knows the override file, but it will not reach Claude.
You change the default in the settings. Type /config in a session and set the Project instructions field.
| Value | What Claude reads |
|---|---|
claude-md-or-agents-md | CLAUDE.md, and AGENTS.md only without CLAUDE.md, the default |
claude-md-and-agents-md | both, CLAUDE.md first in each folder |
claude-md | CLAUDE.md only |
managed-only | only the managed company file and auto memory |
Sometimes AGENTS.md does not load at all. That happens on versions older than 2.1.277, after you turn off the built-in plugin that reads it, and in some cases in the first session after an upgrade. In those sessions the Project instructions field simply is not in /config.
One source for both with an @AGENTS.md import
The safest setup looks like this. All shared rules live in AGENTS.md. Next to it sits a short CLAUDE.md that starts with an import and below it holds only what concerns Claude Code.
@AGENTS.md
## Claude Code
Start changes under `src/billing/` in plan mode.Claude reads the imported file first, then the rest. According to the documentation, the import never makes AGENTS.md land in context twice, whatever the Project instructions setting is. So this setup also works in sessions that cannot read AGENTS.md directly.
Moving from two files to one takes a few minutes.
- Move the shared rules from CLAUDE.md into AGENTS.md. Test commands, code style, pull request rules.
- Keep
@AGENTS.mdas the first line of CLAUDE.md, with only Claude Code specific rules below it. - Start a new session and type
/context all. - Check that CLAUDE.md is listed under Memory files.
If nothing but the import is left in CLAUDE.md, you can delete it and let Claude read AGENTS.md directly. The documentation suggests keeping it, though, if some of your sessions cannot load AGENTS.md on their own. Ready file templates are in CLAUDE.md examples.
A symlink instead of an import
If you have no rules just for Claude, a symlink is enough.
ln -s AGENTS.md CLAUDE.mdOn success the command prints nothing. The documentation names two limits. Claude reads CLAUDE.md through the link, but its editing tools refuse to write through it and point Claude to AGENTS.md instead.
The second one is about Windows. Creating a symlink there needs administrator rights or Developer Mode. Without core.symlinks turned on, Git checks out a committed symlink as a plain text file with one line. Claude then gets that one line instead of your rules. If anyone on the project works on Windows, use the import.
Old workarounds to clean up
If you set Claude Code up to read AGENTS.md before version 2.1.277, the project may still have one of the workarounds. A CLAUDE.md that tells Claude in words to read AGENTS.md leaves the decision to the model, because Claude sees the file only if it chooses to open it. Replace that sentence with the import or delete the CLAUDE.md. A SessionStart hook that printed AGENTS.md into the conversation should go, because now it adds a second copy.
The other direction is simpler. Codex does not read CLAUDE.md by default. You can add other file names to its project_doc_fallback_filenames list, but with one source in AGENTS.md there is no need. How to write such instructions in the first place is covered in our CLAUDE.md article.
If your repository has two files today, start by comparing them and moving the shared part into AGENTS.md. Then run /context all to check that Claude sees what it should.
If you want to know where AI can take work off your company, ask for our free AI audit. We look at your tasks and tell you where to start.
What would you like to change in your business?
Leave your number. We will talk about your process and see whether we can help. The first call is free.
The service this text is about
Automation and AI / OCRAutomation of document re-typing, OCR and checking rules, and your data stays with you.