Shopify CEO 因 AGENTS.md 考虑禁用 Claude Code：桥接明明能用，争议为何还没结束

2026-08-17，Anthropic 关闭了 Claude Code 仓库中的 issue #6235。这个请求已经开放 361 天，拿到 5,026 个赞和 384 条评论，诉求只有一个：让 Claude Code 原生读取 AGENTS.md。这份共享指令文件已有 60,000+ 个项目采用，Codex、Cursor 和 Windsurf 也早已原生支持。Boris Cherny 最终把 issue 标记为已完成，回复里给出的却是一种变通做法。

大约一周后，Shopify CEO Tobi Lütke 发帖称，他正考虑在 Shopify 禁用 Claude Code，直到它开始读取 AGENTS.md 和 .agents/skills。他认为坚持只读 CLAUDE.md 会带来问题，因为这种做法「有时会让使用不同工具的团队成员遇到脑裂问题」（原文：“sometimes leads to split brain problems when different team members use different tools.”）。

我们把官方给出的变通做法都测了一遍，结果确实能用。但事情并没有因此解决。

30 秒看懂结论

• 仓库里只有 AGENTS.md、旁边没有 CLAUDE.md 时，内容不会被加载。我们用 Claude Code 2.1.243 验证了这一点。这部分质疑完全成立。
• 官方文档里的两种桥接都有效。一种是在 CLAUDE.md 中只写一行 @AGENTS.md，另一种是把 CLAUDE.md 做成指向 AGENTS.md 的软链接。跨目录导入也能用，例如 @docs/AGENTS.md。
• Anthropic 文档说得很直接：Claude Code 读取 CLAUDE.md，不读 AGENTS.md（原文：“Claude Code reads CLAUDE.md, not AGENTS.md.”）。
• 到了 Windows，两种方式各有一个已知隐患。 文档建议 Windows 用户用导入，因为软链接需要管理员权限或 Developer Mode。但目前还有一个未关闭的问题报告称，Windows 上的 VS Code 扩展不会展开导入，代理看到的只是原样的 @AGENTS.md。同一仓库会因为操作系统和客户端不同，加载到不同的上下文。这正是 Lütke 所说的脑裂（split brain）。
• 实际配置时优先用导入垫片文件，别用软链接。配完后运行 /context 验证，不要凭感觉认定它已经生效。

事情是怎么走到这一步的

同一天关闭三个相关请求，看起来是一次有意的问题分拣，不像随手清理。关闭回复列出了两种桥接方式，并附上指令文件文档。Lütke 发帖后，有报道提到，一位 Claude Code 团队成员解释说，不同模型家族的行为特征不同，对指令组织方式也各有偏好。他也承认，同时维护多套配置会增加工作量。至于以后会不会原生支持，回应没有给出承诺，只是再次指向 @AGENTS.md 导入。

真正激化争议的是 issue 的处理结果。大家要的是一个还没开发的功能，issue 却以已完成关闭，相当于把仍有争议的产品选择当成已经解决的问题。变通做法只能回答「能不能接上」，回答不了「为什么每个仓库都得自己接」。

我们实测了所有持续生效的桥接方式

测试方法很简单。我们只在 AGENTS.md 里写入一条虚构的部署命令，然后在该目录启动全新的 Claude Code 会话，同时用 --disallowed-tools Read Glob Grep Bash … 禁掉所有读文件工具，再询问部署命令。代理此时没有办法自行打开文件。如果它能答对，内容只可能是在会话启动时进入了上下文。测试环境是 Claude Code 2.1.243、macOS、终端。

所以，流传很广的「Claude Code 拒绝读取 AGENTS.md」并不准确。只要桥接存在，它就能正常读取。它缺的是主动查找这份文件的行为。

即使不考虑 Windows，导入也是更合适的方案。软链接会让 CLAUDE.md 和 AGENTS.md 成为同一个文件，你便没有地方补充 Claude 专属指令。导入没有这个限制。前面放共享文件，下面继续写专属说明即可：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

导入路径以所在文件为基准解析，最多可以嵌套四层。反引号和围栏代码块里的导入标记会被跳过。启动时，导入内容会完整展开进上下文。因此，导入能帮你整理指令，却不会减少内容体积。共享文件很长时，这一点尤其要记住。

Windows 上的缺口

这部分此前几乎没人完整写过，却比「禁用工具」这句狠话更能说明 Lütke 为什么担心。

Anthropic 文档明确建议：Windows 创建软链接需要管理员权限或 Developer Mode，因此应改用 @AGENTS.md 导入。这个建议有充分理由。Windows 上的 git 只有开启 core.symlinks，才会把软链接真正检出为软链接。否则，指向 AGENTS.md 的 CLAUDE.md 可能变成一个普通文本文件，里面只有一行路径 AGENTS.md。代理最终加载到的全部内容，只是一个文件名。

