Claude Code Reads AGENTS.md Now: Setup, the Four Loading Modes, and How to Share One File with Codex, OpenCode, and Cursor

Name

Soren Atelier

Updated on 9/21/2026

The short version: since Claude Code v2.1.277 (September 18, 2026), a repository with an AGENTS.md and no CLAUDE.md anywhere on the path gets its instructions from AGENTS.md automatically. Nothing to install, no import line, no symlink. If a CLAUDE.md or CLAUDE.local.md exists in the working directory or any parent, Claude Code keeps reading that and ignores AGENTS.md, unless you change the Project instructions setting in /config.

Check it in ten seconds. In a repo that has only AGENTS.md, start a new session and look for this line near the top of the conversation:

no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md

If you do not see it, one of four things is true, and all four are covered below: you are on an older version, a CLAUDE.md or CLAUDE.local.md is hiding in a parent directory, this is your first session after upgrading, or your session type cannot load AGENTS.md at all (Bedrock, Vertex, Foundry, telemetry disabled).

Everything below marked tested was run on Claude Code 2.1.278 on macOS on September 21, 2026, with claude -p in a fresh scratch repository. Everything else comes from the official memory documentation (opens in a new tab) and the changelog (opens in a new tab).

What changed, exactly

The changelog entry for 2.1.277 is one sentence:

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)

Before this release, teams that standardized on AGENTS.md (opens in a new tab) for Codex, OpenCode, Cursor, and others had to keep a CLAUDE.md alongside it, containing either a duplicate, an @AGENTS.md import, or a symlink. The Hacker News thread (opens in a new tab) on the release (725 points, 273 comments) is mostly people describing which of those workarounds they had been maintaining.

The release does not make AGENTS.md equal to CLAUDE.md. It adds a fallback with a switch. The rest of this guide is about where the fallback stops and the switch matters.

Which file wins: the decision table

This is the default behavior, mode claude-md-or-agents-md. The check for "a CLAUDE.md exists" covers CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md in the working directory and every directory above it. Your personal ~/.claude/CLAUDE.md, an organization's managed CLAUDE.md, and .claude/rules/ files do not count and keep loading alongside AGENTS.md.

The third row is the trap most people will hit first. CLAUDE.local.md is the documented place for personal, uncommitted instructions. Adding one to a project that relies on AGENTS.md silently switches Claude back to ignoring AGENTS.md. The fix is one setting, covered next.

How I tested this

Each AGENTS.md or CLAUDE.md in the scratch repo contained a single instruction: start every reply with a fixed marker such as [AGENTS_MD_LOADED]. Then:

mkdir agentsmd-test && cd agentsmd-test && git init -q
printf '# AGENTS.md\n\nAlways begin your reply with the exact token [AGENTS_MD_LOADED].\n' > AGENTS.md
claude -p "What is 2+2? Answer in five words or fewer." < /dev/null

A reply beginning with [AGENTS_MD_LOADED] means the file was loaded. A plain 4. means it was not. This is cruder than /context, but /context and /memory do not list a directly loaded AGENTS.md (see the differences table below), so the marker method is the one that works for both files.

The four Project instructions modes

Open /config in a session and set Project instructions, or set the same value in ~/.claude/settings.json under the built-in agents-md plugin. Claude Code ignores this key in project-level and local settings files, so it cannot be committed into a repo; it is a per-user or managed choice.

The settings-file form:

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

Tested: passing that JSON with --settings both.json in a repo containing both files produced a reply beginning [CLAUDE_MD_LOADED] [AGENTS_MD_LOADED], in that order. Passing "instructionFiles": "claude-md" in a repo with only AGENTS.md produced a plain 4., so the file was ignored as documented.

Why it does not work in the first session after upgrading

This one cost me two test runs. The docs say support is unavailable in "your first session after you install or upgrade" and that Claude reads AGENTS.md "from your next session on".

Tested: with a freshly installed 2.1.278 and a repo containing only AGENTS.md, the first claude -p run ignored the file. So did the second. The third run loaded it. Non-interactive -p runs are short, so the feature flag that gates AGENTS.md support may not have been fetched by the time the second run started. The practical rule: after upgrading, open one throwaway session, close it, and only then judge whether AGENTS.md is being read.

Sessions that cannot load AGENTS.md at all, per the docs:

• Amazon Bedrock, Google Vertex AI, and Microsoft Foundry
• telemetry disabled, because the feature flag cannot be fetched
• disableAllHooks or allowManagedHooksOnly set, or the built-in agents-md plugin disabled in /plugin
• the first session after install or upgrade, as above

In all of these, Project instructions does not appear in /config at all, which is the quickest way to tell. The fallback for those sessions is the import described in the next section.

Where a directly loaded AGENTS.md differs from CLAUDE.md

An AGENTS.md read through the setting is not a drop-in CLAUDE.md. Three visible differences from the docs:

Subdirectory AGENTS.md files load on demand, when Claude opens a file in that directory with the Read tool and the directory has no CLAUDE.md of its own. @path imports inside an AGENTS.md are expanded, and claudeMdExcludes patterns apply to it.

