Sep 24, 2026

AI 热点快报：Claude Code 把「读取本地 AGENTS.md」锁在了远程开关后面（2026-09-24）

事件与背景

Claude Code 2.1.277 的官方 CHANGELOG 写了一行看起来很干净的话：「新增 AGENTS.md 支持——项目里没有 CLAUDE.md 时，Claude Code 改为读取 AGENTS.md；可在 /config 的 “Project instructions” 里修改（Bedrock、Vertex、Foundry 暂不支持）」。对一个同时用多款编码 agent 的团队来说，这是把指令文件统一到跨工具标准 AGENTS.md 的关键一步。

但 9 月 20 日创建、至 9 月 23 日仍为 open 的 GitHub issue #95690，以及 9 月 23 日 Przemek 在博客上补的实测，指出这行字背后的实现：AGENTS.md 支持是一个名为 agents-md 的内置插件，isOnByDefault=false，它的可用性判断会去请求 Anthropic 的远程特性开关（Statsig gate）tengu_agents_md_mod，拉不到就回退为 false。换句话说，读取工作目录里的一个 markdown 文件本来完全不需要网络，现在却要先等服务端开关。

作者的验证方式很简单，也很容易复制：建一个空目录，里面只放一个含 canary 词的 AGENTS.md，然后用 claude -p 问它这个词是多少（要求不要读文件），每种配置跑两个会话——第一个会话只负责拉取开关，第二个才会真正使用它。结果是三类会话永远读不到这个本地文件：

设了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1（官方文档写明该变量任意非空值即生效）；
设了 DISABLE_TELEMETRY=1——而这个变量「设成 0 或 false 仍然是退出遥测」，把它置 0 并不能恢复功能；
走 Bedrock、Vertex、Foundry 或第三方 gateway 的会话——开关在那里根本无法解析为 true。

最要命的不是这个门，而是没有任何警告：会话照常启动，模型照常回答，只是没有项目指令，也没有任何东西告诉你那个文件被跳过了。

值得注意的是，官方文档并没有把它当 bug，而是写成了预期行为。env-vars 文档在「关闭特性开关拉取后你不能做什么」的清单里，第一条就是：不能再把 AGENTS.md 当作项目指令读取——只加载 CLAUDE.md。memory 文档甚至专门有 “When AGENTS.md support is unavailable” 一节和排障条目「My AGENTS.md isn’t loading」，列出四种读不到的情形：版本低于 v2.1.277；会话不拉取特性开关（第三方 provider，或关闭了遥测）；安装或升级后的第一个会话（flag 尚未缓存）；在 /plugin 里关掉了内置的 agents-md 插件。

issue 里的复现把 CI 场景补全了：@mmailhos 在 2.1.278 + 全新隔离 home 下确认，安装后第一个会话必然跳过，而在关闭 flag 拉取（DISABLE_GROWTHBOOK=1 或关掉 nonessential traffic）时每次都跳过——「这正是 CI runner 的做法」；@foma-agent 补充 DISABLE_TELEMETRY=0 同样会关掉 flag 拉取，官方文档确认只有 DO_NOT_TRACK 按标准布尔解释（0 表示保留遥测）。当天 HN 首页讨论拿到 391 分，标题还被提交者加上了 “[fixed]” 后缀。

为什么现在重要

