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
  1. How AGENTS.md and CLAUDE.md differ
  2. When Claude Code reads AGENTS.md
  3. One source for both with an @AGENTS.md import
  4. A symlink instead of an import
  5. Old workarounds to clean up

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.mdCLAUDE.md
Formatopen, described on agents.mdClaude Code file
Read byCodex, Cursor, Copilot and othersClaude Code
In Claude Coderead when there is no CLAUDE.mdalways read
Personal filesin 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.

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 hasClaude reads
AGENTS.md, no CLAUDE.md or CLAUDE.local.mdAGENTS.md
AGENTS.md and a CLAUDE.md or CLAUDE.local.mdCLAUDE.md only
a CLAUDE.md that imports @AGENTS.mdCLAUDE.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.

ValueWhat Claude reads
claude-md-or-agents-mdCLAUDE.md, and AGENTS.md only without CLAUDE.md, the default
claude-md-and-agents-mdboth, CLAUDE.md first in each folder
claude-mdCLAUDE.md only
managed-onlyonly 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.

CLAUDE.md
@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.

  1. Move the shared rules from CLAUDE.md into AGENTS.md. Test commands, code style, pull request rules.
  2. Keep @AGENTS.md as the first line of CLAUDE.md, with only Claude Code specific rules below it.
  3. Start a new session and type /context all.
  4. 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.

If you have no rules just for Claude, a symlink is enough.

bash
ln -s AGENTS.md CLAUDE.md

On 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.

When is the best time to call?
Controller: Oleksandr Bondarenko (BondSoft)Privacy PolicyTerms of Service
Legal details

The data controller is Oleksandr Bondarenko, trading as Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, Poland, NIP 5833576264, e-mail: office@bondsoft.pl.

We process your data solely to contact you about your enquiry and to present an offer — on the basis of your consent (Art. 6(1)(a) GDPR and Art. 398 of the Polish Electronic Communications Law) and our legitimate interest in handling the enquiry (Art. 6(1)(f) GDPR).

Providing the data is voluntary but necessary for us to reply. You may withdraw your consent at any time by writing to office@bondsoft.pl — this does not affect the lawfulness of processing before the withdrawal.

You have the right to access your data, rectify it, erase it, restrict its processing, transfer it, and lodge a complaint with the President of the Polish Personal Data Protection Office.

Full information: Privacy Policy.

Send us an email

The service this text is about

Automation and AI / OCR

Automation of document re-typing, OCR and checking rules, and your data stays with you.