AGENTS.md vs CLAUDE.md in Claude Code: share one file

From Claude Code 2.1.277+, a repo with AGENTS.md and no project CLAUDE.md / CLAUDE.local.md on the path loads AGENTS.md by default. To keep one shared file and Claude-only notes: put @AGENTS.md at the top of a sibling CLAUDE.md, or set Project instructions in /config to claude-md-and-agents-md. Native AGENTS load is not yet available on Bedrock, Vertex, or Foundry - use the import there.

What Claude Code loads by default

CHANGELOG 2.1.277 (fetched 2026-09-19; head also lists 2.1.278):

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)

Official memory docs spell out the default table:

Do not count for the “has CLAUDE” check: ~/.claude/CLAUDE.md, org managed CLAUDE.md, and .claude/rules/. Those keep loading alongside AGENTS when the default applies.

Confirm in an interactive session with a line like no CLAUDE.md found; AGENTS.md loaded: …. Direct AGENTS load is not listed under Memory files in /context or /memory. We haven't run this in the CLI yet (as of 2026-09-19), so the load-line wording comes from the docs, not a live session.

Version floor: v2.1.277+. Prior CHANGELOG context: 2.1.271-272 notes. Same-day catch-up: Claude Code 2.1.273-2.1.278.

Share one file without drift

Docs-only recipes:

1. AGENTS-only repo - Commit AGENTS.md, no project CLAUDE. Upgrade to 2.1.277+. Check the load line on the next session (first session after install/upgrade may still skip native AGENTS).
2. @AGENTS.md import (recommended for dual-file or provider fallback) - Sibling CLAUDE.md:

   @AGENTS.md
   
   ## Claude Code
   Use plan mode for changes under `src/billing/`.
   

   Claude reads the import first, then Claude-specific notes. Keeping the import does not double-read AGENTS under claude-md-and-agents-md.
3. Always both files - /config → Project instructions → claude-md-and-agents-md. Or set user/managed settings:

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

   Put that in ~/.claude/settings.json, a --settings file, or managed settings - ignored in project/local settings files. Other values: claude-md-or-agents-md (default), claude-md, managed-only.
4. Symlink - ln -s AGENTS.md CLAUDE.md works on Unix if you accept Edit/Write refusing to write through the link, and Windows Admin/Developer Mode + core.symlinks checkout caveats. Prefer the @ import for Windows/clone-safe teams.
5. Drop SessionStart hooks that print AGENTS, and word-only “please read AGENTS.md” lines. Keep @AGENTS.md if some sessions still lack native load.

Adjacent settings hygiene: /skill-doctor. Skills/plugins sync across Claude.ai ↔ Claude Code: How do I sync Claude.ai skills and plugins into Claude Code?.

When native AGENTS.md support is unavailable

CHANGELOG: not yet on Bedrock, Vertex, or Foundry. Memory docs also list sessions that never fetch feature flags (telemetry disabled / third-party providers), the first session after install/upgrade, and sessions where disableAllHooks / allowManagedHooksOnly or a disabled built-in agents-md plugin apply. In those sessions Project instructions may not appear in /config, and Claude reads CLAUDE.md only.

Fallback: always @AGENTS.md from a CLAUDE.md. No alternate flag or env var is documented. Telemetry-off setups: How do I make Claude Code load AGENTS.md when telemetry is off?.

Pitfalls

• Adding CLAUDE.local.md counts and silently stops default AGENTS load - set claude-md-and-agents-md to keep both.
• Default is or, not merge-both.
• HN thread (item 49760187) is discourse only - not product truth.
• AGENTS.local.md, AGENTS.override.md, and anything under .agents/ are not read as AGENTS instruction files.
• Expecting native AGENTS load on Bedrock/Vertex/Foundry. It isn't there yet.
• Related settings guides: readonly-git permissions, commit attribution.

FAQ

Does Claude Code support AGENTS.md?

Yes. From Claude Code 2.1.277, a project with an AGENTS.md and no CLAUDE.md loads AGENTS.md by default. Native loading is not yet available on Bedrock, Vertex or Foundry, where you import it from CLAUDE.md.

Should I use CLAUDE.md or AGENTS.md?

Keep shared instructions in AGENTS.md and add a CLAUDE.md that starts with @AGENTS.md for Claude-only notes. By default Claude Code loads one or the other, not both.

Does Claude read AGENTS.md if I already have CLAUDE.md?
Default no - CLAUDE only. Use @AGENTS.md import or Project instructions claude-md-and-agents-md.

Where do I change the setting?
/config → Project instructions, or user/managed pluginConfigs["agents-md@builtin"].options.instructionFiles. Ignored in project/local settings files.

Why isn’t AGENTS in /memory or /context?
Direct AGENTS load isn’t listed there. Look for the AGENTS.md loaded line, or ask what project instructions say.

Bedrock / Vertex / Foundry?
Native AGENTS support not available yet (CHANGELOG + docs). Import @AGENTS.md from CLAUDE.md.

Symlink or @ import?
Import preferred for Windows and clone safety. Symlink OK on Unix if you accept Edit-tool and git symlink caveats (docs).

Sources (checked 2026-09-19)

• How Claude remembers your project - AGENTS.md defaults, Project instructions values, share/migrate, unavailable sessions
• Claude Code CHANGELOG.md - 2.1.277 AGENTS.md bullet (raw fetched same-day; head 2.1.278)
• Discourse only (not product truth): HN item 49760187
• Not tested in the CLI: /config labels and the load line are quoted from the docs examples