本地行为第一次被服务端开关「代管」。 一个不需要任何网络的本地文件读取，被一个必须联网才能求值的 flag 卡住；这对隐私敏感团队意味着「关掉遥测」不再只损失诊断信息，而是顺带损失功能。影响：合规设置开始带上隐藏的功能税，而账单不会出现在日志里，只会出现在「模型怎么不听我的指令」上。
静默失败比失败本身更贵。 没有警告、没有提示、没有跳过记录，绝大多数人不会像作者一样做 canary 测试和二进制字符串搜索，只会得出「模型忽略了项目规范」的结论，然后把时间花在改 prompt 上——而文件根本没到模型手里。影响：凡是「配置是否生效」不可观测的 agent 工具，都会持续制造这类无效调试成本。
受影响的人恰好是最在意 AGENTS.md 的人。 维护一份多 agent 共享指令文件的人，通常最在意每个工具往家里发了什么；按政策关闭 nonessential traffic 的 Bedrock / Vertex / gateway 团队同理。影响：如果你的选型清单里有企业通道或自托管推理，「新功能在你们环境里是否可用」应当成为一条硬性验收项，而不是上线后才发现。
跨工具标准 AGENTS.md 的落地比口号脆弱。 agents.md 自称有 6 万多个开源项目在用这个格式，但各家支持路径不同：Claude Code 靠 flag 缓存 + 插件开关，Codex 直接读全局 ~/.codex/AGENTS.md 和 .agents/skills，而 /import 这类命令是复制语义，指令一旦被复制出去，后续编辑就漂移了。影响：共享指令层需要有明确的单一真源（single source of truth）与验证手段，不能靠各家导入功能拼接。
agent 工具链进入「配置治理」阶段。 当 instruction 文件、插件开关、遥测状态、provider 通道四者能互相影响时，它已经不再是「写个 markdown 文件」，而是一份需要被测试的运行时配置。影响：把指令加载纳入 CI 断言和启动日志，成本很低，能省掉整类「模型不遵守规范」的隐形故障。

工程师/产品人今天能做什么

用 canary 词自检一遍，别猜。 五分钟可完成，注意第一个会话只拉 flag、第二个会话才生效：

mkdir -p /tmp/cc-canary && cd /tmp/cc-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.'

在你的真实遥测配置下跑两遍；返回 NONE 就说明指令文件根本没加载。

立刻加一行桥接文件。 CLAUDE.md 的 @path 导入不经过这个 flag：echo '@AGENTS.md' > CLAUDE.md。代价是每个仓库多一个文件，也正是 AGENTS.md 支持本来想省掉的那个文件；如果是多仓库共享的个人指令，改为在用户级 CLAUDE.md 里用 @ 指向共享文件。
在 CI 里加启动断言，而不是依赖 flag 缓存。 CI runner 通常按政策禁用 nonessential traffic，属于「每次都跳过」的那一类；把 canary 检查做成流水线的一步（或在 session 启动日志里断言加载了哪些指令文件），可以保证 agent 在流水线里行为与本地一致。
把「实际加载了哪些指令文件」变成可观测输出。 在 session 启动时打印本次加载的 instruction 文件与插件启用状态（/config、/plugin），并在评审里把它当成事实来源；只有被记录下来的加载行为，才谈得上可归因。
把遥测开关的语义写进团队文档。 DISABLE_TELEMETRY 是「任意非空值即退出，置 0 无效」，DO_NOT_TRACK=1 才是标准布尔（0 表示保留遥测），而 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 同样是非空即生效。这三种写法在同事手里很容易被误用成「关了一半」，导致功能被静默关掉却没人知道原因。

待观察

到底修没修，目前无法从一手来源确认。 HN 帖子标题被加了 “[fixed]” 后缀，但 issue #95690 到 9 月 23 日 17:23 仍为 open，官方 CHANGELOG 更新到 2.1.280 也没有对应的修复条目（那里只有 Opus 5.5 成为默认模型等改动）。在拿到明确说明之前，不要摘掉你的桥接文件。
Anthropic 是否为「静默跳过」加启动警告。 作者提出的诉求很具体：给本地文件读取保留独立的可用性判断，或者至少在有 AGENTS.md 却被跳过时打印一条启动提示；官方文档目前仍把它当作预期行为来记载，因此这会是一个产品决策而不是补丁。
第三方通道的 flag 能力是否会补齐。 Bedrock、Vertex、Foundry 与 gateway 会话拿不到 flag，意味着企业用户可能在很长一段时间里都要靠桥接文件绕过；对正在做 agent 平台选型或采购的人来说，这是需要向厂商确认的明确问题。