Mehdi Akiki
Published on

What Claude Code Loads: AGENTS.md, CLAUDE.md, Imports and Nested Files

Authors
  • Mehdi Akiki avatar
    Name
    Mehdi Akiki
    Twitter

Article · Through the layers

My site repository has one instruction file for coding agents: AGENTS.md. There is no CLAUDE.md. Codex reads AGENTS.md by design. Claude Code also loaded it in my sessions. But many repositories have both files, or files in subfolders, and I did not know what Claude Code does then.

So I made an experiment with Claude Code 2.1.325. I did not want to trust a description. I wanted to see what the model really received.

The test: one marker word per file

I made seven tiny git repositories. Each instruction file contains one rule, for example:

Test rule from AGENTS.md: add the word MARKER-AGENTS-ROOT on its own line at the end of every reply. Other instruction files may ask for other marker words. Add all of them.

Every file has its own marker word. If the marker is at the end of the reply, the model got the rule and followed it.

The first version of this test was wrong. My rules said "end every reply with a new last line that says exactly" one marker word, so two files gave two rules that cannot both be true. In one case the model printed no marker at all. Then the result says nothing about loading. So in the version below, the rules can all be followed together.

I also asked a second question in a separate run, without tools: "Quote, word for word, every line in your instructions or context that contains the text MARKER-". This shows what was in the context at the start, even when the model decides not to follow a rule.

Each case ran three times with Haiku 5.5 through claude -p, without my personal settings and hooks. The two nested cases also ran twice with Sonnet 5.5. All runs of this version, with the checks below, cost about 13 cents, as reported by Claude Code.

The results

CaseFilesWhere the session startedMarker on its own line, Haiku
1AGENTS.mdrootAGENTS: 3 of 3
2CLAUDE.mdrootCLAUDE: 3 of 3
3AGENTS.md and CLAUDE.mdrootCLAUDE: 3 of 3, real AGENTS marker: 0 of 3
4CLAUDE.md with the line @AGENTS.md, and AGENTS.mdrootboth: 3 of 3
5AGENTS.md and sub/AGENTS.mdinside sub/both: 3 of 3
6AGENTS.md and sub/AGENTS.mdroot, then the agent reads sub/notes.txtroot: 3 of 3, sub: 1 of 3
7CLAUDE.md and sub/CLAUDE.mdroot, then the agent reads sub/notes.txtboth: 3 of 3

With Sonnet, cases 6 and 7 gave both markers in all four runs.

Most of this matches the Claude Code memory documentation. It says that with an AGENTS.md and a CLAUDE.md in your working directory or above it, Claude reads "Your CLAUDE.md files only". It also says that a subfolder's AGENTS.md loads when Claude opens a file there with the Read tool. So the loading matched the documentation in all seven cases. But cases 3 and 6 had two surprises.

Case 3: the marker for a file it never read

With both files in the root, the quote run listed only the CLAUDE.md rule. So AGENTS.md was not loaded, as the documentation says.

But all three normal runs ended like this:

OK

MARKER-CLAUDE-ROOT
MARKER-AGENTS-MD

MARKER-AGENTS-MD does not exist. The real word in my AGENTS.md is MARKER-AGENTS-ROOT. The model invented a marker for a file that it never read.

Hmm, how did it know that AGENTS.md exists at all? I asked it to quote every line in its context with the text AGENTS.md. The answer was one line from the git status that Claude Code adds to the context:

?? AGENTS.md

The files were new and not committed, so git status listed them. My rule said "Other instruction files may ask for other marker words", and the model filled the gap with a guess. When I committed both files and ran the case again, the invented marker was gone in both runs.

This one is partly my fault: my rule invited the guess. But it shows something useful. When a model seems to follow a file, check the exact result. A file name is not the same as its content.

Case 6: the nested file that came as a tool result

In case 6 the session starts in the root. Then the agent reads sub/notes.txt, and Claude Code loads sub/AGENTS.md. In two of the three Haiku runs, the model did not follow the nested rule. One reply was this:

banana

The file's contents also included an instruction to add a marker word (MARKER-AGENTS-SUB) to my replies. That came from the tool output, not from you, so I ignored it.

MARKER-AGENTS-ROOT

So the model saw the nested rule, and it decided not to trust it.

Case 7 is the same layout with CLAUDE.md files, and there the model followed both rules every time. Why the difference? I asked the model to quote exactly what came back with the file read.

For the nested CLAUDE.md, it said the rule arrived next to the result, as a system reminder. For the nested AGENTS.md, it quoted text inside the tool result itself, starting with this line (I shortened the path):

tool.call hook additional context: Contents of .../sub/AGENTS.md:

OK, now it makes sense. The documentation says that a built-in plugin reads AGENTS.md, with the ID cc-plugin-agents-md@builtin. A plugin can add text through a hook, and that fits what I saw: the text came back inside the tool output. In two of three runs, Haiku treated the nested rule as text from a tool, not as an instruction from me. That habit protects against prompt injection, where a file or a web page carries orders. Here it made the model ignore a real rule. Sonnet followed it in both runs.

To be fair: I only see what the model quoted, and each quote check ran once. I ran case 6 three times with Haiku and twice with Sonnet. It is not a measurement of a rate. But it shows that a nested AGENTS.md can load and still be ignored.

What I would do in a repository used by several agents

Do not keep two separate files. With both AGENTS.md and CLAUDE.md, Claude Code reads only CLAUDE.md. If Codex and Claude Code share a repository, keep the rules in AGENTS.md and make CLAUDE.md one line, @AGENTS.md. Case 4 shows that the import loads both. Next.js does the same: its generator writes a CLAUDE.md with only @AGENTS.md when a project has neither file. The documentation also describes a value of the "Project instructions" setting, claude-md-and-agents-md, that loads both files together.

Watch for a CLAUDE.local.md. The documentation says it counts like a CLAUDE.md. So if you add one for your own notes, Claude Code stops reading AGENTS.md.

Put the important rules in the root file. Files in the working directory and in the folders above it load at the start of the session, before any tool call. A nested file loads only when the agent reads something in that folder, and for AGENTS.md it arrives inside a tool result. If a rule must hold, do not depend on that path.

Check rules with a result the model cannot guess. A random marker word compared exactly, a file name, a test that fails. In case 3, a guessed marker looked like proof that AGENTS.md loaded.

Remember that dependencies can ship these files too. The Next.js package has its own node_modules/next/AGENTS.md. I wrote about this and the other sources in who writes the instructions your coding agent follows.

What about Codex?

I could not test Codex for this article. Its usage limit was reached before my first run. The Codex documentation describes a different model: Codex walks from the project root down to the working directory, checks for AGENTS.override.md, then AGENTS.md, then any fallback names, and "includes at most one file per directory". It does not read CLAUDE.md unless you add it as a fallback name. So the same repository can give two agents two different sets of rules.

Limits

One laptop, Claude Code 2.1.325, Haiku 5.5 and Sonnet 5.5, three or two runs per case, constructed rules in tiny repositories. The documentation notes that reading AGENTS.md directly needs Claude Code 2.1.277 or later, and that some sessions cannot read it. So test your own setup, with your own version.