Claude Code Ignored AGENTS.md Unless Telemetry Was On: How to Test Rule Loading

If your team mandates telemetry off, Claude Code may be silently skipping your AGENTS.md file. Measurements published on 2026-09-23 by an independent researcher show AGENTS.md loading gated on a remote feature flag that fails closed: when the flag cannot be fetched, the local file is never read, and nothing warns you. Every mechanistic claim in this article comes from that single post and its referenced GitHub issue #95690, not from an Anthropic changelog or statement, so treat the details as author-reported until a vendor source confirms them. The practical response does not depend on waiting: verify loading yourself, per environment, with a test that takes about five minutes.

What gates AGENTS.md: a remote flag, not a file check

Claude Code 2.1.277 announced support for AGENTS.md, the cross-vendor instruction file that teams increasingly use as a single source of agent configuration. In a project with no CLAUDE.md, Claude Code is supposed to read AGENTS.md instead. The researcher, who keeps telemetry off in their shell, found the file never loaded in their repos, and went looking for why.

Reading the 2.1.280 bundle, they report that the AGENTS.md loader ships as a built-in plugin whose availability check asks a remote feature flag called tengu_agents_md_mod, with false as the fallback. When Claude Code cannot fetch the flag, the plugin is unavailable and the local file is never read. This is a fail-closed design: the safe default for Anthropic’s rollout machinery (do not enable a feature without confirmation) becomes an unsafe default for the user (silently lose your project instructions).

That inversion deserves a moment. Feature flags normally gate behavior the user has not asked for. Here the flag gates a file the user deliberately wrote and committed. The plugin’s own description string, as quoted in the post, covers the happy path, “AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; …” The post truncates the quote there, and the visible portion says nothing about what happens when the flag cannot be fetched. As we’ve noted in our coverage of committed instruction files, a committed config file is an auditable artifact, but only if the agent actually reads it.

The telemetry coupling, measured

The researcher tested the environments where the flag fetch fails. Per their canary measurements, setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 blocks loading, and DISABLE_TELEMETRY=1 blocks it too. With either variable set, AGENTS.md never loaded; both variables had to be cleared before it did.

Two traps make this worse than a simple on/off:

• Setting a variable to 0 does not help. According to the post, Claude Code’s environment-variable semantics count any value as set. DISABLE_TELEMETRY=0 still counts as telemetry disabled for this purpose. You must unset the variables entirely.
• Project-level settings do not reach the check. An env block in .claude/settings.json clearing both variables had no effect in the researcher’s tests. A session-level --settings override worked, but only from the second session onward, because of the flag-fetch timing described below.

The failure mode is silence. In the researcher’s words, “None of these cases print a warning. The session starts, the model answers without the project instructions, and nothing tells you that a file was skipped.” That is the property that turns a configuration quirk into an operational risk. Teams that mandate telemetry off for privacy or compliance reasons are exactly the teams most likely to have written careful AGENTS.md governance rules, and they were, per this report, running without them.

Bedrock, Vertex, and gateway deployments get hit twice

As relayed in the post, issue #95690 points out a second exposed population: third-party gateways, Amazon Bedrock, and Google Vertex have the same problem, because the flag cannot resolve to true there either. This claim is medium-confidence: it comes from the issue as relayed by the researcher, not from Anthropic documentation or a changelog, and the affected-version range beyond 2.1.277 through 2.1.280 is unverified.

The inference is straightforward, though. Enterprise deployments route through Bedrock, Vertex, or a gateway precisely to control data flow, and those same deployments are the most likely to disable nonessential traffic. If the flag infrastructure is unreachable in those configurations, then the enterprise segment, the one that most needs instruction files to enforce coding standards, is the segment where the file never loads. That is a bounded inference from the reported mechanism, not a measurement; no public test of a live Bedrock deployment accompanies the report.

The canary test: one word, two sessions

The post supplies a reproducible verification method, and it is worth stating exactly because the timing detail invalidates naive versions of the test.

1. Create an empty directory containing only an AGENTS.md with a unique canary word in it.
2. In a fresh session, run claude -p and ask for the word.
3. Repeat in a second session. The first session in a new configuration only fetches the flag; the second one uses the cached result. A single-session test can therefore mislead in either direction.

Each configuration you care about gets this treatment independently: telemetry on, telemetry off, nonessential traffic disabled, your CI runner’s environment, and each Bedrock, Vertex, or gateway setup. The test proves the file’s content reached the prompt. It does not prove the model follows the instructions, which is a separate question entirely.

This pattern generalizes beyond Claude Code. “Supported” and “always loaded” are different claims whenever a feature flag, a privacy setting, or a network policy sits between the loader and the file, and the only way to distinguish them is a probe whose success is observable. The same skepticism applies when comparing agent stacks: as our harness-versus-scaffold analysis argued, the layer that owns a behavior determines where its failures surface, and a loading failure surfaces nowhere at all unless you test for it.

What Codex CLI and OpenCode actually read

