Product1 publisher3 min readPublished
Claude Code's new AGENTS.md fallback leaves the symlink as the only audit trail
Version 2.1.277 reads a shared AGENTS.md when no CLAUDE.md is in scope. The documented exceptions cover first sessions, telemetry-disabled runs, Bedrock, Vertex and Foundry, and the hooks governance tooling watches.
The Product Desk · Product desk
What happened
- Anthropic shipped Claude Code 2.1.277 on September 18, giving the tool native support for AGENTS.md in folders where no CLAUDE.md file is present.
- Support stops at the one filename: Claude does not read AGENTS.local.md, AGENTS.override.md, or anything kept under a .agents/ directory.
- The AGENTS.md site says more than 60,000 open-source projects use the format and lists more than 30 tools that are compatible with it.
Compiled by The Product DeskSomething wrong?How this is made
Why it matters
- exposure One developer's CLAUDE.local.md counts as a CLAUDE.md, so a personal preferences file silently displaces the team's shared AGENTS.md in that checkout. The documented fix is switching the setting to claude-md-and-agents-md.
- constraint Compliance tooling that watches InstructionsLoaded sees the imported or symlinked file and nothing from the native fallback, so the duplicated setup is the only one that leaves an audit record.
- decision Every team that patched instruction sprawl with a symlink now has to decide whether to remove it, and for anyone with hooks or ephemeral CI the honest answer is to keep it.
- capability Monorepo teams can keep a per-package AGENTS.md and have Claude pick up the right one when it reads a file in that subdirectory, without seeding a CLAUDE.md into every folder.
A continuous integration job that installs Claude Code, runs one agent session and then discards the container never gets to a second session. Anthropic's documentation says the first session after an install or upgrade does not read AGENTS.md [13]. On a runner that installs per job, every session is that first session [2]. The documented workaround is to import AGENTS.md from a CLAUDE.md [13], and Claude loads the file through that import when a CLAUDE.md already does it [4]. Many teams patched the duplication with a symlink long before this shipped [19].
Thariq Shihipar of the Claude Code team announced the change this way: "We're adding support for AGENTS.md to Claude Code. Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md." [2] Claude reads AGENTS.md only when no CLAUDE.md sits in the working directory or any directory above it, and when both exist it reads CLAUDE.md and ignores AGENTS.md [3].
Two of the four values in the /config Project instructions setting read AGENTS.md at all [1]. The value claude-md ignores it, and managed-only loads only the organization's managed CLAUDE.md and auto memory [7]. A shop that has already locked its fleet to managed-only has nothing to gain from the convergence, because its agents read what the organization ships [7].
A fallback-loaded AGENTS.md also does not appear in /memory or in the memory files list in /context [14].
Ownership of the format has moved since the headlines assigned it to OpenAI. OpenAI contributed AGENTS.md to the Agentic AI Foundation, part of the Linux Foundation, when it launched in December 2025, Anthropic contributed the Model Context Protocol to the same foundation, and both are founding platinum members [16]. Mitch Ashley, vice president and practice lead for CIO and technology buyers and software lifecycle engineering at The Futurum Group, said: "For most enterprises, running several coding agents at once is now the permanent state, so convergence on one instruction format matters more than which vendor adopted it." [18]
The decision splits on two questions: whether anything other than a person reads your instruction file, and whether every environment you run in fetches feature flags from Anthropic. If a hook, a compliance check or a release gate depends on knowing which instructions loaded, keep the CLAUDE.md that imports or symlinks to AGENTS.md, since those are the paths that fire InstructionsLoaded [15]. Bedrock, Vertex and Foundry do not have the feature yet according to the changelog [11], and a session with telemetry disabled cannot read AGENTS.md [12]. Teams whose agents run in interactive terminals with telemetry on, and whose tooling ignores hooks, can drop the symlink. The rest keep the CLAUDE.md and point it at AGENTS.md.
What to watch
- Whether Anthropic enables the AGENTS.md fallback on Bedrock, Vertex and Foundry, which would close the gap for teams running agents through those platforms.
- Whether a fallback-loaded AGENTS.md starts appearing in /memory and /context and firing InstructionsLoaded, which would make the symlink redundant for governance.
- Whether support extends past the single filename to .agents/ directories, where some teams keep skills today.