Claude Code's New AGENTS.md Support Has Four Config Values. Most Coverage Only Found the Default One (2026)

Claude Code v2.1.277 (September 18, 2026) added native AGENTS.md support: with no CLAUDE.md in your project, Claude now reads AGENTS.md instead. That’s the one-line version every launch-week writeup ran with. The actual mechanism, per Anthropic’s current documentation, is a Project instructions setting with four values — and a set of rules about which files “count” as a CLAUDE.md that trips up the exact repos this feature was built for: ones that already have a stray CLAUDE.local.md lying around.

What Shipped in v2.1.277, Exactly

Anthropic’s own changelog entry is one line: “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).” The docs page spells out the default behavior as a three-row table:

That middle row is the one most launch-day coverage flattened into “CLAUDE.md wins.” It’s true, but it hides which files are doing the winning — which matters more than it sounds like it should.

The Four Values Behind “Project Instructions”

/config exposes this as a picker, and it’s not a binary on/off. There are four values:

You can set this outside /config too, in a settings file, under the built-in agents-md plugin’s ID:

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

Two details from the docs worth flagging on that snippet: it’s read from ~/.claude/settings.json, a --settings file, or managed settings — Claude Code ignores it in project and local settings files, so you can’t commit this choice to a repo and have it apply to teammates automatically. And whichever value you pick, it applies from your next message on, not retroactively in the current one.

The CLAUDE.local.md Gotcha

This is the detail every summary we found (including the aggregator posts already ranking for “Claude Code AGENTS.md”) left out, and it’s the one that will actually bite teams migrating to this feature.

The default claude-md-or-agents-md value checks for three files before deciding whether to read AGENTS.md:

• Count, so Claude reads them instead of AGENTS.md: CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it
• Don’t count, and keep loading alongside AGENTS.md: ~/.claude/CLAUDE.md (your personal, all-projects file), the organization’s managed CLAUDE.md, and .claude/rules/ files

The gotcha: CLAUDE.local.md — a gitignored, personal, per-project file that most guides describe as harmless scratch space — counts as a blocker. If you’re the one developer on a team who keeps a CLAUDE.local.md with your sandbox URLs and test data, you’re also the one developer whose Claude Code session silently ignores the team’s AGENTS.md and falls back to nothing, while everyone else on claude-md-or-agents-md reads it fine. The docs call this out directly: “adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you.” The documented fix is to switch your own setting to claude-md-and-agents-md, not to delete your CLAUDE.local.md.

Subdirectories and Monorepos

None of the launch-week posts we checked (a handful already ranking for this topic) addressed how this behaves once you leave the repo root. Per the docs, at session start Claude reads every AGENTS.md and .claude/AGENTS.md in the working directory and the directories above it — the same ancestor-chain logic CLAUDE.md already uses. As Claude works and opens files in subdirectories, a subdirectory’s own AGENTS.md loads too, but only if that subdirectory has none of the three counting files (CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md) of its own. In other words: the fallback decision isn’t made once per session, it’s made per directory, the same way nested CLAUDE.md resolution already works — which means a monorepo can end up with some packages reading their local AGENTS.md and others reading a CLAUDE.md a team committed two years ago, without anyone changing a setting.

Two file patterns are explicitly not read even under AGENTS.md fallback: AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ directory. If your team adopted either naming convention from another tool’s ecosystem expecting Claude Code to pick it up automatically, it won’t — those need the same @import treatment as before.

Confirming It Actually Loaded

This is where the feature gets deliberately quiet, and it’s worth knowing before you assume it’s broken. An AGENTS.md read through the Project instructions setting does not show up in /memory or in the Memory files list under /context — both of those still only list CLAUDE.md-family files. The only visible confirmation is a line printed at session start: no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md. If you scrolled past that or you’re checking retroactively, your fallback is to just ask Claude what its project instructions say.

InstructionsLoaded hooks follow the same rule: they fire for CLAUDE.md-family files and for an AGENTS.md reached through an @import or symlink, but not for one read directly through the new fallback. If you built tooling on that hook to audit which instruction files loaded in CI, it will silently under-report as soon as a repo switches from the @AGENTS.md import workaround to relying on native fallback.

When AGENTS.md Support Isn’t Available At All

/config won’t even show the Project instructions row in these sessions — Claude reads CLAUDE.md only, full stop:

• Claude Code version before v2.1.277
• Sessions that don’t fetch feature flags from Anthropic — Amazon Bedrock, other third-party providers, or telemetry disabled
• Your first session after installing or upgrading to a version with support (it applies from the next session)
• disableAllHooks or allowManagedHooksOnly is set, or the built-in agents-md plugin is disabled in /plugin

If you’re on Bedrock or you’ve disabled telemetry for compliance reasons, none of the four values above are reachable — your only path to feeding Claude an AGENTS.md is still the pre-v2.1.277 @AGENTS.md import.

Retiring the Old Workaround — Or Not

