AGENTS.md 与 AI 编码工具：从指令文件到工程兼容性的关键实践

最近技术圈在讨论一条新闻：Shopify CEO 考虑禁用 Claude Code，理由是它不兼容 AGENTS.md。先别急着站队，这个讨论真正值得关注的地方，不是某家公司要不要禁用一个工具，而是 AGENTS.md 这类项目指令文件，正在成为 AI 辅助编码里绕不开的基础设施。如果你在团队里推广过 AI 编码工具，大概率见过这种场景：工具能写代码，但总是不按项目规范来；你让它跑测试，它用了错误的命令；你让它改接口，它把历史约定全丢了。很多问题的根源，就是工具没有读项目指令，或者读错了文件。这篇文章会把 AGENTS.md 的作用、常见编写方式、Claude Code 安装配置与排查思路一起梳理一遍，最后聊聊企业真要裁剪这类工具时，应该先看哪些环节。

1. 事件背后的关键不是“禁用”，而是项目指令能不能被工具读取

1.1 “考虑禁用”这件事，别当成最终结论

这则消息最早出现在技术社区的讨论里，原文大意是 Shopify CEO 对 Claude Code 不满意，原因之一是它不兼容 AGENTS.md。这里有几个信息需要先分开：CEO 是“考虑禁用”，不等于已经禁用；不兼容的是“AGENTS.md”这种文件约定，也不等于 Claude Code 本身不能写代码。我更愿意把这个事件理解成一个信号：当 AI 编码工具进入真实企业仓库时，能不能遵守项目已有约定，已经成了选型的关键维度。

如果只是个人开发者把工具拿来做临时任务，不兼容 AGENTS.md 的影响可能很小。你的项目只有几个文件，模型靠目录结构和代码本身就能猜出大概。但企业项目不一样，仓库里有历史包袱、多模块依赖、团队约定、安全规范，AI 如果读不到这些，就会用“通用经验”替代“项目实际约定”。结果就是：生成的代码缩进统一，但调用链是错的；测试命令看起来合理，但在这个仓库里根本不存在；重构很积极，却把负责登录态的模块目录改错了。

所以，真正值得讨论的不是“某某公司要不要禁用工具”，而是“项目指令文件有没有成为 AI 工具的执行上下文”。如果答案是否定的，禁用只是时间问题，不一定是工具不行，而是它没法融入现有工程体系。

1.2 AGENTS.md 和 README、CLAUDE.md 有什么区别

很多团队到现在还把 AGENTS.md 和 README 混在一起，这是误会。README 面向的是人，包括新入职的工程师、外部贡献者、后续维护者。里面写项目目的、快速开始、目录结构、示例截图，核心是“让人看懂”。AGENTS.md 面向的是 AI 智能体，核心是“让 AI 在执行任务前知道该按什么规则干活”。两者内容可能重叠，但写法完全不同。

README 可以写“点击右上角按钮即可注册”，AGENTS.md 不适合这种表达。AGENTS.md 更合适的是“项目使用 pnpm 管理依赖，不要使用 npm install”“所有 API 请求必须经过 service 层，禁止在组件内直接 fetch”“测试命令是 pnpm test:unit，运行前必须先启动本地 mock 服务”。换句话说，AGENTS.md 应该是可执行、可检查、无歧义的约束，而不是项目介绍。

Claude Code 这类工具通常有自己的指令文件约定，比如 CLAUDE.md。从这次讨论来看，它可能没有主动读取通用的 AGENTS.md，所以才会出现“不兼容”的说法。对团队来说，最忌讳的是每个 AI 工具都有自己的文件格式，导致同一份规范要在多个文件里重复维护。

1.3 不兼容会带来哪些实际损失

第一是约定失效。假设你的 AGENTS.md 里明确规定“禁止直接修改 lock 文件”，AI 不读这个文件，就会在安装依赖后把锁文件改得面目全非。第二是命令污染。AI 自动执行构建、测试、格式化命令时，如果拿到的命令列表和仓库实际不符，不但任务失败，还可能留下脏目录。第三是审计缺口。企业环境里，谁让 AI 改了什么、按照什么依据改的，都要能查。项目指令文件是重要依据，工具不读，后期复盘就没有基线。第四是团队信任度下降。只要出现一两次低级破坏，管理员就会想“这东西到底能不能用”。

这些损失叠加起来，管理者做出“考虑禁用”的决定并不奇怪。但这里我想补一句：不兼容指令文件是可以通过配置、同步和规范化解决的，不一定非要用“禁用”来处理。关键在于先