# 关掉遥测，Claude Code 竟会忽略你的 AGENTS.md

**Summary:** Claude Code 2.1.277 虽然支持 AGENTS.md，但在禁用遥测的会话中可能完全不加载它。建议保留一行 CLAUDE.md 导入作为本地 fallback。

- Canonical: https://markhuang.ai/zh/news/claude-code-agents-md-telemetry-gate
- Language: zh-CN
- Author: [Mark Huang](https://markhuang.ai/about)
- Published: 2026-09-23
- Section: News
- Tags: Claude Code, AGENTS.md, 开发者工具, 遥测, 仓库指令
- Source: [Przemyslaw Szypowicz](https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/)
- License: https://creativecommons.org/licenses/by-nc/4.0/

---

![一份发光的本地指令文件通过直连路径抵达 AI 编码核心，而远程开关保持关闭](https://cdn.markhuang.ai/news/claude-code-agents-md-telemetry-gate/hero.webp)

*本地指令文件不该需要远程开关才能抵达编码智能体。*

Claude Code 2.1.277 新增了原生 `AGENTS.md` 支持。五天后，[Przemyslaw Szypowicz 发现了一个尴尬的附加条件](https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/)：一旦禁用遥测或非必要流量，他的本地指令文件就完全不会加载，而且整个过程没有任何警告。

我之前以为，[只要项目里已有 `CLAUDE.md`，Claude Code 就会把 AGENTS.md 当作备选方案](https://markhuang.ai/news/claude-code-agents-md-is-plan-b)。现在看来，在做这个选择前还有另一个分支：有些会话压根就没启用内置的 `agents-md` 功能。我不再把文件的存在当作 Claude 已经收到它的证据了。

## 本地文件竟依赖远程决策

Szypowicz 拆解了 2.1.280 的安装包，发现内置插件默认处于关闭状态，只有远程功能开关打开才可用。他随后创建了一个空目录，在 `AGENTS.md` 里放了个测试词，然后让 `claude -p` 在不读文件的情况下返回这个词。因为首次会话要获取开关状态，第二次才能用上，所以每种设置他都跑了两次。

只要设置了 `DISABLE_TELEMETRY=1` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`，测试词就从没出现过。清掉这两个变量后，从第二次会话开始功能就恢复了。这虽然是单个开发者的受控复现，不是大规模研究，但 Anthropic 自家的[当前文档也描述了同样的边界](https://code.claude.com/docs/en/memory#when-agentsmd-support-is-unavailable)：直接加载需要 2.1.277 或更高版本，且在会话无法获取功能开关时（包括禁用遥测的会话和某些第三方提供商设置）可能不可用。

Anthropic 仓库里[有个 9 月 20 日提交的开放 issue](https://github.com/anthropics/claude-code/issues/95690) 报告称，当非必要流量被禁用，或 Claude Code 通过某些网关、Bedrock 或 Vertex 运行时，功能开关无法解析为 true。这个 issue 只是缺陷报告的证据，并非 Anthropic 的官方确认。官方文档才是这一限制的更强依据。

> **Warning:**
>
> 危险之处不是崩溃。Claude Code 照样会回答，所以缺失的审查规则或禁止命令看起来像是模型不听话，其实指令根本没进上下文。

## 隐私控制不该改写本地行为

我能理解 Anthropic 为啥要把新加载器藏在功能开关后面。2.1.277 是一次渐进式发布，文档也提到安装或升级后的首次会话可能还不支持。但我没法接受的是这种静默回退——限制外发流量的开关，不该悄无声息地改变是否读取本地 Markdown 文件。

这种实现让调试变得更难，因为现在有三种解释会产生相似症状：Claude 可能加载了文件但没遵守；旁边的 `CLAUDE.md` 可能优先级更高；或者 `agents-md` 功能压根就没启用。要区分这些情况，得检查配置并植入测试词——对一个仓库约定来说，排查成本实在太高了。

明显的反驳是：功能开关只是临时的，加一行兼容性文件成本很低。文件成本确实低，但不确定性的代价不低。仓库指令可能包含测试命令、目录边界和审查要求。如果加载器跳过了它们，产品应该在启动时明确告知并说明原因。

## 我会保留这个简单的导入

Szypowicz 的变通方案正是我今天会采用的：在 `AGENTS.md` 旁边放个 `CLAUDE.md`，只写一行导入：

```text
@AGENTS.md
```

Anthropic 文档也推荐在原生支持不可用时走这条路，并说明当原生加载正常工作时，这个导入不会让 Claude 重复读文件。这样 `AGENTS.md` 仍是共享的事实来源，`CLAUDE.md` 只是一个小小的兼容适配层。

我会用一条无害又独特的指令测试这个安排，并在 Claude Code 2.1.280 或更高版本上检查 `/memory`。Anthropic 提到早期版本不会在 `/memory` 里列出直接加载的 `AGENTS.md` 文件，所以在 2.1.277 到 2.1.279 版本上测试词仍然重要。在官方限制消失前，我会在 Bedrock、Vertex、网关和禁用遥测的工作流里保留这个导入。

原生支持只有在团队生产环境用的隐私设置和提供商都能正确加载同一份仓库指令文件时才有意义。目前，我会保留这额外的一行——它比调试那些从未到达智能体的规则成本低得多。