If your team already solved this with an import, a symlink, or a hook before Anthropic shipped native support, the docs give a specific answer for each, and it isn’t “delete everything”:

• CLAUDE.md containing @AGENTS.md: safe to leave. Claude Code never reads the file twice regardless of setting. Keep it if any of your sessions fall into the “not available” list above; delete it only if it holds nothing else and every session can load AGENTS.md natively.
• CLAUDE.md that tells Claude in prose to “read AGENTS.md”: this only worked when Claude decided to open the file on its own. Replace the sentence with an actual @AGENTS.md import, or delete the file so native fallback takes over.
• CLAUDE.md symlinked to AGENTS.md: no action needed, or delete the symlink — either way the content loads once.
• A SessionStart hook that prints AGENTS.md into context: remove it. Once native reading kicks in, the hook adds a duplicate copy on top.

Which Setting Should You Actually Pick?

The default (claude-md-or-agents-md) is the right call for the common case this feature targets: a repo already using AGENTS.md for Cursor, Codex, or another tool, with no CLAUDE.md at all. You get cross-tool consistency for free and never touch /config.

Reach for claude-md-and-agents-md in two specific situations: a team where individual contributors keep their own CLAUDE.local.md files (the gotcha above), or a repo that wants a committed, cross-tool AGENTS.md plus a thin layer of Claude-specific instructions in CLAUDE.md without wiring up an explicit import.

Pick claude-md if you maintain both files on purpose and want AGENTS.md to stay exclusively for other tools — this restores exactly the pre-v2.1.277 behavior. And managed-only is an admin-side lockdown value, not something an individual contributor sets: it’s for sessions where you want nothing but centrally managed policy loaded, full stop, ignoring every project, local, user, and AGENTS.md file in the repo.

The Backstory This Fits Into

We covered issue #6235 five days before this shipped — the single most-upvoted issue in the claude-code repo, 5,146 👍, auto-closed as “completed” by an inactivity-sweep bot without the actual feature landing. At the time, native fallback loading genuinely hadn’t shipped; the closure was bad bot hygiene, not a maintainer’s call. Three days later, v2.1.277 shipped the exact behavior the issue asked for. Neither fact cancels the other out: the auto-close was still wrong when it happened, and the feature request it dismissed was still legitimate — Anthropic just happened to ship the ask shortly after, on its own schedule, unrelated to the sweep bot’s bookkeeping.

For the general case for and against unifying instruction files across tools, see our comparison of AGENTS.md vs. CLAUDE.md. For the subagent-specific version of this problem — giving individual subagents their own scoped instructions instead of the whole project’s CLAUDE.md — see dedicated AGENTS.md files per subagent and the newer omitClaudeMd flag that replaced part of that workaround in v2.1.271.

Browse real-world CLAUDE.md and AGENTS.md files from active repositories in our gallery.

FAQ

Does Claude Code read AGENTS.md now?

Yes, as of v2.1.277 (September 18, 2026), under the default Project instructions setting: if there’s no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it, Claude Code reads AGENTS.md directly. This wasn’t true in any version before v2.1.277.

Why isn’t Claude Code reading my AGENTS.md even after upgrading?

The most common cause is a stray CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md somewhere in the working directory or an ancestor directory — including a personal, gitignored CLAUDE.local.md you forgot about. Also check claude --version is v2.1.277+, confirm your session isn’t on Bedrock/Vertex/Foundry or running with telemetry disabled, and check /config still shows Project instructions set to something other than claude-md or managed-only.

What’s the difference between claude-md-or-agents-md and claude-md-and-agents-md?

claude-md-or-agents-md (the default) reads AGENTS.md only when no CLAUDE.md-family file exists above the working directory — it’s an either/or fallback. claude-md-and-agents-md reads both every time, with each directory’s CLAUDE.md loaded first and its AGENTS.md after, skipping any AGENTS.md already pulled in through an import or symlink.

Does an AGENTS.md loaded through the new fallback show up in /context or /memory?

No. /memory and the Memory files list in /context only list CLAUDE.md-family files. An AGENTS.md read directly through the Project instructions setting is invisible there; the only confirmation is the AGENTS.md loaded line printed at session start, or asking Claude what its project instructions say.

Does this work on Amazon Bedrock or Google Vertex?

Not yet, per Anthropic’s own changelog entry. Sessions on Bedrock, Vertex, or Foundry — along with sessions that have telemetry disabled or don’t fetch feature flags from Anthropic for any other reason — read CLAUDE.md only, and the Project instructions row doesn’t appear in /config at all. The @AGENTS.md import workaround still works in those sessions.

Should I delete my old @AGENTS.md import now that native support shipped?

Not necessarily. Anthropic’s own guidance is that it’s safe to leave — Claude Code never reads the same AGENTS.md twice regardless of setting. Keep it if any of your team’s sessions fall into a category where native AGENTS.md support is unavailable (Bedrock, telemetry-disabled, etc.); remove it only if the CLAUDE.md holding it has no other content and every session that uses the repo can load AGENTS.md natively.