Picture this. You spend an hour writing your AGENTS.md file: coding conventions, test commands, the "never touch the migration folder" rules your team agreed on. You drop it in the repo root. Your AI coding agent announces it now supports AGENTS.md natively. You close your laptop, satisfied that your agent finally speaks the same config language as every other tool.
Then a developer in Poland runs a canary test, and it turns out your file was never read at all.
That is not a hypothetical. Last week, developer Piotr Szypowicz published measurements showing that Claude Code 2.1.277, the release that announced native AGENTS.md support, only loaded the file when telemetry was switched on. With telemetry off, a local file sitting in your own working directory was silently skipped. No warning. No log line. The agent just answered your questions without your project instructions, and you had no way to know.
The bug is fixed as of version 2.1.281. But the story is worth more than a shrug, because it exposed something most of us have not admitted yet: your AI agent's config files are a trust surface, and almost nobody is verifying that their agent actually reads them.
What Actually Happened
Here is the breakdown, from the original research post and the Hacker News thread where an Anthropic engineer responded. Everything below is sourced; I have not reproduced the bug myself, so treat these as reported findings, not my own measurements.
The feature shipped as a plugin, not core code. AGENTS.md loading in Claude Code 2.1.277 was implemented as a built-in plugin called agents-md, built on Anthropic's new "Mods" extensibility system.
The plugin checked a remote feature flag. Its availability check called a remote flag named tengu_agents_md_mod, with false as the fallback. If Claude Code could not fetch the flag, the plugin registered as unavailable.
Telemetry-off setups could not fetch the flag. Two environment variables did it: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 and DISABLE_TELEMETRY=1. Either one blocked the flag fetch, so the plugin never activated, so AGENTS.md was never read. Setting either variable to 0 did not help; any value counts as "set".
Corporate gateways had the same problem. The original issue reported that AWS Bedrock, Google Vertex, and third-party gateways also failed the flag check, for the same reason: they do not reach Anthropic's flag servers.
Nothing warned you. This is the part that should bother you most. The session started, the model answered, and there was zero indication that a file in your repo had been skipped.
The canary test was simple and brutal. Szypowicz made a directory containing only an AGENTS.md with a canary sentence, ran claude -p asking for the canary word, and the model answered NONE with telemetry off. One file, one question, one provable silence.
On the Hacker News thread, an Anthropic engineer apologized and called it "a rollout artifact": the team needed a way to disable the feature remotely if it broke something, and with telemetry off, feature flags cannot be fetched. The fix landed in v2.1.281, released September 23, 2026.
Why a "Fixed" Bug Still Matters
The bug itself was human error, and the response was fast and honest. Fair enough. But step back and look at the shape of the failure, because that shape will recur.
A local file read waited on a server. Reading a markdown file from your own working directory requires no network at all. Yet the feature that reads it depended on a round trip to a flag server, and the fallback when the network call failed was "silently do less". Every developer who has built feature flags knows this tradeoff. Every developer who has been burned by a flag defaulting to off in an air-gapped environment knows it more painfully.
Silent degradation is the worst failure mode for agent tooling. If your build fails, you see the red. If your agent ignores your config, it just produces worse answers, and you blame the model. How long would it take you to notice that your test commands were never being followed? A day? A week? Would you ever attribute it to a skipped file rather than a "dumber" model?
Your instruction files leak your environment. AGENTS.md and CLAUDE.md routinely contain internal package names, private registry URLs, deployment targets, and team conventions. They are a map of your infrastructure, written in plain text, in every repo. The question "does my agent send these anywhere, and under what conditions" is now a real security question, not paranoia. This incident did not involve your files being uploaded anywhere. But it proved that the path between "file on disk" and "instructions in the model's context" runs through code you have never audited, gated by servers you have never seen.
The One-Line Fix Worth Knowing
Even with the bug fixed, this workaround is useful, because it makes your AGENTS.md load independent of any plugin or flag.
CLAUDE.md supports @path imports, and imports do not depend on the feature flag. So put one line in your CLAUDE.md:
@AGENTS.md
That single line tells Claude Code to load your AGENTS.md as part of CLAUDE.md processing, which has been stable core behavior for a long time. One file, one source of truth, every agent tool that reads either convention gets what it needs.
A detail worth stealing from the same research: for shared skills, symlink .claude/skills to ../.agents/skills rather than copying. Copies drift. Symlinks do not.
The 15-Minute Agent Config Audit
Here is the checklist I would run on any AI coding agent before trusting it with a real repo. It takes about fifteen minutes per tool and you only redo it when the tool updates.
Step 1: Run a canary test. Create a scratch directory with nothing but a config file containing a made-up word:
mkdir /tmp/agent-canary && cd /tmp/agent-canary
echo 'The canary word is PERIWINKLE.' > AGENTS.md
Then ask the agent, without letting it read files: "What is the canary word from the project instructions? Answer NONE if you have none." If it says NONE, your instructions are not loading. If it says PERIWINKLE, check whether it cheated by reading the file, and re-run with file access blocked. Two sessions per configuration, because flag-based features only resolve on the first call.
Step 2: Test with telemetry and network restrictions on. Repeat the canary with your real shell environment: telemetry disabled, proxies on, VPN on, whatever your actual setup is. The default developer machine is not the clean test environment. Your machine is the one that matters.
Step 3: Test through your real endpoint. If you run agents through Bedrock, Vertex, or a corporate gateway, run the canary there too. Endpoint differences are exactly where this bug lived.
Step 4: Grep the binary or source for flag gates. If the tool is source-available, search for the names of your config files and check whether loading is conditional. The phrase to look for is a feature-flag or remote-config call wrapped around your file's loader. Five minutes with grep answers the question "is this a local behavior or a remote permission".
Step 5: Check the silence behavior. Deliberately break something: point an import at a missing file, use a malformed config. If the tool starts a happy session anyway, you have learned the most important thing about it: it fails silently, so you need canary tests in your routine, not just once.
Step 6: Inventory what your config files reveal. Read your AGENTS.md and CLAUDE.md files as if a vendor's telemetry pipeline might see them, because this incident proved the loading path can involve vendor servers. Move anything you would not put in a public issue tracker: internal hostnames, tokens, real team names. Config files should contain conventions, not credentials.
Run these six steps on every agent you use: Claude Code, Codex, Cursor, whatever your team has adopted. The point is not that any specific tool is untrustworthy. The point is that "the agent read my instructions" is now a claim to verify, like "the backup restored" or "the failover worked". Trust, but canary.
What I Would Do Differently Going Forward
Three habits worth adopting from this whole episode:
Prefer imports over native support, at least for now. The @AGENTS.md import line works regardless of plugins, flags, or launch decisions. It is one line of insurance.
Add a canary check after every agent version bump. These tools auto-update weekly. Treat each update like a dependency upgrade in a critical path: cheap test, every time.
Assume silent failure until proven otherwise. The most surprising part of this story was not the flag. It was that a skipped config file produced zero diagnostics. Any agent feature without a warning path is a feature that will someday be off without you knowing.
The bigger lesson is about how this software category works. We are running autonomous tools that read our code, our configs, and increasingly our credentials, shipped by labs moving at launch-every-week speed, verified by almost nobody. This incident had a happy ending: a researcher measured, the company fixed it in a day, the engineer owned it publicly. That is the system working. It only works when someone runs the canary test.
So run it. Fifteen minutes, one made-up word.
I write about AI tooling, developer infrastructure, and the unglamorous engineering that keeps agents honest, every week. Subscribe, it is free.
Have you run a canary test on your AI coding agent? Did your instructions actually load? Tell me what you found in the comments, especially if you are behind a corporate gateway.
Top comments (0)