工具

Claude Code 的 AGENTS.md 只在遥测开启时读取,Anthropic 已修

一个被忽略的细节:Claude Code 是否读取项目级 AGENTS.md,取决于遥测开关。374 分 HN 热议背后,是 AI 编程工具里遥测与功能行为的隐性耦合。

字号

开发者把 telemetry 关掉,本意是「少上传点数据」。结果他顺手写好的 AGENTS.md —— 那个本该被 Claude Code 读进去的项目级指令文件 —— 完全没生效。szypowi.cz 上的这篇博客 把代码扒开一看,发现问题更尴尬:Claude Code 读 AGENTS.md 的逻辑,挂在 telemetry 开启那条分支上。

Anthropic 已经修复。这件事本身不大,但它指向一个正在浮现的工程组织问题。

事件本身:AGENTS.md 不是「配置」,是「遥测开关的副产物」

事情起点很普通。有人在 Claude Code 里放了一份 AGENTS.md,想给模型喂项目规范、代码风格、提交习惯之类的指令。文件没报错,日志看着也正常,但模型对 AGENTS.md 里的内容完全无感。

关掉 telemetry,再开。文件生效了。

szymon (博客作者) 觉得不对劲,就去翻 Claude Code 的源码逻辑。结果发现:读取 AGENTS.md 的代码路径,确实和 telemetry 的开关耦合在一起。telemetry 关 → 走不到那段读文件的代码。

这不是 bug 报告里常说的「误触发」或者「边界条件没覆盖」。这是从代码组织层面上看出来的一个设计决策 —— 或者说,一个埋得太深的副作用。

Anthropic 收到反馈后修了。但修复本身不等于解释 —— 官方没说「我们当初为什么这么写」,也没说「还有哪些功能在 telemetry 关闭时会被静音」。这是后话,先看为什么这件事在 HN 上能拿到 374 分、211 条评论。

HN 讨论地址: https://news.ycombinator.com/item?id=49814947

这个 bug 为什么重要:遥测和功能耦合在一起

把视角从「文件没读到」拉到「遥测和功能跑在同一段代码上」。

开发者关掉 telemetry,典型动机是隐私 —— 不想让代码片段、提示词、上传的文件被服务端拿到。这是合理的、甚至是企业合规场景下必需的选择。结果呢?关掉它,顺带把「读取项目级指令」这个看上去毫无隐私关联的基础功能,一起关掉了。

更深的问题是:没人会在产品文档里告诉你这件事。

你打开 Claude Code 的设置面板,看到 telemetry 是个开关,大概率默认理解是「数据采集开关」。它不会写「同时也会关闭项目配置文件读取」。这种隐性耦合是信任的杀手 —— 不是因为 Anthropic 有恶意,而是因为开发者根本没有渠道在打开开关之前就知道这一连串后果。

类似的隐式依赖大概率不止这一处。等下具体说。

AGENTS.md 是什么,和 .cursorrules 什么关系

先科普一下这个文件。AGENTS.md 是 2025 年中开始流行的一个约定:放在项目根目录,给 AI Agent / AI 编程工具读的项目级指令文件。格式上模仿 README.md,但内容是给模型看的,不是给人看的。

典型内容长这样:

# AGENTS.md

## Build & Test
- pnpm install
- pnpm test

## Style
- 2-space indent
- No `any` in TypeScript
- Prefer composition over inheritance

## Don't
- 不要修改 `migrations/` 目录下的文件
- 不要 commit `.env`

类似机制在其它工具里也有,只是文件名不一样:

  • Cursor: .cursorrules,放在项目根目录
  • Aider: CONVENTIONS.md,通过 --read 参数显式加载
  • Cline / Continue: 通过自定义 system prompt 注入
  • Claude Code: AGENTS.md 或 CLAUDE.md(同一个文件,两个名字都认)

关键差异在加载路径。Cursor 和 Cline 走的是配置解析层 —— 你打开项目、工具初始化、AGENTS.md(或者同类文件)就被读进来,逻辑独立于任何「遥测」或「数据上传」开关。Aider 更直接,要你显式传文件路径,也不存在耦合问题。

Claude Code 这次暴露的是另一条路径 —— 读取行为挂在别的开关后面。这种组织方式在快速迭代的产品里不罕见,但发生在配置加载这条核心链路上,问题就被放大了。

社区反应:374 分、211 条评论在吵什么

HN 上这个帖子热度不低,讨论大致分了三派。

第一派:Anthropic 内部代码组织有问题。 代表观点是 —— 读 AGENTS.md 是一个「应该 100% 走确定性路径」的功能(无副作用、无随机性),把它和 telemetry 这种「可关闭、可变」的开关绑在一起,是糟糕的代码架构。持这派观点的多是有大厂工程背景的开发者,他们见过类似 anti-pattern 在生产环境里引发的更严重事故。

