Does Claude Code read AGENTS.md?

What changed in v2.1.277 and v2.1.281

Before September 2026, Claude Code read only CLAUDE.md files (see AGENTS.md vs CLAUDE.md vs Cursor rules for what each file is for), so teams that already kept an AGENTS.md for Codex, Cursor or Copilot had to add a CLAUDE.md, an import, a symlink or a hook. Two releases changed that:

• v2.1.277 (September 18, 2026): "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config."
• v2.1.281 (September 23, 2026): "Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled." Before 2.1.281 those sessions read CLAUDE.md only, so articles that still say "not on Bedrock or Vertex" describe older versions.

When Claude Code reads AGENTS.md (the CLAUDE.md check)

By default Claude Code reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it. The docs split your files into two groups for that check:

• Files that block AGENTS.md: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it.
• Files that don't block it and keep loading alongside AGENTS.md: your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files.
• Loaded at session start: every AGENTS.md and .claude/AGENTS.md in your working directory and the folders above it. In an interactive session you see a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
• Loaded later: a subfolder's AGENTS.md, when Claude opens a file there with the Read tool and that subfolder has none of the three CLAUDE.md files of its own.
• Inside each AGENTS.md: @path imports are expanded and claudeMdExcludes patterns apply. Subagents that skip project instructions skip AGENTS.md too.
• Never read: AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ folder. (Codex does read AGENTS.override.md; Claude Code does not.)

The CLAUDE.local.md trap

CLAUDE.local.md counts as a CLAUDE.md for the check. If your project relies on AGENTS.md and you add a personal, uncommitted CLAUDE.local.md, Claude Code stops reading AGENTS.md for you, while teammates without that file still get it. To keep your CLAUDE.local.md and still load AGENTS.md, set Project instructions to claude-md-and-agents-md.

How to make Claude Code read both AGENTS.md and CLAUDE.md

Type /config in a Claude Code session and set Project instructions to one of four values. The change applies from your next message and in every new session.

You can set the same value in a settings file under the built-in agents-md plugin's ID in pluginConfigs. Claude Code honours it only in ~/.claude/settings.json, a file you pass with --settings, or managed settings. It ignores the key in project and local settings, so committing it to .claude/settings.json does not switch it on for your team. For a team-wide default, use managed settings, or commit a CLAUDE.md that imports AGENTS.md (next section).

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

Use an @AGENTS.md import (works on every version)

Put a CLAUDE.md next to your AGENTS.md that imports it, then add any Claude-only notes below the import. This is also how you share instructions across repos without copies drifting apart. Claude reads the imported file first, then the rest. Use this when the repo also needs Claude-specific lines, when some teammates run a version older than 2.1.277, or when Project instructions is set to claude-md. Keeping the import never makes Claude read AGENTS.md twice, whichever value you pick in /config.

@AGENTS.md

## Claude Code only
- Use plan mode before changing files under billing/.

How to check that Claude Code loaded your AGENTS.md

Three quick checks, from the Claude Code docs:

• Run /memory and look for your AGENTS.md path in the list.
• In an interactive session, look for the start-up line no CLAUDE.md found; AGENTS.md loaded: <path>.
• Before v2.1.280, /memory and /context didn't list an AGENTS.md that Claude read directly. On those versions, ask Claude what its project instructions say.

AGENTS.md not loading? Checklist

Work through these in order. The first one is the usual cause.

Should you keep your old AGENTS.md workaround?

If you set Claude Code up to read AGENTS.md before it did so itself, here is what the docs recommend for each common setup:

Symlinks have two caveats. The Edit and Write tools refuse to write through a symlink and point Claude at the target file instead. On Windows, creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md. Teams with Windows users should use the import.

ln -s AGENTS.md CLAUDE.md

Where AGENTS.md behaves differently from CLAUDE.md

An AGENTS.md that Claude reads through the Project instructions setting differs from a CLAUDE.md in three places:

Copying AGENTS.md into CLAUDE.md with /init or /import

If you would rather keep a real CLAUDE.md, /init reads AGENTS.md when CLAUDE_CODE_NEW_INIT=1 is set and folds the relevant parts into the CLAUDE.md it generates. /import (v2.1.213 or later) appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md. Both create a copy, so the two files can drift apart; the import approach above keeps one source.

What belongs in AGENTS.md, and what should be a skill

AGENTS.md loads into every session, so keep it to always-on facts: build and test commands, folder layout, and conventions. Step-by-step procedures and checklists that only matter for some tasks work better as skills, which load only when a task needs them; skills vs MCP vs subagents vs hooks shows where each kind of instruction belongs. Claude Code's docs suggest keeping each CLAUDE.md under 200 lines; that advice is written for CLAUDE.md, and Codex caps combined AGENTS.md text at 32 KiB by default. See AGENTS.md vs SKILL.md for the split and every agent config file explained for the wider picture.

AIPM doesn't install AGENTS.md or CLAUDE.md; keep those in your repo. It installs versioned skills from the registry into Claude Code (.claude/skills/<name>/SKILL.md); every other folder Claude reads skills from is in where Claude skills are stored. Browse Claude skills or see all commands. Using Codex too? --target codex installs the same skill to .agents/skills/<name>/SKILL.md, which Cursor also reads.

npm install -g @aipm-registry/cli
aipm init --target claude
aipm add @scope/name@1.0.0 --target claude

Does Claude Code read AGENTS.md automatically?

Yes, since v2.1.277, as long as there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it.

Does Claude Code read AGENTS.md if I also have a CLAUDE.md?

Not by default. Set Project instructions to claude-md-and-agents-md in /config, or put @AGENTS.md at the top of your CLAUDE.md.

Can I make Claude Code always read both files for my whole team?

Only through user settings, a --settings file or managed settings; Claude Code ignores the setting in a committed .claude/settings.json. The simplest team-wide option is to commit a CLAUDE.md that imports @AGENTS.md.

Why isn't Claude Code loading my AGENTS.md?

Usually a CLAUDE.md or CLAUDE.local.md is somewhere on the path. Also check your version, the Project instructions value in /config, and that the built-in agents-md plugin isn't disabled.

Does Claude Code read AGENTS.override.md or AGENTS.local.md?

No. Claude Code doesn't read AGENTS.override.md, AGENTS.local.md, or anything under a .agents/ folder. Codex is the tool that uses AGENTS.override.md.

Should I symlink CLAUDE.md to AGENTS.md?

It works, but the Edit and Write tools won't write through the link, and Windows clones can end up with a one-line CLAUDE.md. The @AGENTS.md import is the safer choice.

Does it work on Amazon Bedrock or Google Vertex AI?

Yes, from v2.1.281, which also covers Microsoft Foundry, LLM gateways and sessions with telemetry disabled.