Teams standardizing on AGENTS.md assume one file governs every agent. The evidence supports a narrower claim.

Codex CLI is OpenAI’s locally run terminal coding agent, installable via npm or Homebrew. According to the researcher’s post, Codex reads a global ~/.codex/AGENTS.md, and reads skills from .agents/skills in the project and ~/.agents/skills in the home directory. Claude Code, by contrast, looks for AGENTS.md and .claude/AGENTS.md in project directories only, with no user-level file, and learns the shared skills paths only via /import, which copies content into .claude/skills rather than referencing it. Copies drift; the author’s workaround is symlinking .claude/skills to the shared directory.

An important provenance note: those Codex loading details come from the same researcher’s post, not from Codex documentation. The Codex CLI documentation frames repeatable instructions as skills and plugins, and covers non-interactive codex exec runs for CI, but the page does not document AGENTS.md loading order. OpenCode, the open-source comparison point, ships two built-in agents with different permission levels (build with full access, plan read-only) and a documented per-agent configuration surface; the linked repository page does not mention AGENTS.md.

The honest summary: cross-agent loading order is, at time of writing, sourced to one researcher’s measurements, not vendor documentation. That is not a reason to dismiss it; it is a reason to run the canary test against each agent you deploy rather than inheriting confidence from the file format’s name.

The fallback: @AGENTS.md in CLAUDE.md

The post identifies a workaround that bypasses the gate entirely. CLAUDE.md supports @path imports, and those imports do not depend on the feature flag. A one-line CLAUDE.md containing @AGENTS.md, placed next to the real file, loads it with telemetry off.

This keeps AGENTS.md as the single canonical file (the same report shows Codex reading a global ~/.codex/AGENTS.md directly) while giving Claude Code a flag-independent path to the same content. Two caveats. First, prefer the @ import over /import, since /import copies and copies drift. Second, this is a researcher-supplied workaround, not an Anthropic patch; we could locate no vendor confirmation, as of 2026-09-25, that Anthropic will decouple AGENTS.md loading from the flag.

A loaded file is not automatically a helpful file

Verification effort assumes loading matters. A recent study quantifies how much, and in which direction. The MSR ‘26 Instructions-as-Code paper examined agentic pull requests before and after projects added instruction files. With all instruction files in place, the paper reports that 31.93% of projects improved their merge rate by at least 20%, and 27.73% saw merge-rate decreases of the same size. It also reports that 13.13% and 15.15% showed statistically significant increases in time-to-merge and review discussion respectively. Named examples swing both ways: the paper reports NethermindEth/nethermind rose from 20% to 69.23% (+246.15%) after adding two instruction files; the same paper records theopenco/llmgateway falling from 89% to 66.66%.

These are before/after project-level associations, not causal effects, and they sit alongside earlier benchmark work whose findings on whether context files help coding agents are mixed. The combined picture reshapes what the telemetry bug means. A silently dropped instruction file is not a silent catastrophe in every repo; for roughly a quarter of projects in the MSR data, dropping the file might coincide with better merge outcomes. What the silent failure removes is not a guaranteed benefit but your ability to know which side of that distribution your repo is on. If the file loads conditionally and invisibly, no A/B observation of agent behavior can be trusted, because the treatment itself is uncontrolled.

A rule-file verification checklist

The defensible posture until Anthropic clarifies or fixes the gating:

The broader habit this builds is the durable one: loading is an empirical property of a specific agent, version, and environment, not a property of the file format. Platform teams that assumed “one file governs all agents” now own a small, recurring verification job.

Still unverified

Everything specific about the gate, the flag name, the env-var semantics, the settings-override timing, and the workaround traces to one researcher’s reverse-engineering and measurements, corroborated only by a GitHub issue, not by vendor documentation. We found no Anthropic changelog entry, statement, or confirmed fix. Whether the behavior persists in versions after 2.1.280 is unknown, and so is whether the report has been independently reproduced. Check the Claude Code changelog before treating this as current; the mechanism could change with a single release, while the verification checklist remains useful regardless.

Frequently Asked Questions

How do I test if Claude Code is actually loading my AGENTS.md file?

1. Create an empty directory containing only an AGENTS.md with a unique canary word in it.
2. In a fresh session, run claude -p and ask for the word.
3. Repeat in a second session. The first session in a new configuration only fetches the flag; the second one uses the cached result. A single-session test can therefore mislead in either direction.

Does setting DISABLE_TELEMETRY=0 re-enable AGENTS.md loading?

According to the post, Claude Code’s environment-variable semantics count any value as set. DISABLE_TELEMETRY=0 still counts as telemetry disabled for this purpose. You must unset the variables entirely.

Is there a workaround to load AGENTS.md without relying on the feature flag?

The post identifies a workaround that bypasses the gate entirely. CLAUDE.md supports @path imports, and those imports do not depend on the feature flag. A one-line CLAUDE.md containing @AGENTS.md, placed next to the real file, loads it with telemetry off.