第二派:open-source / CLI 工具的天然缺陷。 这派觉得 Claude Code 的代码虽然不完整开源,但能看到的那部分也暴露了快速迭代产品的常见问题 —— 功能加得太快,内部重构没跟上。一个匿名用户评论说:「这不是 bug,这是 velocity tax。」翻译过来:你跑得越快,埋得越深。

第三派:更深的反思 —— AI 工具的开关到底控制了什么。 这派的讨论最有意思。他们把这件事放到更大的语境里:LLM 工具普遍有「遥测 / 数据收集」开关,但用户根本不知道开关背后连着多少功能行为。某个开关可能是「数据收集」、也可能是「功能开启」、还可能是「模型版本选择」、甚至是「提示词缓存策略」。这种不可见性才是问题根源。

我比较认同第三派。前两派讨论的是「为什么这次会出 bug」,第三派在问「这种类型的 bug 怎么系统性地避免」。

对开发者的实操影响:你现在该开还是关遥测

短期建议,如果你已经在用 Claude Code:升级到最新版本。修复已经合入,但具体哪个版本号发布的,szypowi.cz 的博客和 HN 评论里都没点透,建议直接查 Claude Code 的 release notes 或 GitHub commits。

如何验证修复生效?最直接的方式:关掉 telemetry,启动 Claude Code,在项目根目录放一份测试用的 AGENTS.md,内容随便写一行独特的话(比如 print("AGENTS_MD_TEST_OK")),然后问 Claude「根据 AGENTS.md 里的指示执行一下」。如果它真的去执行了那行代码,说明读取链路独立于 telemetry 了。

遥测开关本身开不开:这个看你的场景。

  • 开遥测:能拿到产品改进、能优先体验新功能、需要把使用数据反馈给 Anthropic。
  • 关遥测:在乎代码片段 / 提示词不被上传、所在企业有合规要求、想要更可预测的行为。

我的倾向:在 AI 编程工具越来越像「协作者」而不是「工具」的当下,默认关掉数据收集、但开启必要功能 —— 这件事 Anthropic 们得给一个明确的承诺,开关的副作用必须在文档里穷举。这件事不能靠用户自己扒代码。

可以关注的几个位置(具体名字以官方文档为准):

  • ~/.claude/settings.json 里的 telemetry 相关配置
  • CLI 命令里的 telemetry 相关 flag
  • 启动日志里 telemetry 状态的输出

编辑思考

这件事不是「Anthropic 又翻车了」那么简单。它指向一个具体的工程问题:AI Agent 工具的「功能开关」和「数据开关」是不是该解耦?

Cursor、Aider、Cline、Claude Code 这一类工具都在快速迭代 —— 每周都有新功能、新模型、新权限。新功能往现有的「读取配置 / 初始化环境 / 加载策略」这条链路上挂的时候,挂在哪里、依赖什么状态、是否有副作用,这些决定每一个都直接影响开发者的工作流。Claude Code 这次「配置读取挂在 telemetry 分支上」,不是孤立事件,是这类工具普遍的代码组织问题的早期信号。

我的判断:未来 12-18 个月,这一类「隐性耦合」事件会越来越多,而不是越来越少。 原因很简单 —— Agent 工具的产品形态还在剧烈变化,「什么是核心功能」的定义本身在移动。今天的核心功能,明天可能就变成「实验性」;今天的实验性,明天可能成为默认行为。在这种变动下,「哪个开关连哪个功能」就变成了一笔糊涂账。

这件事和过去的工具 bug 不同:过去「工具出 bug」通常是功能行为出错 —— 输出有偏差、计算结果有 bug。这次是元层面的问题 —— 工具的「什么是 bug」这个判断标准本身,在用户和厂商之间产生了分歧。用户以为「AGENTS.md 必须被读取」,但代码里它不是这个语义。

短期靠审计:用户社区、第三方安全研究者会持续扒代码、提 issue、暴露问题,这是半开源工具的优势。长期需要行业级透明度 —— 我希望看到的是:每个开关都有明确的「影响范围声明」,文档里穷举副作用;配置加载链路独立于数据收集链路,作为工程硬性要求;第三方审计成为 agent 工具的标配,类似现在的 SOC2、GDPR 合规审计。

能不能完全解决,我有保留。LLM 工具的可观察性传统上就比传统软件弱 —— 模型本身是黑盒,围绕模型的产品也越来越黑盒。Claude Code 这次修复了,但修复不意味着这类问题消失。

来源: https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/