Independent AI intelligence Two editions daily · ET
Fervor AI
Menu

Analysis · September 23, 2026 · concept

AGENTS.mdClaude Codeclaude-codeagent-harnessprivacyagent-securityai-skills

Claude Code's AGENTS.md Support Resolves Against a Remote Flag, Not Your Disk

A file sitting on your own hard drive, read only when the network says so. Here is the mechanism, why it fails without a word, and the two-minute test that catches this whole class of bug in any agent you run.

Reading a markdown file from the working directory requires no network. That sentence should be so obvious it is boring. It is also, as of Claude Code 2.1.277, not quite true: the loader that reads your AGENTS.md sits behind a remote feature flag, and when the flag cannot be fetched, the file is skipped. No error. No warning. The session starts, the model answers, and your project instructions were never in the context at all.

Przemek Szypowicz found this the way these things usually get found, by not believing his own tooling. He put a canary word in an AGENTS.md, asked for it back, and got nothing. Then he went looking for why, and published the measurements on September 23.

The mechanism

The AGENTS.md loader ships as a built-in plugin named agents-md. Szypowicz pulled its registration out of the 2.1.280 bundle, and it reads like this:

var W = !1;
var B = () => Oa("tengu_agents_md_mod", W);

W is the plugin's isOnByDefault value, and it is false. B is isAvailable, and it queries a remote feature flag called tengu_agents_md_mod, passing W as the fallback. So when Claude Code cannot reach the flag service, the answer is no, the plugin is unavailable, and a file on your local disk goes unread.

That is a staged-rollout pattern, and staged rollouts are fine. The problem is which way the fallback points and what else turns it off.

What actually blocks it

Szypowicz tested each configuration twice, because the first session in a new configuration only fetches the flag and the second one uses it. What he measured:

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 blocks the feature. That one at least makes intuitive sense once you know the loader talks to a server.

DISABLE_TELEMETRY=1 blocks it too. This is the one that stings. You turned off telemetry, an unrelated privacy control, and it switched off a local file read.

Setting either variable to 0 does not help. Claude Code's environment variable convention is that any value counts as set, which is documented and is also exactly the kind of documented thing people miss when they are trying to turn something back on.

An env block in the project's .claude/settings.json that clears both variables has no effect. There is no per-repo escape hatch.

A session-level override does work, from the second session onward:

claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'

None of these cases prints anything. That is the part worth sitting with. Szypowicz's writeup notes that the tracking issue, #95690, also covers third-party gateways, Bedrock and Vertex, where the flag cannot resolve to true either.

Why the silence is the real bug

Think about who turns telemetry off. Someone maintaining a single instruction file across Claude Code, Codex and whatever else they run is usually the same person who has opinions about what each of those tools sends home. Enterprise teams on Bedrock or Vertex frequently disable nonessential traffic by written policy, not by preference. The gate lands hardest on the exact population that the AGENTS.md convention exists to serve.

Now think about what those people experience. They write careful project instructions. The model ignores them. They rewrite the instructions. The model ignores them again. They start tuning phrasing, adding emphasis, restructuring sections, maybe blaming the model's instruction-following. Every hour of that is spent on a file the model never saw.

I have watched people burn days on prompt archaeology for problems that turned out to be a path, an encoding, or a load order. This is that failure, shipped as a feature flag. A system that fails open on policy and fails silent on features has its failure modes exactly backwards, and the cost is not the missing feature. It is the false hypothesis it hands you.

Put this into practice

The lowest-friction fix first, then the habit that matters more.

Restore the load with a one-line import. CLAUDE.md supports @path imports, and those do not depend on the flag:

echo '@AGENTS.md' > CLAUDE.md

Szypowicz verified the canary test passes with that file in place and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 still set. The cost is one extra file per repository, which is the thing AGENTS.md support was supposed to eliminate. Take the trade anyway; a redundant file beats invisible instructions.

Then write the canary test, because this is not really about AGENTS.md. It takes two minutes and it generalizes to every agent and every instruction file you maintain:

mkdir /tmp/canary && cd /tmp/canary
echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'

Three details make it work. Pick a word that cannot appear by coincidence, so a lucky guess is not a false pass. Add "do not read files," so you are testing the instruction-loading path rather than the agent's ability to open a file it was told about. And run it twice in any new configuration, since the first run in a fresh config may only be fetching the flag.

Do this per repository if your instruction files differ, and do it again after every upgrade. Claude Code releases move fast enough that a load path can change between the version you validated and the version you are running.

Audit what else is network-shaped. Once you have seen one local behavior gated on reachability, the useful question is which others are. Run your agent with network egress restricted, in a test project, and see what stops working. Anything that changes behavior between connected and disconnected runs is a feature whose availability depends on something outside your repository, and that is worth knowing before it matters.

Sort out skills while you are in there. Codex reads skills from .agents/skills in the project and ~/.agents/skills at home. Claude Code 2.1.280 knows those paths only through /import, which copies them into .claude/skills, and a copy drifts from its source the moment you edit one side. Szypowicz links .claude/skills to ../.agents/skills instead and reports Claude Code follows the symlink. Worth noting that 2.1.280 also fixed writes through symlinked paths being judged by their in-tree spelling rather than where they landed, so if you are going to introduce path indirection on purpose, know what sits on the other end of it.

Honest limitations

What I am describing here is one engineer's measurements, reproduced carefully and documented in public, plus a string search through a bundled JavaScript file. It is not a vendor statement. Anthropic has not published an explanation, and the flag behavior could change in any release, possibly before you read this. Re-run the canary rather than trusting my description of a build I did not test.

The workaround is narrower than it looks, too. A one-line CLAUDE.md restores instruction loading for that repository. It does not give you a global AGENTS.md: the plugin looks only at project directories, with no user-level file beside the user CLAUDE.md, so a personal instruction set shared across agents still needs an @ import pointing at it. And I have not independently confirmed the Bedrock, Vertex and gateway behavior, which comes from the issue thread rather than from my own runs.

There is a fair counterargument I should state properly. Feature flags let a vendor roll back a broken feature without shipping a release, and for a loader that changes what goes into every prompt, that caution is defensible. If the flag defaulted to the documented behavior when unreachable, or printed one line when it skipped a present file, almost none of this would be worth an article. The design problem is the fallback direction and the silence, not the existence of the flag.

I also cannot tell you how many people are affected. Telemetry-off is the population by definition, which is the population nobody has data on. That is a small joke and also the actual reason a bug like this can live in a shipped release.

What to do with this

The transferable lesson is not a workaround, it is a stance. Treat your agent's configuration as a claim, not a description. A settings file says what somebody intended; only a test tells you what the running system does. Between a remote flag deciding whether a local file gets read, and a permission rule comparing the spelling of a path instead of resolving it, September has produced two clean demonstrations that the gap between those two things is real and currently unmeasured by most of us.

So measure it. Put a canary in your instruction files this afternoon and find out whether your agent can see them. If it can, you spent two minutes. If it cannot, you just recovered every hour you were about to spend rewriting prompts for a file that was never there.

Sources: Przemek Szypowicz's measurements, September 23, 2026; anthropics/claude-code issue #95690; the Claude Code changelog for the 2.1.280 symlink and auto-mode entries.

Medium metadata

Title: Claude Code's AGENTS.md Support Resolves Against a Remote Flag, Not Your Disk Subtitle: A file on your own hard drive, read only when the network says so Tags: Claude Code, AI Agents, Developer Tools, Software Engineering, Privacy Canonical: publish on fervorai.dev first, then import to Medium with canonical set to the fervorai.dev URL.