Claude Code reads AGENTS.md only when telemetry is on [fixed]

TL;DR Highlight

With telemetry off, Claude Code silently skipped AGENTS.md because of a remote flag

Who Should Read

A developer who shares one AGENTS.md across several agents but finds Claude Code ignoring it

Core Mechanics

The AGENTS.md loader sits behind a remote flag
- The loader is a built-in plugin called agents-md, and its isOnByDefault value is false.
- It asks a remote feature flag, tengu_agents_md_mod, whether it is available and falls back to false if it cannot fetch it.
With telemetry off, it skips silently
- Setting either DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 kept AGENTS.md from loading.
- There is no warning, so it looks as if the model ignores your instructions.
Setting the variables to 0 does not help
- Any value counts as set, so 0 keeps the block in place.
- Clearing them in the project's .claude/settings.json env had no effect.
A --settings override works from the second session
- The first session only fetches the flag, and the second one uses it.
- The issue says Bedrock, Vertex and third-party gateways have the same problem because the flag cannot resolve to true.

Community Reactions

Anthropic's reply: a rollout artifact, fixed in v2.1.281
- A commenter explained they needed a remote kill-switch, and with telemetry off you don't receive flags.
- They said it was fixed in v2.1.281 releasing that day and apologized for a human error.
Experience: AGENTS.md is skipped by default when CLAUDE.md exists
- One comment says even a ~/CLAUDE.md prevents any AGENTS.md from being read.
- To read both, switch the Project instructions setting to claude-md-and-agents-md.
Many commenters say existing workarounds work fine
- One comment uses ln -s AGENTS.md CLAUDE.MD in new projects.
- Another keeps a CLAUDE.md that references @AGENTS.md and says it still works.
Counterpoint: feature flags are normal practice
- One view is that separating deployment from activation is a standard distributed-systems approach.
- Others still criticized the failure to decouple flags from telemetry and the lack of any warning.

How to Apply

Run the canary test in an empty folder
- Create an empty directory with an AGENTS.md containing a canary word and ask for it with claude -p.
- Run it twice in a shell with telemetry off and check the second session.
Add a one-line CLAUDE.md to repos that use AGENTS.md
- Run echo '@AGENTS.md' > CLAUDE.md at each repo root and commit it.
- This matters most for teams that block nonessential traffic via telemetry or gateway policy.
Link shared skills with a symlink
- Keep skills in .agents/skills and link .claude/skills to ../.agents/skills.
- Use the link instead of /import copies, which drift from the source.
Upgrade to v2.1.281 or later and re-verify
- After updating, rerun the canary test with telemetry off.
- Even if it passes, remember AGENTS.md is skipped by default when a CLAUDE.md exists.

Try It

copy & run

# Paste into your shell (bash/zsh): check whether AGENTS.md loads with telemetry off

mkdir /tmp/canary && cd /tmp/canary
echo 'The canary word is PERIWINKLE.' > AGENTS.md
export DISABLE_TELEMETRY=1

# Run twice. The first session only fetches the flag; the second uses it
for i in 1 2; do
  claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'
done

# If you get NONE, work around it: import via CLAUDE.md
echo '@AGENTS.md' > CLAUDE.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'

# Next to try: share skills
# ln -s ../.agents/skills .claude/skills

Terminology

feature flagA server-side switch that turns an already-deployed feature on or off. It is like installing a light and flipping it on from a central panel.

telemetryUsage and diagnostic data a tool sends back to its vendor. Think of a car's remote diagnostics.

canary wordAn arbitrary word placed in an instruction file to check whether it was loaded. If the model repeats it, the file was read.

@path importSyntax in CLAUDE.md that pulls in another file's contents with @filename. It works like an include in code.

AGENTS.mdA project instruction file shared by multiple coding agents. Think of it as a README for agents.