Migration: what to do with your existing workaround

If you set up AGENTS.md reading before 2.1.277, here is the docs' guidance per setup, with my reading of when to act.

• CLAUDE.md containing only @AGENTS.md: you can delete it if every session you use supports the new behavior. Keep it if anyone on the team works through Bedrock, Vertex, or Foundry, since those still need the import. Keeping it never causes a double read.
• CLAUDE.md that says "read AGENTS.md" in prose: replace the sentence with @AGENTS.md or delete the file. Prose only works if Claude decides to open the file; an import is deterministic.
• CLAUDE.md symlinked to AGENTS.md: works either way, but the Edit and Write tools refuse to write through a symlink and redirect to the target. On Windows, a committed symlink checks out as a one-line text file unless core.symlinks is on, so prefer the import there.
• A SessionStart hook that prints AGENTS.md: remove it. Once Claude reads AGENTS.md directly, the hook injects a second copy into context.
• Both files with different content: decide whether the Claude-specific part is worth a separate file. If yes, keep AGENTS.md for the shared rules, keep a short CLAUDE.md for Claude-only rules, and set claude-md-and-agents-md so both load. If no, merge into AGENTS.md and delete CLAUDE.md.

The docs also suggest the sharing pattern for repos that must keep a CLAUDE.md:

@AGENTS.md
 
# Claude-specific
- Use the `Bash` tool for git; do not call the GitHub MCP for pushes.

Claude reads the import first, then the Claude-only lines.

What the other tools read

The point of standardizing on AGENTS.md is that one file serves every agent. Here is what each tool actually does with it, from their current docs.

Two consequences for a shared file:

1. Codex will not read CLAUDE.md at all, so anything that lives only there is invisible to Codex. If you were using Codex and Claude Code on the same repo with two files, AGENTS.md is the only file both see.
2. OpenCode reads CLAUDE.md only when there is no AGENTS.md, which is the mirror image of Claude Code's default. In a repo with both files, Claude Code reads CLAUDE.md and OpenCode reads AGENTS.md. If the two files disagree, the two agents follow different rules without either telling you.

The safe end state for a multi-tool repo is therefore: one AGENTS.md with the shared rules, no CLAUDE.md unless you have Claude-only rules, and if you do, a CLAUDE.md that starts with @AGENTS.md.

Recommended setup by situation

Troubleshooting: AGENTS.md is not loading

Work through these in order; each one was either reproduced above or is the docs' stated cause.

1. Run claude --version. You need 2.1.277 or later. Update with claude update if the version is older.
2. Search every parent directory for CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md:

d="$PWD"; while [ "$d" != "/" ]; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do [ -f "$d/$f" ] && echo "blocks AGENTS.md: $d/$f"; done; d=$(dirname "$d"); done

Any hit other than ~/.claude/CLAUDE.md means Claude reads that file instead, unless you switch to claude-md-and-agents-md.

3. Start a second session if you just upgraded. In my test the third run was the first to load the file.
4. Open /config and confirm Project instructions is not claude-md or managed-only. If the setting is missing entirely, your session type cannot load AGENTS.md; use the @AGENTS.md import.
5. Do not rely on /memory or /context to confirm. A directly loaded AGENTS.md is not listed there. Look for the AGENTS.md loaded line or ask Claude to quote its project instructions.

FAQ

Does Claude Code read AGENTS.md by default?

Yes, since v2.1.277, but only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or any parent directory. If one exists, Claude Code reads it and ignores AGENTS.md unless you set Project instructions to claude-md-and-agents-md.

Can I make Claude Code read both CLAUDE.md and AGENTS.md?

Yes. Set Project instructions to claude-md-and-agents-md in /config, or in ~/.claude/settings.json under pluginConfigs → agents-md@builtin → options.instructionFiles. Each directory's CLAUDE.md loads first, then its AGENTS.md. A file already imported from CLAUDE.md is not read twice.

Why does my AGENTS.md not load right after updating Claude Code?

The first session after an install or upgrade cannot read AGENTS.md; support starts from a later session. In testing with claude -p, the third run was the first to load it. Start and close a throwaway session, then check again.

Should I delete CLAUDE.md if I already have AGENTS.md?

If CLAUDE.md only contains @AGENTS.md and nobody on the team uses Bedrock, Vertex, or Foundry, you can delete it. If it holds Claude-specific rules, keep it and put @AGENTS.md on its first line so both load everywhere.

Does Codex read CLAUDE.md?

No. Codex reads AGENTS.override.md or AGENTS.md per directory from the repo root down to the working directory, plus ~/.codex/AGENTS.md, with configurable fallback names in config.toml. Anything that exists only in CLAUDE.md is invisible to Codex.

Related Guides

• How to Use Codex
• Oh My OpenCode and OpenCode: Install, Setup, and Fixes
• Claude Code Bypass Permissions: Desktop Toggle, CLI Flags, and Error Fixes
• Claude Code Routines
• How to Use DeepSeek Harness