Claude Code 2.1.277 added support for AGENTS.md, the shared instruction file that other coding agents already read. In a project with no CLAUDE.md, it is supposed to read AGENTS.md instead. On the author’s machine it never did — because whether the tool reads a file sitting in his own working directory was made to depend on a call to Anthropic’s servers. The 201-comment thread on Hacker News is where an engineer from the Claude Code team turned up to explain it.

Where the gate is

  • The loader ships as a built-in plugin called agents-md. In the 2.1.280 bundle its isOnByDefault value is false, and its availability check asks a remote feature flag — a switch on the vendor’s servers that enables a feature for some users without shipping new code. The fallback when the flag cannot be fetched is “off”.
  • With the plugin unavailable, the file is never read. Reading a markdown file from your own folder needs no network at all; this one waits on a server-side switch anyway.
  • He tested with a canary word: an empty directory holding only an AGENTS.md with a made-up marker word in it, then asking claude -p for the word. A canary works because it is a string the model could only produce if the file actually reached it.

What he measured

  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 blocks the feature. That is the variable teams set when they want the tool to stop phoning home.
  • DISABLE_TELEMETRY=1 blocks it too. Both had to be cleared before the file loaded.
  • Setting either variable to 0 does not help — any value counts as “set”. Easy to miss when you are trying to turn a feature back on.
  • Clearing the variables in the project’s own .claude/settings.json has no effect. There is no way to enable it for a single repo.
  • A per-session override on the command line does work, but only from the second session on: the first one just fetches the flag.
  • Nothing prints a warning. The session starts, the model answers without the project instructions, and nobody is told a file was skipped.
  • Third-party gateways, Bedrock and Vertex hit the same wall — the flag cannot resolve to true there either.

The workaround

One extra file: echo '@AGENTS.md' > CLAUDE.md next to it. CLAUDE.md supports @path imports and those do not consult the flag. The cost is exactly what AGENTS.md support was supposed to remove — one more file per repo.

Why he calls it unacceptable

Turning telemetry off should cost you diagnostics, not a feature that reads a file on your own disk. The gate also lands hardest on the people most likely to keep a shared instruction file: teams running through a gateway, Bedrock or Vertex often disable nonessential traffic by policy, so they get a feature announced as available that silently does nothing.

Silence is the worst part. Most people will not run a canary test and a string search through the binary; they will conclude the model ignores their instructions, and rewrite prompts for a file that never reached the model.

What he wants instead:

  • Reading a local file should not depend on telemetry — or, failing that, a startup warning when an AGENTS.md is present and skipped.
  • A user-level AGENTS.md. Claude Code looks in project directories only; Codex reads ~/.codex/AGENTS.md, and Claude Code’s /import copies that once without following later edits.
  • Native support for shared agent skills. Codex reads .agents/skills and ~/.agents/skills; Claude Code 2.1.280 only understands those paths inside /import, which copies. He symlinks .claude/skills to ../.agents/skills instead.

What the thread adds

  • mpoteat — self-identified on the Claude Code team, in the thread: “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.” He calls it “a fully human error on my part - I should’ve found a better way to launch with a kill-switch”, and links the plugin source in the public repo. His follow-up adds that AGENTS.md support runs on a new extensibility system (“Mods”) that is itself not generally available yet.
  • arrowsmith — a second gate the article never mentions, and one that survives the fix: AGENTS.md is only read when there is no CLAUDE.md at all, so a ~/CLAUDE.md suppresses a project’s AGENTS.md. The ‘Project instructions’ setting has to be switched to claude-md-and-agents-md to load both.
  • nijave — corroboration with a longer timeline: with telemetry off, new feature rollouts “basically” stopped working for months, until flags get “promoted” and defaulted on. Their own read is that the title oversells it.
  • msp26 — a second feature in the same bucket: Claude Code Remote control also only works with telemetry enabled. The author replies that this is why he runs VPN → SSH → mosh → tmux → claude/codex instead.
  • p5v and MPSimmons — the workaround predates the bug. A hand-written CLAUDE.md pointing at @AGENTS.md has long been their standard setup (“Still works fine”); scottyah suggests a symlink instead.
  • vorticalbox — the multi-agent version of the same problem: symlinking Cursor and Claude skill folders to one ~/.agents/skills works, except Claude’s own .skills/synced folder ends up duplicating skills.
  • dotancohen, taking the engineer’s explanation one step further: “So what Anthropic calls ’telemetry’ is really ’telechangeability’?” — which sits worse with them than a feature that needs telemetry outright.

Where the thread pushes back

  • The strongest objection is not about the bug but the premise. shermantanktop argues a launch flag is ordinary distributed-systems practice — separate deploying a feature from triggering it — and stravant calls the thread’s size “[e]mbarrassing for HN to have a huge thread over a Feature Flag”, linking Martin Fowler’s feature-toggles piece. HotHotLava puts the scale of the impact plainly: users with telemetry off “got this feature ~2 days later, when the bug was noticed.”
  • sandrello reads it as a symptom of AI-written patches accumulating in the product — “the kind of subtle but extremely severe bug that sneaks in when you start piling up layers of AI generated patches” — and fg137 compares it to VS Code adding Copilot as a git co-author regardless of settings. Neither is verifiable from outside, and the Claude Code engineer’s own account describes an ordinary release-engineering mistake.
  • cowpig aims at the users rather than the vendor: “The number of people raw-dogging software that executes arbitrary instructions on their machine coming from a 3rd party server just absolutely baffles me.”
  • tjoff on the writing itself: they’d “rather read the prompt that was used to write this article”, which they found about ten times longer than it needed to be.

A question the thread keeps asking

Whether any of this was intended — nfRfqX5n: “Crazy part is: can’t tell if this intended or a bug”, which the engineer’s later comment answers with “rollout artifact”. Separately, quintu5 and lucfranken ask why feature flags have to ride on telemetry at all (“I’m sure there’s no conceivable way an organization as well resourced as Anthropic can separate out feature flags from telemetry. It’s just too complicated! Maybe when we get AGI?”). The article raises that question and nobody in the thread answers it.

On reading comments as evidence: HN handles are pseudonymous, the site publishes no per-comment scores, so the ordering above is HN’s own ranking and not a vote. The claims about AI-written patches, Copilot co-authorship and the scope of the rollback come from commenters, quoted as claims. This is a slice of a 201-comment thread, not a consensus.