Skip to content
Mastering Claude

Home / A structured installation

A structured installation8 minApplication

AGENTS.md: when Claude Code reads it, and how to check

With the default setting, Claude Code reads AGENTS.md only when no CLAUDE.md comes before it in the working folder or above, and what was actually loaded is checked at session start, not in the /config panel.

A repository prepared for other coding agents often carries an AGENTS.md file at its root: project conventions, the exact test command, files not to touch. Since Claude Code version 2.1.277, released on 18 September 2026, Claude Code reads this file as project instructions, with no import or setting, on one condition: no CLAUDE.md file must take its place.

The exact condition

With the default setting, three files count for this check: CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md, in the working folder or in one of the folders above it. If one of them exists, Claude reads the CLAUDE.md files and leaves AGENTS.md aside. The personal file ~/.claude/CLAUDE.md, the CLAUDE.md managed by the organisation and the rules in .claude/rules/ do not count: they load alongside AGENTS.md. The documentation flags a trap: creating a CLAUDE.local.md to note your personal preferences is enough to remove AGENTS.md from the session.

When the condition is met, Claude reads at startup each AGENTS.md and .claude/AGENTS.md in the working folder and the folders above it. It then reads the AGENTS.md of a subfolder when it opens a file there and that subfolder carries none of the three CLAUDE.md files. The @path imports written in an AGENTS.md are expanded as in a CLAUDE.md.

A setting is not a witness

The Project instructions entry in the /config panel chooses what loads. The default value, claude-md-or-agents-md, applies the condition above; claude-md-and-agents-md reads both families of files, the CLAUDE.md files of each folder first; claude-md ignores AGENTS.md; managed-only loads at startup the CLAUDE.md managed by your organisation and the automatic memory, leaving out your project, local and personal CLAUDE.md files, your .claude/rules/ rules and any AGENTS.md, but a subfolder's CLAUDE.md and rules still load when Claude reads a file there. This panel says what is requested, not what was read. The proof is read elsewhere: in an interactive session, the documentation gives the example of a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md displayed in the conversation, and since version 2.1.280, the /memory command also lists the path of the file read.

Two special cases are worth knowing. Before version 2.1.281 of 23 September 2026, sessions on Amazon Bedrock, Google Vertex AI or Microsoft Foundry, behind a gateway or with telemetry turned off, only read CLAUDE.md files; this version aligned them with the others. And in some cases, the first session after an update from version 2.1.276 or earlier does not yet read AGENTS.md: reading starts with the following session.

The demonstration

Create the folder outside any project, so that no CLAUDE.md in a parent folder counts in the check.

mkdir test-agents-md && cd test-agents-md
printf "# Project rules\nAlways answer in a single sentence.\n" > AGENTS.md
cat AGENTS.md
# Project rules
Always answer in a single sentence.

Then launch claude in this folder, read the line displayed at startup, then type /memory. The file loads like the CLAUDE.md described in the lesson on project memory, and its instructions age in the same way, as the next lesson shows.

Figure 1

How Claude Code decides to read AGENTS.md, with the default setting

01
Look for a CLAUDE.md
Claude Code looks for CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working folder and in each folder above it.
02
If it finds one
It reads the CLAUDE.md files and leaves AGENTS.md aside, unless Project instructions is set to claude-md-and-agents-md.
03
Check
The line displayed at startup and the /memory list give the path of the file actually read.
If it finds none01It reads each AGENTS.md and .claude/AGENTS.md in the working folder and the folders above it.
The sequence starts from the condition checked when the session opens and ends on where the result is read.
Calibrate it yourself

A developer opens an interactive Claude Code session, version 2.1.283, in a repository that carries an AGENTS.md file at its root. At startup, the conversation displays the line no CLAUDE.md found; AGENTS.md loaded, followed by the path of that file. She then types /memory and reads that same path in the list.

Write in one sentence what this situation establishes, and in one sentence what it does not establish.

What to remember
  • A CLAUDE.local.md counts as much as a CLAUDE.md in the check, whereas the personal file ~/.claude/CLAUDE.md does not count.
  • The claude-md-and-agents-md value of Project instructions makes both families of files load in the same session.
  • What was loaded is checked by the startup line and, since version 2.1.280, by the /memory list, the /config panel showing only the setting requested.
  • A session on a cloud provider or without telemetry reads AGENTS.md provided Claude Code is up to date, an older version sticks to CLAUDE.md files.
  • At startup, the managed-only value loads the CLAUDE.md managed by the organisation and the automatic memory, but a subfolder's CLAUDE.md and rules still load when Claude reads a file there.
Do this now

Create a folder outside any project, put in it an AGENTS.md with one short rule as in the demonstration, launch claude in this folder, read the line displayed at startup, then type /memory and find the path of your file there.

Check the source

Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.