Claude Code 读取 AGENTS.md 竟依赖遥测开关

Claude Code 只在遥测（telemetry）开启时才读取 AGENTS.md

Claude Code 2.1.277 新增了对 AGENTS.md 的支持，但加载器被一道远程特性开关（feature flag）挡在后面。关掉遥测或非必要流量（nonessential traffic）时，本地的 AGENTS.md 就被直接跳过，也不给任何警告。下文是我测到的数据，以及我改用的一行 CLAUDE.md。

2026-09-23 5 min read ai-assisted Claude Code 2.1.277 宣布支持 AGENTS.md。在没有 CLAUDE.md 的项目里，它本应转去读 AGENTS.md。我的 shell 默认关了遥测，结果仓库里这个文件从来没被加载过。

Issue #95690 解释了原因，我把自己测到的数据也补到了那条 issue 下。本文把这些数据汇总到一处。

这个开关在哪里

加载器本身是名为 agents-md 的内置插件（plugin）。它在 2.1.280 构建（bundle）中的注册代码长这样：

var W=!1;var B=()=>Oa("tengu_agents_md_mod",W);var H="AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; ...";

W 是该插件的 isOnByDefault 值，为 false。

B 是 isAvailable，它会查询一个名为 tengu_agents_md_mod 的远程特性开关，拿不到值时回退为 false。Claude Code 拿不到这个开关时，该插件就不可用，本地文件也永远不会被读取。从工作目录里读一个 markdown 文件根本不需要网络，但这里却要等一个服务端开关。

我是如何测试的

我建了一个空目录，里面只放一份包含金丝雀词（canary word）的 AGENTS.md，然后用 claude -p 问这个词。每种配置我都跑两个会话，因为在新的配置下第一次会话只会去拉取开关，第二次才会用到它。

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.'

我的测量结果

正如那条 issue 所说，CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 会拦截这个功能。

DISABLE_TELEMETRY=1 同样会拦截它。这两个变量只要设了任意一个，AGENTS.md 就永远不会加载，所以我必须两个都清空。

把其中任一变量设为空串也无济于事，拦截依然生效。环境变量文档里说「任何值都算」，但想开启功能时这一点很容易被忽略。

在项目的 .claude/settings.json 里通过 env 块清空这两个变量也没有效果。没办法为单个仓库单独开启这个功能。

会话级别的覆盖从第二次会话起是生效的。

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

以上情况都不会打印任何警告。会话正常启动，模型回答时拿不到项目指令，也没有任何提示告诉你有一份文件被跳过了。那条 issue 还指出，第三方网关以及 Bedrock、Vertex 也有同样的问题，因为在这些环境下这个开关同样无法解析为 true。

临时解决办法

CLAUDE.md 支持 @path 形式的导入，这种导入不依赖那个开关。在 AGENTS.md 旁边放一行 CLAUDE.md，就能在关闭遥测的情况下把它加载进来：

echo '@AGENTS.md' > CLAUDE.md

放上这个文件之后，金丝雀测试照样能返回那个词，即便 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 还设着。代价是每个仓库多一个文件，而这恰恰是 AGENTS.md 支持本应省掉的事。

为什么我认为这不可接受

我是有意关掉遥测的，本以为只会损失一些诊断信息，不会有别的影响。但它在这里悄悄砍掉了我读取自己磁盘文件的功能。远程开关对那些需要和服务端通信的功能来说是合理的，但这个功能所需要的全部输入早就已经位于工作目录里了。

这个开关还波及到最关心 AGENTS.md 的人。一份指令文件要喂给多个智能体（agent）的人，通常对每个工具往回传什么很谨慎；用 Bedrock、Vertex 或网关的团队，也经常按策略禁用非必要流量。他们全都拿到一个号称「可用」、实际「什么都不做」的功能。

最糟糕的是它全程一声不吭。我是用金丝雀词、再在二进制里搜字符串才定位到原因的，而大多数人不会这么做。他们只会以为模型不听话，然后花时间去调提示词，其实那份文件压根没到过模型手里。

一项隐私设置不该悄无声息地把无关的本地行为也一起关掉。如果 Anthropic 想分阶段推出，那在拿不到开关时，回退行为至少应该跟文档说的一致，或者至少显示一条可见消息，说明跳过了什么、为什么跳过。