问题是，另一条路也有人报告失败。仍未关闭的 issue #81189 指出，在 Windows 的 Claude for VS Code 扩展中，@AGENTS.md 没有被展开。代理看到的是这串原样文本，不是目标文件的内容。同一台机器上的同一仓库换到终端后，却可以正常工作。

这里必须把证据边界说清楚。#81189 来自一位用户的实测，Anthropic 没有确认。我们手边没有 Windows 机器，也无法自行复现。因此，这是一项需要防范的风险，还不能当成已经坐实的普遍结论。

把两件事放在一起，混合平台团队就很尴尬：软链接在 Windows 上本来就脆弱，官方建议改用导入，偏偏导入又有一份报告称它会在最常用的 Windows 编辑器里静默失效。两种故障都不报错，也不警告。代理只是没有读到大家以为它已经掌握的规则。

真正值得重视的正是这种故障。工具完全读不到指令，通常很快就能察觉。同一份指令只对部分成员生效，问题往往要到三周后的代码审查里才暴露。这会直接影响结果正确性，已经远远超出一般的使用麻烦。

持续桥接，还是一次性复制

另外还有两条路径，但它们解决的是迁移，不是持续同步。

表格后两种方式会留下当时的快照。一个月后再改 AGENTS.md，Claude Code 仍会读取旧副本，团队里的其他代理却已经拿到新内容。这样的脑裂更难发现，因为两个文件都存在，看上去也都有人维护。

想保留单一事实来源，就从表格前两项里选。我们亲自测试的是这两种持续桥接方式。后两种复制路径的行为来自 Anthropic 文档，并非我们的实测结果。

Shopify 真正在抱怨什么

他们没有说这件事技术上做不到。搭一个桥只需约 30 秒。问题在于，这 30 秒要由谁承担，又要重复多少次。

上面的每种桥接都需要逐个仓库主动开启，而且以后每个仓库都得一直保持正确配置。Shopify 有数千名开发者，代码库规模也很大。放到这种组织里，桥接不再是一项顺手修改，而是一套需要推广的政策。平台团队得把它铺到所有现有仓库，保证新仓库也有，还要通过 CI 检查。否则，只要某个仓库漏了垫片文件，代理就会在缺少团队规则的情况下工作，整个过程没有提示。

仓库越多、工具越多，这项维护负担就越重。Lütke 把它称为「复杂度税」。说白了，就是每接入一个工具，都要多维护一层本来可以省掉的兼容配置。CEO 会亲自谈到这件事，正因为这笔账最终落在平台团队身上，不会由某个开发者用 30 秒一次性解决。

Anthropic 也有合理理由，应该如实看待。指令文件并非换个文件名就完全等价。CLAUDE.md 支持 @ 导入，也有存放未提交个人说明的 CLAUDE.local.md。它会按层级合并组织策略、用户、项目和子目录文件。单体仓库（monorepo）里还可以用 claudeMdExcludes 排除其他团队的文件，并通过 .claude/rules/ 设置只对特定路径生效的规则。为另一种代理编写的文件，可能针对不同能力，也可能采用了另一种模型更适应的表达。自动加载这样的文件，有可能把一批不了解 Claude Code 加载规则的指令直接带进来。

这些理由足以支持继续把 CLAUDE.md 作为功能完整的主文件。可如果仓库根本不存在 CLAUDE.md，为什么不能退回读取 AGENTS.md？现有解释还无法充分回答这个更窄的问题。Lütke 发帖次日提交的 issue #89825，请求的正是这种回退行为。只实现这一小步，无需改变其他加载规则，也足以消除 Shopify 面临的主要问题。

现在应该怎么配

单个仓库，或所有成员都在同一平台。 用导入垫片文件。让 CLAUDE.md 第一行写 @AGENTS.md，下面再放 Claude 专属说明。随后启动新会话，运行 /context，确认「Memory files」中出现 CLAUDE.md。这一步不能省。既然失败时没有提示，验证本身就是配置流程的一部分。

团队里有 Windows 开发者。 仍然使用导入垫片文件，并至少让一位真实用户在 Windows 的 VS Code 扩展中验证一次。启动会话，让代理复述 AGENTS.md 里一条容易辨认的句子。如果答不出来，很可能碰到了 #81189，Windows 开发者此时没有拿到共享指令。这里不要用软链接。

单体仓库（monorepo）。 根目录 AGENTS.md 放全组织通用的信息，各包的 AGENTS.md 只写本地差异，再用各目录下的 CLAUDE.md 垫片文件复制这套层级。我们的 AGENTS.md 模板 给出了具体结构。如果其他团队的上级文件不断进入你的上下文，可以在 .claude/settings.local.json 中为 claudeMdExcludes 配置通配模式。

负责统一落地的平台团队。 把垫片文件纳入仓库模板，并像检查许可证文件一样用 CI 检查它。两项检查就够：CLAUDE.md 是否存在，它是否引用 AGENTS.md。这点成本远低于花一个下午追查代理为什么忽略了明明写在文件里的规范。

