Build1 publisher2 min readPublished
A single CLAUDE.md anywhere up the tree cancels Claude Code's new AGENTS.md support
Claude Code started reading AGENTS.md on September 18, but only where no CLAUDE.md sits in the working directory or any parent above it. Monorepos need a stub file per package or a change to the instructionFiles setting.
The Engineer · Build desk
What happened
- Claude Code began reading AGENTS.md natively on September 18, the open cross-tool instruction file other coding agents already read, according to a dev.to breakdown of the release.
- The default is a fallback and not a merge: the CLI reads AGENTS.md only where no CLAUDE.md exists in the working directory or any parent, and otherwise ignores AGENTS.md entirely.
- AGENTS.md is plain Markdown read by more than twenty coding tools, including Codex, Cursor, Gemini CLI and Copilot.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- decision A team that standardised on AGENTS.md now has to decide what to do with its root CLAUDE.md: delete it, reduce it to a one-line import, or change the instructionFiles setting.
- constraint Per-package instructions in a monorepo cannot live in AGENTS.md alone while a CLAUDE.md sits above them, so each package that wants its own rules needs a Claude-specific file of its own.
- exposure In repos where both files exist, Claude Code keeps acting on the CLAUDE.md while every other agent on the team reads the updated AGENTS.md, and nothing in the session flags the divergence.
- cost Teams running Claude Code through Bedrock, Vertex or Foundry keep paying for their own sync, whether that is a symlink, a hook or hand-editing, until support arrives there.
The check walks upward. Claude Code looks in the working directory and then every parent above it, so a CLAUDE.md three levels up outranks an AGENTS.md sitting in the package you are editing [2][8]. The dev.to write-up describes the check as happening per lookup, with a closer or higher CLAUDE.md winning [8].
The changelog entry is short. It says: "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)" [4]. The feature ships as a built-in plugin, which is why the precedence is configurable at all [7].
Monorepos get the least out of the default. A nested AGENTS.md in apps/api/ is not read automatically while any CLAUDE.md exists above it, including at the repo root [8]. The documented workaround is a small CLAUDE.md beside each nested AGENTS.md that imports it with @AGENTS.md [9]. That is one Claude-specific file per package, the same count as the symlink-per-package setup it replaces, with a one-line import where the symlink used to be [15]. The other option is setting instructionFiles to claude-md-and-agents-md, which loads both files everywhere [10]. In my view that is the safer setting for a repo that already has both files, because a contradiction between two loaded files shows up in the output and an ignored file does not.
The friction it removes was real. Before native support, teams symlinked CLAUDE.md to AGENTS.md, wrote pre-commit hooks or Makefile targets that concatenated one into the other, or installed wrapper skills whose entire job was to find AGENTS.md, read it and inject it into context [12]. That is a plugin to open a file. Most teams maintained both by hand, and the write-up gives the drift case: someone updates the build command in AGENTS.md for the Cursor and Aider users, forgets CLAUDE.md, and Claude Code runs stale instructions until somebody notices [13].
The advice to drop the symlink holds for one shape of repo, a single instruction file at the root with no CLAUDE.md elsewhere in the tree [11]. AGENTS.md is read by more than twenty coding tools, among them Codex, Cursor, Gemini CLI and Copilot [6]. That count only helps where each of those tools looks at the path your repo actually uses, root or nested subdirectory [5]. The changelog says support has not reached Bedrock, Vertex or Foundry [14], so teams running Claude Code through those keep whatever sync they already built.
What to watch
- Whether Anthropic extends AGENTS.md support to Bedrock, Vertex and Foundry, which would retire the sync workarounds for managed deployments.