Claude Code Silently Skipped AGENTS.md Unless Telemetry Was On

Claude Code 2.1.277 announced support for AGENTS.md, a cross-agent instruction file standard. In a project with no CLAUDE.md, Claude Code is supposed to read AGENTS.md instead. But a developer discovered that the file was never loaded when telemetry was disabled, and no warning was printed. Anthropic acknowledged the issue and fixed it in v2.1.281, released the same day the story hit Hacker News[1].

The problem

The AGENTS.md loader ships as a built-in plugin called agents-md. Its registration in the 2.1.280 bundle shows that the plugin's default state is off, and it depends on a remote feature flag called tengu_agents_md_mod to turn on. When Claude Code cannot fetch the flag, which happens when telemetry or nonessential traffic is disabled, the plugin is unavailable and the local file is never read[1].

Reading a markdown file from the working directory needs no network at all, but the implementation waited on a server-side switch. The developer, who writes as pszypowicz, tested this with a canary word in an AGENTS.md file and confirmed that setting either CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 or DISABLE_TELEMETRY=1 blocks the feature entirely. Setting either variable to 0 does not help, despite the documentation suggesting any value counts[1].

Who it affects

The gate hits the people most likely to care about AGENTS.md. Someone who keeps one instruction file for several agents is usually careful about what each tool sends home. Teams on Bedrock, Vertex, or third-party gateways often disable nonessential traffic by policy. They all get a feature that is announced as available and then does nothing[1].

The silence is the worst part. The session starts, the model answers without the project instructions, and nothing tells you that a file was skipped. Most people will conclude that the model ignores their instructions and spend time on prompts when the file never reached the model in the first place[1].

The workaround

CLAUDE.md supports @path imports, and those do not depend on the feature flag. A one-line CLAUDE.md next to the AGENTS.md loads it even with telemetry off[1]:

echo '@AGENTS.md' > CLAUDE.md

With that file in place, the canary test returns the word with nonessential traffic still disabled. The cost is one extra file per repo, which is what the AGENTS.md support was supposed to remove[1].

Anthropic's response

An Anthropic engineer responded on Hacker News: "Sorry folks, this is a rollout artifact, we needed a way to turn this off remotely via feature flags if it broke something, and with telemetry off you don't get those. It's already been fixed as part of v2.1.281 releasing today."[2]

The engineer explained that AGENTS.md support was implemented via their new extensibility system called Mods, which is launching soon. A mod is a plugin with a new type of hook. The feature flag was a kill-switch for the rollout, but it backfired because it tied a local file read to a remote flag that cannot resolve when telemetry is off[2].

The broader question

pszypowicz argues that a privacy setting should never quietly switch off unrelated local behavior. If Anthropic wants a staged rollout, the fallback for a flag that cannot be fetched should be the documented behavior, or at least a visible message that says what was skipped and why[1].

On Hacker News, the story drew 346 points and 187 comments. Discussion covered the tension between gradual rollouts and user trust, the irony of gating a local file read behind a network call, and comparisons with Codex's approach. Codex reads a global ~/.codex/AGENTS.md without any feature flag. Claude Code has no equivalent user-level file, only project-level files that depend on the flag[2].

One commenter noted: "The only difference between CLAUDE.md and AGENTS.md is the filename. Do you really need a whole plugin system to support that use case? Feels like this could have been a one line change."[2] Another pointed out that Hyrum's Law applies: somebody, somewhere was relying on Claude ignoring AGENTS.md to give different instructions to Claude versus other agents[2].

Sources

[1] blog.szypowi.cz: "Claude Code reads AGENTS.md only when telemetry is on" (September 2026)

[2] Hacker News discussion (346 points, 187 comments)