Meltlight

AGENTS.md vs CLAUDE.md: which one Claude Code reads

Updated

The problem

You keep your project instructions in AGENTS.md so that every coding agent can read them. Then you open the project in Claude Code and it behaves as if the file were not there — or it follows a CLAUDE.md and ignores AGENTS.md. The questions people search for are "AGENTS.md vs CLAUDE.md" and "does Claude Code read AGENTS.md".

The short answer

Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. If you have both files, put the line @AGENTS.md at the top of CLAUDE.md: Claude Code then imports AGENTS.md and reads it before the rest of CLAUDE.md.

Why it happens

Everything in this section is from the Claude Code memory docs. I have not tested each version number below myself.

The default is "one or the other". The default value of the Project instructions setting is claude-md-or-agents-md. Claude Code first looks for CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md from the working directory upwards. Only if none of them exists does it load every AGENTS.md and .claude/AGENTS.md it finds on that path, and it says so with the line "no CLAUDE.md found; AGENTS.md loaded: …".

Some files do not count in that check. Your personal ~/.claude/CLAUDE.md, a managed CLAUDE.md and the files in .claude/rules/ keep loading next to AGENTS.md.

A CLAUDE.local.md is enough to switch AGENTS.md off. Because CLAUDE.local.md is one of the three files in the check, adding one for your personal notes stops Claude Code from reading the team's AGENTS.md. This is the case that surprises people most.

Subdirectories follow the same rule. An AGENTS.md in a subdirectory loads when Claude reads a file in that subdirectory and the subdirectory has no CLAUDE.md of its own.

Saying "read AGENTS.md" in words is not an import. If your CLAUDE.md contains a sentence like "Follow the instructions in AGENTS.md", Claude sees AGENTS.md only if it decides to open the file. An @AGENTS.md line is different: Claude Code expands it into the context when the session starts.

Version requirements. Reading AGENTS.md directly needs Claude Code v2.1.277 or later, with the built-in agents-md plugin enabled. The docs note that it can be missing in the first session after upgrading from v2.1.276 or earlier, and that before v2.1.281, sessions on Amazon Bedrock or with telemetry disabled read CLAUDE.md only. Run claude --version if AGENTS.md never loads.

Check it with the tool

Paste either file into Kanon (beta), the free SKILL.md, CLAUDE.md and AGENTS.md linter on this site, and pick the matching file type. It runs in your browser and sends nothing anywhere.

  • With CLAUDE.md selected, Kanon warns agents-words when the file mentions AGENTS.md in words but never imports it with @AGENTS.md. It also lists every @path import it finds (imports), flags imports that point outside the project, and counts HTML comments that Claude Code strips (html-comment).
  • With AGENTS.md selected, Kanon adds the note agents-precedence: a reminder that Claude Code reads this file only when no CLAUDE.md exists.
  • For both, mem-length warns when the file is over 200 lines, the size the docs suggest staying under.

What to do next

Pick one of these, depending on how your repository is set up.

You only use Claude Code. Keep CLAUDE.md. You do not need AGENTS.md.

You only have AGENTS.md. Claude Code v2.1.277 or later reads it as it is. If you later add a CLAUDE.local.md, also switch the setting described in the last option below; that is the fix the docs give for this case.

You want one shared file plus Claude-specific notes. This is the setup the docs describe:

  1. Keep the shared instructions in AGENTS.md.
  2. Create CLAUDE.md with @AGENTS.md on its first line.
  3. Write anything that only applies to Claude Code below that line.
  4. Delete any sentence that tells Claude to "read AGENTS.md" — the import replaces it.

A symlink from CLAUDE.md to AGENTS.md also works if you have nothing Claude-specific to add.

You want Claude Code to load both files without an import. Change the Project instructions setting to claude-md-and-agents-md with /config, or put this in ~/.claude/settings.json:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Only your user settings, a --settings file or managed settings are read for this option; a project's .claude/settings.json is ignored. With this setting, an AGENTS.md that a CLAUDE.md already imports is not loaded twice.

Then confirm. Start a new session and run /context. The files Claude Code loaded are listed under "Memory files". If AGENTS.md is not there, it is not in the context, whatever CLAUDE.md says.