Claude Code Ignoring AGENTS.md? The Real Fix

Claude Code added AGENTS.md support on September 18, 2026, in version 2.1.277. Many developers read that changelog line, updated, and assumed their existing AGENTS.md file would now load alongside CLAUDE.md. For most repos, it doesn't. The tool gives no warning that AGENTS.md is still being ignored. This explainer was checked line-by-line against Anthropic's own release notes and the engineer's public announcement before publishing, the same fact-check standard applied to every post in our software coverage.

What Claude Code 2.1.277 Actually Changed

Claude Code is Anthropic's terminal-based coding agent, and AGENTS.md is a cross-tool spec for project instructions that Codex, Cursor, and other agents already read the same way. CLAUDE.md is Claude Code's own, older instructions file, and for most existing repos it's the one still in charge.

Claude Code 2.1.277 made AGENTS.md a fallback source of project instructions. It did not make it an additional one. The rule is confirmed by Anthropic engineer Thariq Shihipar in his public announcement and documented in Anthropic's own release notes. If any CLAUDE.md file exists at or above the working directory, Claude Code loads that file and nothing else. AGENTS.md is never read in that case. Only when no CLAUDE.md exists anywhere in the directory chain does Claude Code check for AGENTS.md and use it instead (Claude Code v2.1.277 release notes).

That single word — "instead," not "also" — is the real story here. AGENTS.md is a cross-tool spec that Codex, Cursor, and other coding agents already read. Anthropic's implementation treats it as a substitute file for projects with no CLAUDE.md. It is not a second file Claude Code merges in.

Why Your AGENTS.md Is Still Being Ignored

Claude Code is ignoring your AGENTS.md because your project already has a CLAUDE.md. The default setting only reads one file or the other, never both. This is the exact scenario most existing repositories hit. A team adopted AGENTS.md for cross-tool compatibility. It kept CLAUDE.md around for Claude-specific instructions. That team now assumes 2.1.277 merges the two files. By default, it doesn't.

/config exposes a setting called Project instructions with four values, laid out in detail in this precedence breakdown and in Anthropic's supported-backend notes:

Setting	Behavior
claude-md-or-agents-md	Default. CLAUDE.md if present, otherwise AGENTS.md. Never both.
claude-md-and-agents-md	Reads both files, with CLAUDE.md's content taking precedence on conflicts.
claude-md	Ignores AGENTS.md entirely, even with no CLAUDE.md present.
managed-only	Only enterprise-managed instruction files load; both project files are ignored.

If your /config still shows claude-md-or-agents-md and your repo has both files, Claude Code has been silently running on CLAUDE.md alone since you updated.

Unique insight: The two "both" options in that table are not equivalent for a team migrating toward AGENTS.md. Consider a monorepo with per-package AGENTS.md files and one shared CLAUDE.md at the root. The claude-md-and-agents-md setting merges that root CLAUDE.md into every package, which is useful. But it also means a package-level AGENTS.md can never override a root-level rule — it can only add to it. For example, a package trying to loosen a root restriction needs the @AGENTS.md import approach instead, placed inside that package's own CLAUDE.md, so the package's file is what Claude Code loads first.

The One-Line Fix

The fix that keeps both files working for every tool, not just Claude Code, is a one-line import. It is not a symlink. Anthropic's own guidance and third-party writeups agree on this point. Create or edit CLAUDE.md so its first line reads:

@AGENTS.md

Claude Code's @-import syntax pulls the full contents of AGENTS.md into the effective CLAUDE.md context. It then appends anything else written below that line. Other tools that read AGENTS.md directly, like Codex and Cursor, are unaffected. They never look at CLAUDE.md in the first place. A symlink from CLAUDE.md to AGENTS.md looks like it should work the same way, but the documented fix calls that approach wrong. Claude Code resolves the symlink and treats the result as a real CLAUDE.md file. That can trigger duplicate-instruction warnings in some setups (Fix: Claude Code ignores AGENTS.md).

The alternative fix, if you'd rather not touch either file, is switching /config to claude-md-and-agents-md. That reads both files on every session without editing either one. The cost is that it's a per-developer setting, not something committed to the repo.

Which Fix to Use, and When

Use the @AGENTS.md import when you want the fix committed to the repository. Every teammate and every CI agent then gets it automatically. Use the /config toggle when you're working solo, in someone else's repo you can't modify, or testing the merge behavior before committing to it. For a broader look at how these agent-tooling defaults keep shifting underneath teams, see our AI coverage and, for the churn among agent frameworks generally, our agent framework rankings.

Neither fix is available yet if your Claude Code deployment runs through Bedrock, Vertex, or Foundry. Anthropic's release notes list AGENTS.md support as unavailable on those three backends as of 2.1.277. Teams on managed cloud deployments stay CLAUDE.md-only regardless of the /config value, until Anthropic extends support.