Claude Code 2.1.277 引入 AGENTS.md 支持，但受远程遥测开关限制
Claude Code 版本 2.1.277 宣布支持读取 AGENTS.md 文件。官方文档指出，在没有 CLAUDE.md 的项目中，系统应自动加载 AGENTS.md。然而实测发现，当用户关闭远程遥测功能时，该文件从未被加载。GitHub Issue #95690 解释了这一现象背后的机制：插件的启用依赖于一个名为 tengu_agents_md_mod 的远程功能标志。
加载机制与门控逻辑
AGENTS.md 的加载器作为内置插件实现，在 2.1.280 版本的注册表中配置如下：
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。这意味着插件必须通过获取远程标志 tengu_agents_md_mod 才能激活。如果 Claude Code 无法连接到服务器获取该标志，插件将保持禁用状态，本地文件不会被读取。尽管读取工作目录中的标记文件完全不需要网络交互，但该功能却被绑定在了服务器端的开关上。
测试验证与行为分析
为了验证这一行为，可以在空目录中创建一个包含特定“金丝雀”字眼的 AGENTS.md 文件。由于新配置下的第一个会话仅用于获取标志，而第二个会话才会实际应用该标志，因此需要多次运行命令进行测试：
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 所述，阻止远程连接会导致功能失效。
- 设置环境变量
DISABLE_TELEMETRY或CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC为任意值（包括 0）均无效，阻塞依然生效。 - 在
projects.claude/settings.json中清除相关环境变量块没有任何效果，目前无法针对单个仓库启动该功能。 - 通过在会话级别重置环境变量可以解决问题，从第二个会话开始功能正常：
claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'
值得注意的是，上述所有失败案例均未发出任何警告或提示，用户无法得知文件被跳过的原因。第三方网关、Bedrock 和 Vertex 服务也存在同样问题，因为这些环境同样无法解析该远程标志。
临时解决方案
目前存在一种绕过方法。CLAUDE.md 支持 @path 导入语法，且这种导入不依赖于远程标志。通过在 AGENTS.md 旁边创建一个单行的 CLAUDE.md 文件，即可在不依赖远程遥测的情况下加载指令：
echo '@AGENTS.md' > CLAUDE.md
使用该文件后，即使保持 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 设置，之前的金丝雀测试也能成功返回预期单词。这表明 AGENTS.md 的支持本应无需依赖远程测量即可正常工作。
争议与改进建议
对于注重隐私的用户而言，关闭远程遥测是预期内的选择，但这不应导致本地文件读取功能的静默失效。读取磁盘上的文本文件与服务器通信无关，将其置于远程开关之后被认为是不合理的设计。此外，最可能使用 AGENTS.md 的用户群体（如跨多个代理维护统一指令文件的开发者，或在 Bedrock/Vertex 等受严格政策约束的环境中工作的团队）往往正是那些会主动禁用非必要流量的人。这导致他们获得了一个看似可用实则无效的功能。
缺乏警告信息加剧了问题的隐蔽性。大多数用户可能会误以为模型忽略了指令，从而浪费时间在提示工程调试上，而非意识到是配置加载失败。
社区期望看到的改进包括：
- 解耦本地读取与遥测：读取本地文件不应依赖于遥测数据。至少应在检测到
AGENTS.md存在但因标志缺失而被跳过时，向用户发出启动警告。 - 支持全局 AGENTS.md：当前插件仅在项目目录及
.claude/AGENTS.md中查找文件，不支持用户级全局文件。相比之下，Codex 支持读取~/.codex/AGENTS.md。虽然 Claude Code 的/import命令可将内容复制到用户CLAUDE.md，但这不会跟随源文件的后续编辑。对于多代理场景，用户仍需手动维护指向共享文件的@ import。 - 支持共享代理技能：Codex 可从项目中的
.agents/skills和主目录中的~/.agents/skills读取技能。Claude Code 2.1.280 仅在/import中识别这些路径，但未列出它们；相反，它列出了来自同一仓库.claude/skills的技能。目前常见的变通方案是将.claude/skills链接到.agents/skills。
在上述改进实施之前，使用单行 CLAUDE.md 作为指令入口，并利用符号链接管理技能，是目前可行的替代方案。
