Claude Code shipped AGENTS.md support on September 18, 2026. The changelog line for 2.1.277 is one sentence, and every word in it matters:

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)

// Detect dark theme var iframe = document.getElementById('tweet-2101023103962718457-239'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2101023103962718457&theme=dark" }

Read that again: in a project with no CLAUDE.md. This is a fallback, not a merge. If your repo already has a CLAUDE.md, nothing changed for you. Claude Code keeps reading CLAUDE.md and keeps ignoring AGENTS.md, exactly as before.

What 2.1.277 actually changed

Three things, and only three.

  1. When Claude Code finds no CLAUDE.md, it reads AGENTS.md instead of loading nothing.
  2. The behavior is togglable under Project instructions in /config.
  3. It is not available yet on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

There is no documented settings.json key and no environment variable for the toggle. The only documented surface is the /config menu. If you deploy Claude Code through managed settings, that matters: you cannot pin this behavior across a fleet today.

One more thing worth knowing before you build on it. The memory documentation page has not caught up. At the time of writing it still says, in plain text, that Claude Code reads CLAUDE.md and not AGENTS.md. The changelog is ahead of the docs here, so trust the release notes and verify in your own session.

The fallback almost never fires in a real repo

Claude Code does not look for one instructions file. It walks a tree.

/ <- managed policy CLAUDE.md ~/.claude/CLAUDE.md <- user instructions, every project repo/ CLAUDE.md <- project instructions (or .claude/CLAUDE.md) CLAUDE.local.md <- your gitignored personal layer services/api/ CLAUDE.md <- loads on demand, when Claude reads files here

At launch, Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it. Files in subdirectories are not loaded at launch; they are pulled in when Claude reads files in those subdirectories.

Everything discovered is concatenated, not overridden. Order runs from the filesystem root down to your working directory, so the instructions closest to where you launched Claude are read last. Inside a single directory, CLAUDE.local.md is appended after CLAUDE.md.

Now put the AGENTS.md fallback next to that. It only has an opening when there is no CLAUDE.md at all in the project. In a repo that has been through /init even once, that opening does not exist. Which is why, for most teams, the two older mechanisms are still the ones doing the work.

The import still beats the fallback

If you keep AGENTS.md for Codex, Cursor, or anything else, the documented way to share it is a CLAUDE.md that imports it:

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

Claude loads the imported file at session start, then appends whatever you wrote below it. You get one source of truth plus a Claude-specific section, and you are not relying on a fallback that disappears the moment someone commits a CLAUDE.md.

The import rules are strict, and they bite:

  • Syntax is @path/to/import. Relative paths resolve against the file containing the import, not your working directory.
  • Imports nest to a maximum depth of four hops.
  • Import parsing skips Markdown code spans and fenced code blocks. Wrapping @README in backticks keeps it literal; outside backticks it imports the file.
  • An import in a project file that resolves outside the working directory is external. The first time Claude Code sees one, it shows an approval dialog. Decline once and those imports stay off, with no second prompt.
  • Imports in user-scope files such as ~/.claude/CLAUDE.md load without that dialog, because you wrote them.

That last pair is the one that surprises people on a shared repo: your teammate approved the external import, you declined it, and now the two of you are running different instructions.

The symlink, and the one-time copy

If you need no Claude-specific additions at all, a symlink is enough:

ln -s AGENTS.md CLAUDE.md

It prints nothing on success. On Windows this needs Administrator privileges or Developer Mode, so use the @AGENTS.md import there instead.

The third option is a one-time migration rather than a live link. /import brings a supported coding agent configuration into Claude Code: it appends a copy of instruction files such as AGENTS.md to the matching CLAUDE.md, and carries over MCP servers, commands, subagents, and skills. It requires Claude Code v2.1.213 or later. Use it when you are leaving the other tool, not when you are running both.

Related, and easy to miss: /init reads Cursor rules and Copilot rules by default. Set CLAUDE_CODE_NEW_INIT=1 and it also reads AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules.

Check what actually loaded

Every mechanism above is invisible until you verify it. Three tools, in order of effort:

/context -> "Memory files" section lists what loaded this session /memory -> browse and open every CLAUDE.md and memory file hook -> InstructionsLoaded logs which files loaded, when, and why

/context is the fast check. If your file is not under Memory files, Claude cannot see it, and no amount of rewording the instructions will help. The InstructionsLoaded hook is the one to reach for when a path-scoped rule or a lazily loaded subdirectory file is the suspect.

Two limits that quietly change behavior while you debug: Claude Code loads a CLAUDE.md up to 4 MiB in full and skips a larger file entirely, and adherence drops well before that, which is why the docs target under 200 lines per file. In a monorepo, claudeMdExcludes skips ancestor files by glob against absolute paths, at any settings layer, with arrays merging across layers. A managed policy CLAUDE.md cannot be excluded.

Do this, in this order

  1. Run claude --version. The fallback needs 2.1.277 or later, and it is not on Bedrock, Vertex, or Foundry.
  2. Check whether the repo has a CLAUDE.md. If it does, the new fallback will never fire, and steps 3 and 4 are your real options.
  3. Keep AGENTS.md as the source of truth and add a CLAUDE.md containing @AGENTS.md plus any Claude-specific section.
  4. If you need nothing Claude-specific, use ln -s AGENTS.md CLAUDE.md instead, unless you are on Windows without Developer Mode.
  5. Start a session and run /context. Confirm the file appears under Memory files.
  6. Open /config, find Project instructions, and set the AGENTS.md behavior you want before someone else on the team sets a different one.

You can follow me on my social media: