这条在讲 Claude Code 2.1.277 宣布支持 AGENTS.md 之后，实际测出来的一个事。出处是 Przemek，blog.szypowi.cz，今天发的。功能默认关着，读不读 AGENTS.md 取决于一个远程开关，而你一旦关掉遥测或者禁用非必要流量，工作目录下的 AGENTS.md 就静默不读。
我第一反应是不信。AGENTS.md 又不是什么云端服务，本地文件读取为什么要看远程开关。于是按他的方法顺手跑了一下。
mkdir /tmp/agentstest
cd /tmp/agentstest
echo "PERIWINKLE" > AGENTS.md
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude -p "what is the canary word in AGENTS.md?"
模型回答没提 PERIWINKLE。我环境里本来设了那几个隐私变量，所以第一次跑完以为是自己把环境弄坏的，把变量设成 0 再跑，还是不行。设成 0 不算清空，照样卡住。
读到作者写“每种配置都跑两个会话”那段我才确认，这是真测过的，不是看代码猜的。我跑的时候只跑了一个会话，所以第一遍没注意到“第一个会话只拉开关、第二个才用”这个细节。作者每个配置都跑两个会话，第一个会话负责拉那个远程开关，第二个才实际使用开关。他给的结论是：必须同时清空 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 和 DISABLE_TELEMETRY 两个变量，AGENTS.md 才会被读。我也试了在项目根 .claude/settings.json 的 env 块里清空这俩变量，没用。单个仓库想开都开不了。作者说的会话级覆盖能生效，但要到第二个会话才起作用。
最让我来气的是所有失败情形都没警告。会话正常启动，模型在没有项目指令的情况下照常回答。不放金丝雀词，你根本不会发现 AGENTS.md 压根没被读。到这儿我对这个功能的火气已经上来了。
作者原话我记不全，但大意是：把读取本地文件的能力挂在遥测开关上，不可接受。关闭遥测本该只损失一些诊断信息，现在把项目指令也一起静默扔了。我同意。这事还不只关遥测的人会踩。作者提到问题编号 #95690，说第三方网关、Bedrock、Vertex 也会卡，因为那些环境里远程开关同样解析不成 true。也就是说你不一定非得手动禁非必要流量，走代理的、用云托管的，都可能撞上 AGENTS.md 失效——每次都是静默的，没有任何提示。
我最不舒服的不是“bug 还没修好”，而是失败方式。开关取不到，回退默认 false，这没问题；但工作目录里明明放着一个叫 AGENTS.md 的文件，至少该说一句“检测到了但我没读，因为当前环境禁用了开关”。这行日志不复杂，也不暴露什么敏感信息。现在这样，等于让用户自己猜是不是文件名不对、格式不认、路径写错。
作者给的规避方法直接：在 AGENTS.md 旁边再放一个 CLAUDE.md，内容一行——
@AGENTS.md
因为 CLAUDE.md 的 @path 导入不依赖那个远程开关。代价是每个仓库多出一个文件，正是 AGENTS.md 本来想省掉的东西。绕一圈，回到“每个仓库手放一个 CLAUDE.md”的老路，只是这个 CLAUDE.md 只写一行。
我按这个跑通了。AGENTS.md 被读到，模型答出了金丝雀词。跑通那一下松口气，但也更觉得讽刺：功能本身没毛病，就是被这个开关卡住了。
写到这儿我犹豫过这锅算产品设计还是发布流程。从打包代码看，插件默认不开启，远程开关名是 tengu_agents_md_mod，取不到就回退 false——像是个还没准备好全量放开的功能，用开关做灰度。灰度没问题。问题是不该把“读本地文件”和遥测流量这两个不相干的事绑在同一个环境变量判定上。用户为了隐私关掉非必要流量，不该附带“本地 AGENTS.md 失效还不告诉你”的惩罚。
还有件拧巴的事。Claude Code 这个插件只在项目目录找 AGENTS.md 和 .claude/AGENTS.md，没有用户级 AGENTS.md。Codex 会读全局 ~/.codex/AGENTS.md。我夹子里还存过一篇写 Codex 共享技能路径的，Claude Code 在这块的兼容也拧巴，但那是另一个话题了，这篇值钱的还是金丝雀词实验。
不点链接也能带走的一句：如果你 Claude Code 项目突然变笨、不看项目指令了，先查你是不是动过 DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC。真要用 AGENTS.md，现在最稳的办法不是清变量，是放一个内容为 @AGENTS.md