无论选哪种方式，都要控制文件长度。这些内容会进入每个代理的每次会话。Anthropic 自己也建议把每个文件控制在 200 行以内。桥接本身几乎没有成本，真正昂贵的是你让它搬过去多少内容。

延伸阅读

• CLAUDE.md 与 AGENTS.md：Claude Code 到底读哪个？：标准现状，以及什么时候该让哪个文件成为主文件。
• AGENTS.md 模板：精简起步模板、垫片文件和 monorepo 写法。
• 如何写好 CLAUDE.md：每次会话都会加载的文件，哪些内容才值得占位置。
• Anthropic 删掉 Claude Code 80% 的系统提示词，效果反而更好：为什么更短的指令文件得分更高。

来源

1. 功能请求：支持 AGENTS.md，anthropics/claude-code issue #6235
2. 支持 AGENTS.md 和 .agents/skills，issue #31005
3. Windows 版 VS Code 扩展无法在 CLAUDE.md 中导入同目录 AGENTS.md，issue #81189
4. 没有 CLAUDE.md 时，根目录 AGENTS.md 不会在会话启动时自动加载，issue #89825
5. Claude 如何记住你的项目，Claude Code 文档
6. Tobi Lütke 在 X 上的发帖
7. Shopify CEO 威胁禁用 Claude Code，Anthropic 此前已关闭功能请求，The New Stack
8. Shopify CEO 威胁放弃 Claude Code，Anthropic 回应 AGENTS.md 兼容性争议，BigGo Finance
9. AGENTS.md

常见问题

Claude Code 会读取 AGENTS.md 吗？ 不会主动读取。Anthropic 文档明确写道：Claude Code 读取 CLAUDE.md，不读 AGENTS.md（原文：“Claude Code reads CLAUDE.md, not AGENTS.md.”）。我们在 Claude Code 2.1.243 上确认过：如果仓库只有 AGENTS.md，旁边没有 CLAUDE.md，会话启动时不会加载其中的内容。通过桥接则可以读取。一种是在 CLAUDE.md 中写一行 @AGENTS.md，另一种是把 CLAUDE.md 做成指向 AGENTS.md 的软链接。两种方式实测都有效，指向子目录文件的导入也有效。

Anthropic 为什么关闭请求支持 AGENTS.md 的 issue #6235？ Boris Cherny 于 2026-08-17 将它关闭为已完成，回复中给出了导入和软链接两种变通做法，并附上相关文档。此时该 issue 已开放 361 天，获得 5,026 个赞和 384 条评论。相关请求 #62371 和 #84830 也在同一天关闭。Tobi Lütke 发帖后，有报道援引 Claude Code 团队成员的回应：不同模型家族偏好的指令组织方式不同，同时维护多套配置也确实增加工作量。不过 Anthropic 没有明确承诺会不会加入原生支持。

Shopify CEO 到底说了什么？ Tobi Lütke 在 X 上说，他正考虑在 Shopify 禁用 Claude Code，直到 Anthropic 改变主意，开始读取 AGENTS.md 和 .agents/skills。他还说，只读 CLAUDE.md「有时会让使用不同工具的团队成员遇到脑裂问题」（原文：“sometimes leads to split brain problems when different team members use different tools.”），并认为这种做法没有必要。他说的是正在考虑，并未宣布正式政策。

应该用导入垫片文件，还是软链接？ 绝大多数情况都该用导入。软链接方式下，CLAUDE.md 和 AGENTS.md 实际是同一个文件，没有地方再写 Claude 专属指令。Windows 创建软链接还需要管理员权限或 Developer Mode，所以 Anthropic 文档也建议 Windows 用户优先使用导入。导入方式可以先放共享指令，再在下面补充 Claude 专属说明。

AGENTS.md 的变通做法在 Windows 上会失效吗？ 两条路各有已知问题。软链接需要管理员权限或 Developer Mode，而且 Windows 上检出的软链接文件可能只是一段路径文本。另有一个仍未关闭的 issue 报告称，Windows 版 Claude for VS Code 扩展不会展开 @AGENTS.md 导入，代理看到的是原样文本。同一仓库在终端里却能正常工作。这只是一位用户的实测报告，Anthropic 尚未确认。团队应在实际使用的每个平台上通过 /context 验证，不能想当然。

/import 命令和 @AGENTS.md 垫片文件是一回事吗？ 不是。v2.1.213 起提供的 /import 会把 AGENTS.md 等文件一次性追加到 CLAUDE.md，同时迁移 MCP 服务器、命令、子代理和技能。它做的是迁移，不是链接。以后再改 AGENTS.md，Claude Code 读到的内容不会跟着更新。@AGENTS.md 导入和软链接都会在每次会话启动时重新读取文件。想维护单一事实来源，就该用这两种方式之一。