最近 AI 编程圈最值得关注的信号不是某个模型又在榜单上刷新了几分而是一位头部科技公司的 CEO 在公开场合放话正在考虑禁用 Claude Code理由是它对 AGENTS.md 的支持不能让人满意。这个信号的分量在于它把问题从“开发者个人用哪个工具顺手”直接抬高到了“大型技术团队如何治理 AI 编码行为”的层面。Claude Code 是过去一年口碑最被看好的终端 AI 编码代理之一它以对话式编程、自主执行命令、修改文件的能力著称。但当仓库里已经存在 AGENTS.md 时Claude Code 的读取与执行表现和其他一些工具并不总是一致。对单个开发者来说这可能只是“偶尔不听话”对一个拥有大量仓库、并行推进多个 AI 编码任务的组织来说这就是行为不可控。AGENTS.md 正在成为 AI 协作编码时代的事实标准文件。它本质上是一份专门写给 AI 代理看的 README告诉 AI 这个项目怎么构建、怎么测试、代码风格是什么、哪些目录不能动。OpenAI Codex 把 AGENTS.md 作为一等公民支持越来越多的开源仓库也开始在根目录维护 AGENTS.md。也正因为如此一家大型电商技术公司的 CEO 会为了这个文件而考虑禁用某个热门工具——规则文件的兼容性已经不只是技术细节而是 AI 编程工程化的地基问题。这篇文章会围绕这条新闻展开先讲清楚 AGENTS.md 到底是什么、为什么它越来越重要再分析 Claude Code 与 AGENTS.md 的兼容问题出在哪接着给出最关键的实操内容Claude Code 的安装配置、AGENTS.md / CLAUDE.md 的编写方法、如何验证规则真正生效以及多工具团队落地时的最佳实践。如果你正在用 Claude Code 写项目或者准备把 AI 编码工具引入团队这篇文章值得读完再动手。1. 从 Shopify CEO 的吐槽说起AGENTS.md 触动的是谁的神经1.1 为什么一条吐槽能刷屏这条消息能刷屏首先是因为身份特殊。Shopify 是电商基础设施公司工程体量庞大技术选型一贯偏务实。CEO 亲自下场讨论某个 AI 编码工具的规则兼容性问题说明 AI 编程已经从“业务团队试点”进入了“最高管理层过问”的阶段。其次是因为吐槽对象特殊。Claude Code 的口碑建立在真实开发效率上很多开发者用它的第一反应是“终于有人把 AI 编码做成了能替我跑完整个流程的终端工具”。它可以读取仓库、分析代码、执行命令、查看报错、修改文件像一个住在终端里的 AI 工程师。正因如此当它被一家大型公司的 CEO 点名“不遵守 AGENTS.md”时社区才会认真思考这到底是一个工具的小毛病还是所有 AI 编码工具都会遇到的结构性问题1.2 从单人工具到团队规范过去一年AI 编程工具最大的变化不是模型更强而是工作方式变了。早期 AI 编程助手以“补全代码”“聊天解释”为主本质是人用工具现在的 Agent 型工具会直接操作仓库本质是工具替人干活。一旦工具开始替人干活它的行为就必须有边界、有规则、可预期。AGENTS.md 正是在这个背景下被推向前台的。它不是某个公司的私有格式而是一个可以被任何 AI 工具读取的仓库级说明文件。一个团队一旦引入三五种 AI 编码工具如果每个工具各自读各自的配置、各自理解各自的规则那么“AI 生成代码的质量”就会变成一个黑盒问题。AGENTS.md 想解决的就是这个用一份所有人都能读、所有工具都能读的文件把 AI 的行为约束到团队可接受的范围。1.3 核心问题可预测性我们经常关注 AI 编码工具的上限——它能多快写出多复杂的代码。但团队关注的是下限——它会不会突然做出一个危险的修改。AGENTS.md 就是用来托住这个下限的告诉 AI 哪些命令是安全的、哪些目录不能碰、哪些风格必须遵守。Claude Code 的性能上限很高但如果它在一个已有 AGENTS.md 的项目里表现不稳定团队就不得不重新权衡。从公开信息看Shopify CEO 的反馈焦点也正是这一点工具本身不错但前提是它必须尊重仓库里已经写好的规则否则再好的能力也无法在大型工程体系里被信任。2. AGENTS.md 到底是什么给 AI 代理看的 README2.1 先看一个没有规则文件的项目假设你接手一个中型 Python 后端项目仓库里没有任何 AI 规则文件。你让 Claude Code 修一个 bug它大概率会猜测试命令是pytest但项目实际上用的是python -m unittest按自己的偏好重排 import导致 diff 巨大和团队风格不一致不知道src/legacy/目录是不能动的历史包袱直接改坏了核心逻辑。这些问题的根源不是模型笨而是缺少上下文。模型不知道这个仓库怎么跑、哪里能改、哪里不能改。传统项目靠 README 和团队口口相传AI 代理如果每次都要靠“猜”效率再高也会出乱子。2.2 AGENTS.md 的定义与结构AGENTS.md 是一份放在仓库根目录或docs/目录的 Markdown 文件专门给 AI 编码代理和人类开发者阅读。它的典型内容包括项目说明与技术栈构建、测试、Lint 等常用命令目录结构与架构约定编码风格与必须遵守的规则明确禁止 AI 自动执行的操作。它与 README 的最大区别是阅读对象。README 主要面向人类会解释“这是什么、怎么用”AGENTS.md 主要面向 AI会写“你该怎么在这个仓库里工作”。它更像是把团队对 AI 协作的期望固化成一份可版本化、可审查、可复用的工程资产。2.3 AGENTS.md、CLAUDE.md、.cursorrules 有什么区别很多开发者第一次接触这几个文件时容易混淆下面用一个表格梳理文件主要读者来源定位AGENTS.mdAI 编码代理Codex、Claude Code 等社区事实标准多工具支持仓库级通用规则CLAUDE.mdClaude CodeAnthropic 官方支持Claude 专属记忆与行为规范.cursorrulesCursor 编辑器Cursor 官方编辑器级提示词已逐步向.cursor/rules迁移从表格能看出这三者不是完全等价的关系。AGENTS.md 更接近“整个仓库的公共契约”CLAUDE.md 更接近“某个工具的项目级指令”.cursorrules 则是历史产物。在理想状态下团队应该以 AGENTS.md 为主CLAUDE.md 只写 Claude 专属的工作偏好但在实际项目中很多团队会让多个文件并存于是冲突概率也随之上升。3. Claude Code 与 AGENTS.md 的兼容问题出在哪3.1 不是“不读”而是“读得不够稳定”从公开资料和社区反馈来看Claude Code 本身具备读取 AGENTS.md 的能力甚至在较新版本中还会主动提示发现的规则文件。那为什么还有“不兼容”的说法关键在于“兼容”不只等于“能读”还包含三个层面的稳定性发现机制是否会自动发现根目录或docs/下的 AGENTS.md而不是要求用户手动导入优先级当 AGENTS.md、CLAUDE.md、系统提示词三处指令冲突时谁说了算这个规则是否透明、可解释上下文管理AGENTS.md 很长时工具如何压缩、抽取、保留关键规则会不会出现规则被裁剪导致行为偏差任何一个层面不稳定在开发者视角里都会被归为“兼容问题”。尤其当团队同时使用多个 AI 编码工具时同一份 AGENTS.md 在 Codex 里表现得很好在 Claude Code 里却时灵时不灵那么“不兼容”的标签就会被贴上身。3.2 典型冲突场景结合团队真实使用情况比较典型的冲突场景有三个场景一规则优先级冲突。AGENTS.md 写“所有数据库迁移必须走迁移工具”CLAUDE.md 或用户的某个历史会话里写“直接用 SQL 修改”。Claude Code 在执行时可能优先采用了更具体或更靠近会话上下文的指令而团队认为 AGENTS.md 才是全局标准。场景二文件路径识别差异。AGENTS.md 放在docs/AGENTS.mdClaude Code 没有自动扫描到而另一个工具会自动扫描常见路径。同一个仓库不同工具的行为不一致AI 生成的结果自然也对不齐。场景三长文件被截断。AGENTS.md 写得很详细超过了一定上下文窗口后Claude Code 可能只保留了前半部分的架构说明后半部分的“禁区”规则被丢弃于是 AI 触碰了不该碰的目录。这些问题的本质是规则文件生态还处于早期各工具的解析方式、优先级逻辑、加载策略没有统一。对一个单体开发者来说可以忍受但对一个同时并发几十个 AI 任务的大型团队来说就是不可接受的不确定性。3.3 核心影响团队不敢把规则交给 AI这里的核心影响不是“ Claude Code 能不能用”而是“团队敢不敢把规则正式交给 AI”。一个工具如果只是“偶尔不听话”开发者可以人工兜底但如果规则文件本身成为了不可靠因素那么团队就不可能围绕 AGENTS.md 建立自动化流程。从这个角度看Shopify CEO 的表态更像是一声提醒AI 编码工具的下一阶段竞争点不是单点代码生成能力而是对团队规则的理解与服从。谁能在多文件、多指令、多上下文的复杂场景下稳定地遵守仓库规则谁才有资格进入大型工程体系的核心流程。4. Claude Code 安装与基础环境准备4.1 环境要求Claude Code 目前以命令行工具为主也有桌面端和 VS Code 插件。在安装之前建议先确认环境满足基本要求操作系统macOS、Linux 比较常见Windows 建议使用 WSL 或虚拟机环境Node.js建议使用 Node.js 18 或更高版本具体以官方文档为准网络环境需要能正常访问 Anthropic 服务且账号所在区域在官方支持范围内账号准备Anthropic 账号、Claude 订阅Pro/Max或者 Anthropic API Key。如果项目里已经用了 Claude Code建议先确认当前版本避免后续配置项不匹配。4.2 命令行安装Claude Code 的官方安装方式是通过 npm 全局安装# 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 查看版本确认安装成功 claude --version # 进入交互式编程会话 claude如果 npm 下载速度不理想可以临时切换 npm 镜像源来安装但平时建议保持默认 registry。安装完成后在终端直接输入claude即可进入交互式对话界面。4.3 认证与 API Key第一次运行 Claude Code 时会要求登录认证。常见的两种方式方式一登录 Claude 账号使用订阅额度。适合个人开发者对高频使用比较友好。方式二使用 Anthropic API Key 计费通过环境变量注入export ANTHROPIC_API_KEYyour_api_key_here企业场景下如果组织策略限制订阅访问一般会改用 API Key并走企业内部的审批和密钥管理流程。注意API Key 是敏感凭证不要提交到 Git 仓库也不要写进 AGENTS.md、CLAUDE.md 这类会进入版本库的文件。4.4 桌面版与 VS Code 插件除了 CLIClaude Code 还提供桌面应用和 VS Code 插件。VS Code 用户可以直接在扩展市场搜索 Claude Code 官方插件安装后重启窗口即可。桌面版可以从 Anthropic 官方渠道下载适合不习惯终端的开发者。使用 VS Code 插件时通常会在侧边栏看到任务输入面板也可以直接在集成终端中运行claude命令。两者的核心逻辑一致都是让 Claude 读取当前工作区、理解代码并执行修改。4.5 升级与版本确认Claude Code 迭代速度很快遇到问题先升级版本通常是最有效的排查方式# 更新到最新版本 claude --update # 查看当前版本 claude --version从社区反馈看很多 AGENTS.md 相关的行为差异会在版本更新后得到改善或调整。遇到规则不被遵守时不要急着否定工具先看看是不是版本太旧。5. 让 Claude Code 真正遵守项目规则AGENTS.md 与 CLAUDE.md 搭配5.1 在仓库中编写 AGENTS.md要让 Claude Code 遵守规则第一步是把规则写清楚。下面是一个比较完整的 AGENTS.md 示例适合中型 Python 项目# AGENTS.md ## Mandatory Commands - Install dependencies: poetry install - Run tests: pytest tests/ -q - Run linter: ruff check src/ tests/ - Run formatter: ruff format --check src/ ## Repository Structure - src/app/ — 核心业务代码任何修改需要说明理由 - src/legacy/ — 历史遗留模块禁止改动 - migrations/ — 数据库迁移只能通过迁移工具生成 ## Rules for AI Agents - Do not modify src/legacy/** or migrations/** without explicit user confirmation - All public functions must have docstrings - Follow existing import order: standard library, third-party, local - If you are not sure about a behavior, ask before acting - Never run git push automatically; stop after creating a local commit这个例子最大的特点是“可执行”。每一条规则都是 AI 能直接判断对错的而不是“请写得优雅一些”“请考虑性能”这种模糊表达。AI 代理擅长执行约束不擅长理解潜台词。5.2 编写 CLAUDE.md 作为 Claude 专属约束Claude Code 对 CLAUDE.md 的支持更成熟。建议在项目根目录添加一份 CLAUDE.md专门描述 Claude 在工作时的工作方式# CLAUDE.md ## Workflow - Always read AGENTS.md before making changes - Before large refactoring, explain the plan in a few bullet points - Run tests after every change, not only at the end ## Do Not - Do not remove # TODO comments - Do not rewrite code style across multiple files - Do not create new dependencies unless requestedCLAUDE.md 的定位是“Claude 专属工作偏好”它不应该重复 AGENTS.md 里的全部内容而是补充那些“只有 Claude 才需要特别注意”的约定。比如某些项目希望 Claude 先给计划再动手就可以写在这里而 AGENTS.md 里不需要包含这些。5.3 指令冲突时如何确认优先级当 AGENTS.md、CLAUDE.md 和当前对话中的临时指令冲突时最好在规则文件里显式声明优先级。例如在 AGENTS.md 顶部加入## Rule Precedence 1. User instructions in the current conversation (highest) 2. AGENTS.md (repository-level contract) 3. CLAUDE.md (tool-specific preferences) 4. Default model behavior (lowest)这样写的好处是AI 在遇到冲突时有一个清晰的决策依据开发者审查时也能推断出 AI 为什么会做出某个选择。没有优先级说明冲突就只能靠模型“当场判断”结果不可控。5.4 引入 Skill 扩展 Claude Code 能力如果你发现 Claude Code 在执行某一类任务时总是缺少固定步骤可以考虑使用 Skill。Skill 可以理解为打包好的技能模板把某一类任务的做法封装成可复用的目录。目录结构通常是.claude/skills/review-python/ ├── SKILL.md └── prompt.mdSKILL.md 示例--- name: review-python description: Review Python code for style, correctness, and security issues. --- Follow the checklist in prompt.md and output a review report with severity levels.Skill 更适用于重复发生的任务比如代码审查、依赖升级检查、发布前自检等。它能减少每次对话里都要重复粘贴规则的成本。不过不同版本对 Skill 的加载方式有差异配置时以官方文档为准。5.5 可选实践用 CC Switch 切换模型接入Claude Code 默认使用 Anthropic 官方模型。社区中存在 CC Switch 这类开源配置管理工具可以在不同模型 API 配置之间快速切换例如把请求转发到兼容协议的第三方模型服务。这对想降低 API 成本、做模型对比或替换模型后端的开发者是有用的。如果要通过命令行配置兼容端点一般会使用环境变量方式export ANTHROPIC_BASE_URLhttps://your-compatible-endpoint export ANTHROPIC_API_KEYyour-key这里需要提醒第三方模型的真实能力和合规性是参差不齐的。如果模型标识不符合当前 Claude Code 版本的识别规则运行时会提示类似“model is not a model this version of claude code recognizes”的报错届时需要把模型名改成服务商实际提供的名称或升级工具版本。合理的管理方式是把不同服务商配置存成多套 profile通过 CC Switch 一键切换既保留官方模型也保留备选模型。6. 验证规则是否生效从“能跑”到“听话”6.1 三个快速验证问题安装好 Claude Code、写好规则文件之后不要急着让它写大功能。先用几个小问题验证它是否真的“读懂了”规则问它“根据项目规则我应该用什么命令运行测试测试框架是什么”看回答是否来自 AGENTS.md而不是模型自己猜的pytest。让它执行一个命令观察它是否先用 AGENTS.md 里规定的命令而不是临时换一条。给它一个“禁止修改”的目录看它是否拒绝或者先向你确认而不是直接改。这三个问题分别对应“发现规则”“遵循命令”“遵守禁区”是最容易暴露兼容问题的三个环节。6.2 使用命令行验证可以用非交互模式直接提问# 使用 -p 模式向 Claude 提问不进入交互 claude -p 根据项目规则我应该用什么命令运行测试也可以进入交互模式主动要求它先加载规则再回答claude 请先阅读仓库根目录的 AGENTS.md然后告诉我你理解的规则。如果 Claude 的回答与 AGENTS.md 内容一致说明规则至少被读取了。接下来再让它实际执行一个命令确认行为层面也一致。6.3 失败时的第一排查顺序如果发现 Claude Code 没有遵守 AGENTS.md建议按以下顺序排查确认文件位置是否在官方支持的范围内通常推荐放在仓库根目录确认文件编码正常不要有特殊 BOM 或异常字符尝试缩短 AGENTS.md观察行为是否变化排除上下文裁剪导致的规则丢失检查 CLAUDE.md 中是否存在与 AGENTS.md 冲突的指令升级 Claude Code 到最新版本后重试。多数情况下问题出在文件位置、规则过长或文件冲突真正属于“工具完全不支持 AGENTS.md”的情况反而少见。7. 常见问题与排查思路下面整理了一份常见问题排查表覆盖安装、认证、运行和规则生效几个环节问题现象可能原因排查方式解决方案npm 安装失败或超时Node.js 版本过低 / 网络不稳定 / registry 异常检查node -v、npm config get registry升级 Node.js配置可信 npm 镜像源运行时报 529服务端负载过高查看提示信息、等待重试稍后重试或临时切换备用模型配置提示当前地区不可用账号区域或网络环境不在官方支持范围内查看官方支持列表更新账号信息或使用合规网络环境以官方文档为准提示 organization has disabled ...企业订阅策略限制咨询企业管理员使用本机 API Key 或走企业审批流程模型名称报错 not recognized配置的模型标识不存在或拼写不一致查看模型服务商提供的模型列表改为服务商实际提供的模型名或升级工具版本AGENTS.md 被“无视”文件路径不对 / 规则过长被裁剪 / 与 CLAUDE.md 冲突分步提问验证调整文件位置压缩规则明确优先级这张表覆盖的是真实使用中最常见的几条路径。遇到问题时第一原则是“先看提示再查版本最后查配置”不要一上来就怀疑规则文件本身也不要一上来就重装工具。8. AGENTS.md 团队落地的工程建议8.1 把 AGENTS.md 当产品文档维护AGENTS.md 不是写完一次就结束的临时文件。项目结构一变、命令一变、架构一调整AGENTS.md 就必须同步更新。比较推荐的做法是把它纳入 review 流程任何改命令、改目录、改代码规范的 PR都要同步检查是否需要更新 AGENTS.md。在大型团队中可以指定一名负责人或一个小组负责规则文件的统一维护避免多个仓库各自为政。模板化是提升效率的关键团队可以沉淀一份标准 AGENTS.md 模板新仓库直接复制再按项目调整。8.2 规则要可执行不要写感想AGENTS.md 里最容易出现的问题是“写感想”。比如# Bad - 请保证代码质量 - 注意系统设计 - 不要写烂代码这种规则对 AI 没有任何约束力因为它无法被验证。正确的做法是写“可被验证的约束”# Good - 所有公开函数必须包含 docstring - 不允许修改 src/legacy/** 目录 - 修改数据库表结构必须使用迁移工具并生成迁移文件判断一条规则是否合格最简单的方法是问自己如果 AI 违反了这条规则我能不能通过 diff 或命令输出快速发现如果不能那就说明规则还需要更具体。8.3 多工具共存时的冲突仲裁现在很多团队不会只用一个 AI 编码工具。Chrome 里开着 Codex终端里跑着 Claude CodeIDE 里还有 Copilot。这种情况下AGENTS.md 必须成为唯一的仓库级事实来源CLAUDE.md、.cursorrules 这些工具专属文件只写“该工具的增量偏好”不要重复定义命令和架构规则。一旦出现冲突建议遵循“仓库级规则优先于工具级规则工具级规则优先于模型默认行为”的原则。同时规则文件应该定期审查比如每季度检查一次看 AGENTS.md 里的命令是否仍然有效、架构说明是否过期。8.4 权限与安全边界AI 编码工具的能力越强权限边界越重要。给 Claude Code 配置凭证时建议使用最小权限原则只授予它完成本职工作所需的仓库权限和网络权限不要用一个拥有全部权限的通用 Key。同时在 AGENTS.md 里要明确“禁止 AI 自动执行的危险操作”比如不要自动推送到生产分支不要自动执行数据库清空或批量删除不要读取或打印密钥、令牌等敏感信息涉及.env、密钥文件、生产环境配置时必须先停下来询问人类。AI 编码工具的落地速度很快但规则和安全边界不能跟着“快”。人类工程师需要 review 什么AI 代理同样需要被约束在哪条线上这条线应该写进仓库里而不是依赖某一次对话里的一句提醒。9. 总结Claude Code 的争议教会我们什么Claude Code 是一个值得长期关注的工具Shopify CEO 这次表态也提醒了所有 AI 编码工具的开发者AI 编程的下一阶段竞争点已经不只是生成代码的速度和准确率而是对团队规则的尊重程度。一个工具可以很快、很强但如果它在一个已经定义了 AGENTS.md 的仓库里反复“失控”它就无法进入严肃的工程体系。对开发者来说现在最值得做的两件事是第一把 AGENTS.md 当成与 README 同级的一等工程资产在自有仓库里真正建立规则第二对自己正在用的 AI 工具做一次“规则遵守度”测试而不是只看它生成的代码有多像老手。工具会迭代模型会升级但可预测、可约束、可解释才是一个 AI 编码工具进入生产环境的前提。如果你已经在项目里维护了 AGENTS.md不妨顺手验证一下 Claude Code 的遵守情况再把 CLAUDE.md 的优先级写清楚。规则体系的建立越早后续切换到其他工具时的成本就越低。