Claude Code adds native AGENTS.md support, with CLAUDE.md taking precedence by default

Claude Code, Anthropic's terminal-based coding agent, now reads AGENTS.md natively. According to a write-up on dev.to, the change shipped on September 18 and quietly closes one of the last gaps in support for the cross-tool instruction standard — though the default behaviour is subtler than a simple "it works now".

What AGENTS.md is

AGENTS.md is an open, tool-agnostic Markdown file that serves as a manual for AI coding agents: it records how to build and test the project, which style rules apply, which directories are off limits, and how deploys are done. It sits at the repository root, or nested inside subdirectories for monorepos, and per dev.to it is already read by more than twenty tools including Codex, Cursor, Gemini CLI and Copilot. The pitch is to replace a stack of vendor-specific instruction files — CLAUDE.md, .cursorrules, .github/copilot-instructions.md — with one plain document every agent can consume, with no proprietary schema or special syntax.

Until now, Claude Code users who wanted that arrangement had to bridge the gap themselves. The dev.to article catalogues the common hacks: symlinking CLAUDE.md to AGENTS.md (which broke on some filesystems and checkouts), running scripts that concatenated one file into the other on save, installing community plugins whose only job was to inject the file into context, or maintaining two files by hand and hoping they never drifted apart.

A fallback, not a merge

The key detail of the new support is that it works as a fallback rather than a merge. Claude Code checks the working directory and every parent directory above it; if a CLAUDE.md exists anywhere in that chain, AGENTS.md is ignored entirely. Only when no CLAUDE.md is in scope does Claude Code read AGENTS.md instead. The feature is implemented as a built-in plugin, which is why the behaviour is configurable rather than hardcoded.

Users can change it under "Project instructions" in the /config menu, where four modes exist:

• claude-md-or-agents-md (the default): read CLAUDE.md if one exists anywhere above the working directory, otherwise fall back to AGENTS.md.
• claude-md-and-agents-md: load both files, with CLAUDE.md taking precedence where instructions overlap.
• claude-md: ignore AGENTS.md completely, matching the behaviour from before version 2.1.277.
• managed-only: drop checked-in and private instruction files in favour of organisation-managed configuration, aimed at enterprise compliance setups.

Monorepos and rough edges

Single-repository setups that were only symlinking CLAUDE.md to AGENTS.md can drop the symlink under the default mode. Monorepos are not so lucky. A nested AGENTS.md inside, say, apps/api/ is not picked up if any CLAUDE.md exists higher in the tree, because the fallback check runs per lookup and the higher file wins. The documented pattern for that case, per dev.to, is a small CLAUDE.md placed next to the nested AGENTS.md that imports it with an @AGENTS.md reference, or switching to the claude-md-and-agents-md mode so both files load everywhere.

Other limitations are worth checking before assuming full parity with CLAUDE.md. Support is not yet available on Bedrock, Vertex or Foundry deployments. Nested AGENTS.md files attach on file reads but are not restored after context compaction, they do not appear in /memory, and directories added with --add-dir do not contribute their AGENTS.md at all.

Why it matters

For a team running a single agent, little changes. The value shows up the moment several agents share one repository — Claude Code for one class of task, a Cursor or Codex agent for another, plus a CI-triggered reviewer — which the dev.to article argues is increasingly the norm. A repository shipped with only an AGENTS.md at the root is now read identically by Claude Code, Cursor, Codex and Copilot with zero configuration.

The decision that remains belongs mostly to existing Claude Code users. Because most already have a CLAUDE.md, the default means Claude Code keeps reading that file while every other tool reads AGENTS.md, and the two must be kept in sync on purpose. The recommended approach in the dev.to write-up is to treat AGENTS.md as the cross-tool baseline everyone gets, and reserve CLAUDE.md for Claude-specific extras such as hook configuration and permission modes, layered on top via claude-md-and-agents-md or an explicit import. Made once and deliberately, that choice stops "which instruction file does this tool actually read" from being a recurring question.