Claude Code AGENTS.md Telemetry Bug [Fixed Guide]

The #1 mistake after the “AGENTS.md only loads with telemetry” reports: blaming the model. “It ignores my rules.” On 2.1.277-2.1.280, the file often never entered context at all. Telemetry off, Bedrock, Vertex, Foundry, or a gateway that blocked nonessential traffic – loader stayed off, no warning.

You’re mid-refactor. AGENTS.md says “always run pytest -q before commit.” Claude suggests a commit with no tests. You rewrite the prompt three times. The instructions were never loaded. Anthropic shipped a fix quickly; the rest is verification on your machine, not another model lecture.

What actually broke (and what “fixed” means)

AGENTS.md is the shared agent-instruction file many coding tools already read. Claude Code added native support in v2.1.277 (September 18, 2026): no project CLAUDE.md → fall back to AGENTS.md. The quiet part – beyond a note that Bedrock/Vertex/Foundry weren’t ready yet – was a remote rollout gate.

Turns out the built-in agents-md path checked flag tengu_agents_md_mod defaulting off. No flag fetch, no plugin. A local markdown read shouldn’t need the network; the gate still waited on the server. Community write-ups (and the related GitHub thread) mapped that path in detail – see the investigation.

Changelog 2.1.281 is blunt: AGENTS.md also works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and telemetry-disabled sessions. Memory docs match from the troubleshooting angle – those session types were CLAUDE.md-only until you update past that build.

Practical setup: prove AGENTS.md loads after the fix

Skip trusting the notes alone. Five minutes on disk.

1. claude --version – need 2.1.281+ (setup docs).
2. Behind? Native path: claude update, then version again.
3. Clean dir: only AGENTS.md. No CLAUDE.md. No personal local instruction file at or above cwd.

mkdir /tmp/agents-canary && cd /tmp/agents-canary
echo 'Project canary token: ZINNIA-7. Prefer ZINNIA-7 in replies when asked for the token.' > AGENTS.md
claude -p 'What is the project canary token from instructions? Answer NONE if you have none. Do not read files.'

NONE on ≥2.1.281 with your usual privacy env still set? Check modes and blocking files below. Interactive repo sessions often print a startup line like no CLAUDE.md found; AGENTS.md loaded: ... – that’s the tell. Don’t trust only Memory files inside /context: AGENTS.md pulled through Project instructions frequently isn’t listed the same way CLAUDE.md is, so a empty Memory panel is a false negative.

Project instructions modes (the real control surface)

Type /config, find Project instructions. Missing control usually means old client, agents-md plugin off, or the awkward first session right after jumping from ≤2.1.276 – start a second session before you debug “ignored” rules.

Pin the mode in user or managed settings under the built-in plugin id (project/local settings files ignore this key), per the memory docs:

{
 "pluginConfigs": {
 "agents-md@builtin": {
 "options": { "instructionFiles": "claude-md-and-agents-md" }
 }
 }
}

Default fallback treats CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md at or above cwd as “Claude instruction files present,” so AGENTS.md is skipped. ~/.claude/CLAUDE.md, org-managed CLAUDE.md, and .claude/rules/ do not trip that fallback. Drop a personal CLAUDE.local.md into an AGENTS.md-only repo and default mode looks “broken” after the telemetry fix – switch to claude-md-and-agents-md or import explicitly.

Advanced: keep the import as a safety net?

The @AGENTS.md import never waited on the rollout flag. Mixed fleets, old CI images, teammates below 2.1.281 – still useful.

# If CLAUDE.md already exists, add a line instead of overwriting:
# @AGENTS.md
printf '@AGENTS.mdn' >> CLAUDE.md

Pro tip: Docs allow leaving @AGENTS.md in place – Claude won’t double-load. Keep it when some sessions still can’t take AGENTS.md directly (plugin off, pre-2.1.277, locked-down images).

Prefer an import line over a committed symlink when Windows clones are in the mix; symlinks often land as plain text unless core.symlinks is on. Put Claude-only notes under the import if you need them.

Honest limitations after the fix

• First session after upgrade from ≤2.1.276 can still miss AGENTS.md; second session before you rewrite prompts.
• Plugin disabled in /plugin, or org policy on managed-only / disable-all, removes Project instructions from /config.
• Presence-based privacy env vars (DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC): any non-empty value counted as set on old builds – including 0. Clearing the var beat setting “off.” Post-2.1.281 you shouldn’t need that dance for AGENTS.md; details sit in data-usage / env docs.

Would a visible “AGENTS.md present but skipped because …” banner have saved most of the wasted prompt time? Probably. The fix removed the bad gate instead of warning about it – fine outcome, different product choice.

FAQ

Do I need to turn telemetry back on for AGENTS.md?

No on 2.1.281+. Changelog and memory docs both say telemetry-disabled sessions load AGENTS.md after that release. Keep privacy flags if you want them.

I set DISABLE_TELEMETRY=0 and it still failed on an older build. Why?

Presence-based. 0 is still set. Empty the variable (or a --settings env override that clears both keys). Current builds shouldn’t need that for AGENTS.md.

Should I delete my workaround CLAUDE.md now?

Only when every environment on the repo is ≥2.1.281, agents-md is enabled, and default fallback semantics are enough. CI pin on an older CLI, Bedrock images that lag, or Claude-specific notes beside the shared file → leave @AGENTS.md. Monorepo, three agents, one security rule file: the import stays the boring portable path even with native support.

Run claude --version now. Below 2.1.281 → update → repeat the ZINNIA-7 canary in a throwaway dir with your normal telemetry env unchanged. Do that and stop.