奇链 奇链
← 文章 / AI技术
Hacker News 55分钟前 · 2026-09-23 22:11:35 · 3 阅读

Claude Code 仅在启用遥测时读取 AGENTS.md 文件

Claude Code 2.1.277 宣布支持 AGENTS.md 文件。在缺乏 CLAUDE.md 的项目中，程序本应改为读取 AGENTS.md。但我一直关闭 Shell 中的遥测功能，结果发现仓库中的该文件从未被加载。Issue #95690 解释了原因，我也在其中补充了自己的测试数据。本文旨在汇总这些测量结果。

控制门槛在哪里

加载器作为一个名为 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。B 对应 isAvailable 函数，它会查询名为 tengu_agents_md_mod 的远程特性开关，且后备值设为 false。一旦 Claude Code 无法获取该开关，插件即视为不可用，本地文件也就不会被读取。虽然从工作目录读取 Markdown 文件并不需要网络，但这里却被一个服务端开关所阻塞。

我的测试方法

我创建了一个仅包含 AGENTS.md 的空目录，并在其中写入一个“金丝雀词”（canary word，用于验证标识），然后通过 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 就无法被读取，因此必须清除这两个变量。
  • 将任一变量设为 0 也无济于事，阻塞状态依然保留。环境变量文档称任意值均有效，但在试图启用功能时，这一细节很容易被忽视。
  • 在项目 .claude/settings.json 中添加清除这两个变量的 env 配置块也无效。目前无法针对单个仓库单独启用此功能。
  • 从第二个会话开始，会话级覆盖才生效：
claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'

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

变通方案

CLAUDE.md 支持 @path 导入，而且这个功能不依赖该 flag。在 AGENTS.md 旁边放一个只有一行的 CLAUDE.md，就能在关闭遥测的情况下加载它：

echo '@AGENTS.md' > CLAUDE.md

加上这个文件后，即使仍然设置着 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1，同样的金丝雀测试也能返回那个词。代价是每个仓库多出一个文件——而 AGENTS.md 支持本来就是为了消除这种冗余的。

为什么我认为这不可接受

我是有意关闭遥测的，我预期这个选择的代价只是损失一些诊断数据，仅此而已。但实际上它悄悄夺走了我一项功能——读取我自己磁盘上的文件。对于需要与服务器通信的功能，用远程 flag 来控制还说得过去，但这个功能唯一的输入就在工作目录里。

这个门槛偏偏卡在了最在乎 AGENTS.md 的人身上。维护一份供多个 agent 共用的指令文件的人，通常会对每个工具上报什么数据很敏感；而在 Bedrock、Vertex 或网关上的团队，往往出于政策要求禁用非必要流量。这些人拿到的都是一个宣称可用、实际上毫无作用的功能。

最糟的是它的沉默。我是靠金丝雀词和对二进制文件的字符串搜索才确认了原因，但大多数人不会这么做。他们会认定模型无视了自己的指令，然后花时间反复调整提示词——而实际上那个文件压根就没送到模型手里。

隐私设置绝不应该悄悄关闭无关的本地行为。如果 Anthropic 想做灰度发布，那么在 flag 无法获取时，回退行为就应该是文档中描述的正常行为，或者至少给出一条可见的消息，说明跳过了什么以及为什么。

我希望看到的改进

  • 读取本地文件不应依赖于遥测功能。如果出于逐步推广的目的需要保留此限制，那么当检测到 AGENTS.md 存在但被跳过时，启动时应给出警告，以免用户像我当初做金丝雀测试那样浪费时间。
  • 全局 AGENTS.md 支持缺失。该插件仅在项目目录中查找 AGENTS.md 和 .claude/AGENTS.md，而在用户目录下没有与 CLAUDE.md 并列的全局文件。Codex 会读取全局的 ~/.codex/AGENTS.md；Claude Code 的 /import 命令虽然能将此文件复制到用户的 CLAUDE.md 中，但后续的编辑同步无法实现。如果你为多个代理维护同一套个人指令，仍需在用户级的 CLAUDE.md 中添加指向共享文件的 @ 导入。
  • 缺乏对共享代理技能的原生支持。Codex 会从项目内的 .agents/skills 和主目录下的 ~/.agents/skills 读取技能。Claude Code 2.1.280 仅在 /import 命令中知晓这些路径，且该命令会将技能复制到 .claude/skills。我在 .agents/skills 放置了一个测试技能，Claude Code 未能列出它，却能列出同一仓库中 .claude/skills 下的同名技能。由于副本会与源文件产生偏差，我改用软链接将 .claude/skills 指向 ../.agents/skills，Claude Code 能够正确跟随该链接。

在此之前，我使用单行 CLAUDE.md 作为指令，并通过对技能目录建立软链接来解决问题。

原始来源： Hacker News

评论 (0)