Claude Code reads AGENTS.md now, but only when CLAUDE.md is missing
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 =…
On September 18, 2026, Claude Code introduced support for AGENTS.md, but only when CLAUDE.md is absent. This is a fallback mechanism, not a merge. If a CLAUDE.md exists in a project, Claude Code still reads it and ignores AGENTS.md. The change is limited to the "Project instructions" section in the /config directory and is currently unavailable on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. No settings.json key or environment variable controls this toggle; it is managed through the /config menu.
Claude Code concatenates discovered files without overriding them, with the closest instructions to the launch directory read last. CLAUDE.local.md is loaded after CLAUDE.md within a single directory. AGENTS.md only has an opening when there is no CLAUDE.md in the project. Keeping AGENTS.md for Codex, Cursor, or other tools requires a CLAUDE.md that imports it, using the @AGENTS.md syntax. Each import has strict rules, such as limited nesting depth and skipping certain code spans.
If no Claude-specific additions are needed, a symlink to AGENTS.md as CLAUDE.md is sufficient. Alternatively, a one-time migration using the /import command can bring an AGENTS.md configuration into Claude Code, appending it to the matching CLAUDE.md. Finally, Claude Code's behavior can be verified using /context, /memory, and /InstructionsLoaded tools.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
