Claude Code 仅在开启遥测时才会读取 AGENTS.md
Hacker News 摘要原标题：Claude Code reads AGENTS.md only when telemetry is on
这篇技术博客详细分析了命令行工具 Claude Code 在读取项目指令文件 AGENTS.md 时存在的一个隐蔽问题：只有在开启遥测（Telemetry）或允许非必要网络流量时，该文件才会被加载。
问题机制与代码分析
Claude Code 在 2.1.277 版本中宣布支持 AGENTS.md。按照设计，在没有 CLAUDE.md 的项目中，它应当自动读取 AGENTS.md 作为项目指令。
但作者查看 2.1.280 版本的打包代码后发现，该功能的加载器以名为 agents-md 的内置插件形式提供，并且被远程功能标志（Feature Flag）控制：
• 插件的默认启用状态（isOnByDefault）被硬编码为 false。
• 插件的可用性检查（isAvailable）会请求一个名为 tengu_agents_md_mod 的远程功能标志，请求失败时的默认回退值也是 false。
• 只有当 Claude Code 能够连接服务器并成功获取到该标志为开启时，插件才会生效。
读取本地 Markdown 文件本身不需要网络，但在此机制下却完全依赖服务端的远程开关。
测试方法与实测结果
作者在一个空目录中创建了包含金丝雀测试词的 AGENTS.md，通过 claude -p 命令测试模型能否获取该词。经过多组测试，得出以下结论：
• 设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 会阻止此功能。
• 设置 DISABLE_TELEMETRY=1 同样会阻止此功能。只要开启了其中任意一个禁用变量，AGENTS.md 就永远不会被加载。
• 将上述环境变量设为 0 无法解决问题，只要变量存在且有值就会触发禁用。
• 在项目的 .claude/settings.json 中配置 env 块清空这些变量完全无效，无法针对单个代码仓库单独开启该功能。
• 仅能在会话级别通过命令行参数覆盖环境变量（例如传入清空变量的 --settings 参数），且需要从第二个会话开始才生效（第一个会话用于拉取标志，第二个会话才会应用）。
• 无论哪种失败情况，程序都不会输出任何警告，只会静默跳过该文件。
• 通过第三方网关、AWS Bedrock 以及 Google Cloud Vertex AI 使用 Claude Code 时，也会因为无法解析该远程标志而遇到同样的问题。
临时解决方案
CLAUDE.md 原生支持 @path 导入语法，且该语法不依赖远程功能标志。在项目根目录下创建一个单行的 CLAUDE.md 文件，内容写入 @AGENTS.md，即可在关闭遥测和非必要流量的情况下正常加载 AGENTS.md。
为何这种设计不可接受
• 违背隐私设置预期：关闭遥测本应只影响诊断数据的发送，现在却静默破坏了读取本地文件的核心功能。
• 影响核心受众：多 Agent 协同用户以及企业级用户（使用 Bedrock、Vertex AI 或受合规策略限制禁用非必要流量的团队）通常对隐私和数据外流极为敏感，他们恰恰是 AGENTS.md 的主要目标用户，却因此无法正常使用该功能。
• 静默失败带来排查成本：工具没有任何警告提示，容易误导用户以为是模型没有遵循指令，导致用户浪费时间反复调整 Prompt。
作者的改进建议
• 解除本地读取与网络的绑定：读取本地文件不应依赖遥测。如果必须进行灰度发布，在检测到 AGENTS.md 但被跳过时，应在启动时输出明确的警告提示。
• 支持全局指令文件：目前该插件仅在项目目录及 .claude/AGENTS.md 中查找。希望支持类似 Codex 那样的全局用户级 AGENTS.md（例如放置在用户主目录下），而不是仅能通过 /import 命令单向复制。
• 原生支持跨 Agent 技能共享：Codex 支持直接读取项目中的 .agents/skills 和主目录下的 ~/.agents/skills。Claude Code 目前仅能通过 /import 复制技能到 .claude/skills 中，导致副本与源文件脱节。作者目前的解决办法是将 .claude/skills 软链接到 .agents/skills。
原文：https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/