我合作的大多数企业开发团队如今都在运行不止一个 AI 编码代理。平台团队统一采用了 Claude Code,前端团队为 Cursor 付费,所有人都通过组织的 GitHub Enterprise 协议拥有 GitHub Copilot,有人在 Codex 中排队执行后台任务,数据团队则在半数笔记本上装了 Gemini CLI。每个工具都读取自己的指令文件,而每个文件都是由最早采用该工具的人写的。六个月后,CLAUDE.md 里的构建命令已经错了,.cursorrules 仍然禁止使用一个团队现在依赖的库,而没有人能说清哪个文件才是权威。本指南针对这种局面给出一套统一的配置策略:以 AGENTS.md 作为厂商中立的单一事实来源,围绕它构建精简的工具专用适配文件,明确哪些内容必须保持工具专用,并建立让这些文件保持可信的治理机制。关于各工具读取什么的每一项说法,都已对照该厂商的当前文档核实,并在正文中附上链接。
问题所在:五个工具、五个文件、彼此漂移
指令文件就是你交给新工程师的入职文档,区别在于这位工程师在每一次会话开始时都会读它,而且在它出错时永远不会提出质疑。这让漂移的代价变得高昂,而文档漂移从来没有这么贵过。一份过期的 README.md 只会浪费新员工一个下午;一份过期的指令文件却会把仓库里的每一次代理会话引向同一条错路,而且由于每个工具各有自己的文件,漂移是不均匀的:Claude Code 可能已经知道新的测试运行器,而 Copilot 仍在运行旧的那个。
我在面向企业团队的 CLAUDE.md 指南和面向企业 AI 编码的 AGENTS.md 指南中分别讲解了这两个最常见的文件。那两篇文章解释了每个文件里该写什么。本文位于它们之上,回答一个在搜索查询和需求沟通电话中反复出现的问题:当一个团队运行多个代理时,哪个文件胜出,又如何避免维护同一套规则的五份副本?
简短的答案是:你不需要维护五份副本。你只维护一份,并且准确理解每个工具如何消费它。
每个工具读取什么
下表是我当初开始理清这个问题时就希望拥有的参考。它根据各厂商的当前文档整理而成,表后的各工具小节给出细节和链接。
| 工具 | 主要指令文件 | 嵌套与优先级 | 文档记载的限制与导入 | 读取 AGENTS.md? |
|---|---|---|---|---|
| Claude Code | CLAUDE.md 或 .claude/CLAUDE.md、CLAUDE.local.md、.claude/rules/*.md、受管 CLAUDE.md | 工作目录及每个上级目录中的文件在启动时加载;子目录文件按需加载;全部拼接,最近者最后读取 | @path 导入最多四层;每个文件目标控制在 200 行以内 | 是,当工作目录及其上级不存在 CLAUDE.md 时(v2.1.277 及以上),或通过 @AGENTS.md 导入 |
| OpenAI Codex | AGENTS.md(AGENTS.override.md 优先) | 先读 ~/.codex/,再从项目根目录到工作目录每个目录各取一个文件,按顺序拼接,越近的文件优先级越高 | 合并链由 project_doc_max_bytes 限制,默认 32 KiB | 原生支持 |
| GitHub Copilot | .github/copilot-instructions.md、带 applyTo glob 的 .github/instructions/*.instructions.md | 仓库级与匹配的路径级文件同时使用;个人指令、仓库指令、组织指令依次排序 | 未记载平台级大小限制 | 云代理、GitHub.com 上的代码评审、VS Code 聊天和 Copilot CLI 会读取;GitHub.com、Visual Studio 和 JetBrains 中的 Copilot Chat 不读取 |
| Cursor | 带 description、globs、alwaysApply 的 .cursor/rules/*.mdc | Team Rules、Project Rules、User Rules 依次合并,先出现的来源胜出 | 规则保持在 500 行以内;被引用的文件不会内联 | 是,根目录和子目录均可,合并后以更具体的文件胜出 |
| Gemini CLI | GEMINI.md | 全局 ~/.gemini/GEMINI.md、工作区目录及其父目录,随后按需加载子目录文件 | @file.md 导入;context.fileName 接受文件名列表 | 是,当 context.fileName 包含 AGENTS.md 时 |
| Windsurf | .windsurf/rules/*.md(现在首选 .devin/rules/)、旧版 .windsurfrules | 在工作区内直至 Git 根目录发现规则;trigger 模式有 always_on、glob、model_decision、manual | 每个工作区规则文件 12,000 个字符,全局文件 6,000 个字符 | 是,根文件始终开启,子目录文件按 glob 自动限定范围 |
Claude Code:CLAUDE.md 及其层级
Claude Code 的记忆文档按加载顺序列出了四个范围:由 IT 部署的受管策略文件(macOS 上为 /Library/Application Support/ClaudeCode/CLAUDE.md,Linux 和 WSL 上为 /etc/claude-code/CLAUDE.md,Windows 上为 C:\Program Files\ClaudeCode\CLAUDE.md)、位于 ~/.claude/CLAUDE.md 的用户文件、位于 ./CLAUDE.md 或 ./.claude/CLAUDE.md 的项目文件,以及一个被 gitignore 的 ./CLAUDE.local.md 用于个人笔记。Claude 在启动时加载工作目录及其上方每个目录中的 CLAUDE.md 文件,从文件系统根目录向下拼接,因此最近的文件最后被读取;子目录中的文件只在它读取、写入或编辑该子目录中的文件时才加载。
对于共享策略而言有三个细节很重要。第一,@path/to/file 导入语法会把另一个文件拉入上下文,路径相对于包含导入语句的文件解析,最多可嵌套四层;代码片段和围栏代码块中的导入会被忽略。第二,Anthropic 的指导是每个 CLAUDE.md 文件目标控制在 200 行以内,而导入并不能降低这一成本,因为被导入的文件会随导入它的文件一起加载。第三,.claude/rules/*.md 文件与项目 CLAUDE.md 一同加载,前置元数据中的 paths: 字段可把规则限定到匹配的文件,使其仅在 Claude 处理这些文件时加载。如果你想了解 Claude Code 仓库逐层的全貌,包括技能和钩子,请阅读Claude Code 项目的解剖。
OpenAI Codex:AGENTS.md 加覆盖文件
Codex 是这一格式最初为之设计的工具,它的 AGENTS.md 文档是我见过对嵌套最精确的描述。Codex 首先查看它的主目录(~/.codex,或 CODEX_HOME),在那里只使用第一个非空文件,并优先选择 AGENTS.override.md 而非 AGENTS.md。随后它从项目根目录(通常是 Git 根目录)开始向下遍历到当前目录,每个目录最多取一个文件,顺序为 AGENTS.override.md、AGENTS.md,再到 project_doc_fallback_filenames 中列出的任何名称。这些文件从根目录向下以空行分隔拼接,因此越靠近工作目录的指令在提示中出现得越晚、优先级越高。
大多数团队忽略的限制是:project_doc_max_bytes 默认把合并后的大小限制在 32 KiB,一旦链条达到该上限,Codex 就停止添加文件。一个臃肿的根文件可能会悄无声息地把包级文件挤出上下文。
GitHub Copilot:三种指令文件
GitHub 关于仓库自定义指令的文档描述了仓库级的 .github/copilot-instructions.md、.github/instructions/ 下带有前置元数据 applyTo glob(以及可选的 excludeAgent,取值 code-review 或 cloud-agent)的路径级 NAME.instructions.md 文件,以及代理指令文件:仓库中任意位置的 AGENTS.md,以最近的文件优先;或者根目录下单一的 CLAUDE.md 或 GEMINI.md。当路径级文件匹配且仓库级文件也存在时,两者都会被使用。在各来源之间,个人指令排在仓库指令之上,仓库指令排在组织指令之上,但所有相关的指令集都会提供给模型,因此 GitHub 的建议是避免矛盾,而不是依赖排序。
关键在于支持矩阵。Copilot 云代理、GitHub.com 上的 Copilot 代码评审、VS Code 中的 Copilot Chat 和 Copilot CLI 会读取 AGENTS.md。GitHub.com 上、Visual Studio 中和 JetBrains IDE 中的 Copilot Chat 读取 .github/copilot-instructions.md,但不读取 AGENTS.md。Copilot 代码评审还会从拉取请求的头分支而不是基础分支读取指令,当你在同一个 PR 中修改这些文件时这一点很重要。
Cursor:.cursor/rules 与 AGENTS.md
Cursor 的规则文档把项目规则描述为 .cursor/rules/ 下的 .mdc 文件(放在那里的普通 .md 会被忽略,因为它没有前置元数据),带有三个前置元数据字段:alwaysApply: true 让规则进入每次聊天,globs 在匹配文件进入上下文时附加规则,而只有 description 时由代理自行决定是否引入。规则按 Team Rules、Project Rules、User Rules 的顺序合并,冲突时先出现的来源胜出。Team Rules 在 Team 和 Enterprise 方案中通过 Cursor 控制台管理,并可被强制执行,使用户无法禁用。Cursor 还要求规则保持在 500 行以内,并警告从规则中引用的文件不会被内联;代理只在它自己决定时才用工具去读取该文件。
AGENTS.md 在文档中被描述为面向简单场景的 .cursor/rules 的纯 Markdown 替代方案,支持放在项目根目录和子目录中,嵌套的指令与其父级合并,并以更具体的文件优先。旧版指南中描述的那个单一 .cursorrules 文件在当前的规则页面上完全没有出现。把它视为遗留文件并迁移。
Gemini CLI:可重命名的 GEMINI.md
Gemini CLI 的上下文文件文档描述了全局的 ~/.gemini/GEMINI.md、在已配置的工作区目录及其父目录中找到的 GEMINI.md 文件,以及对任何被工具触及的目录按需加载文件,直至可信根目录。所有找到的内容都会被拼接并随每个提示一起发送。支持相对路径和绝对路径的 @file.md 导入。这里真正重要的功能是 settings.json 中的 context.fileName,它接受单个名称或一个列表,而文档自己的示例就是 ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]。/memory show 打印合并后的上下文,/memory reload 重新扫描这些文件。
Windsurf:带字符限制的规则
Windsurf 的规则文档现在位于 Devin Desktop 之下,首选 .devin/rules/*.md,.windsurf/rules/*.md 作为后备保留;旧版的单文件 .windsurfrules 仍会被读取。每个规则文件带有一个 trigger,取值为 always_on、glob、model_decision 或 manual。全局规则文件限制为 6,000 个字符,每个工作区规则文件限制为 12,000 个字符,这是本文所有工具中记载最严格的限制。任何目录中都支持 AGENTS.md:根文件始终开启,子目录文件会自动按 glob 限定到其所在目录。在 Git 仓库中,搜索还会向上遍历到 Git 根目录,企业 IT 可以部署只读的系统规则。
单一来源策略:AGENTS.md 加精简适配文件
为什么 AGENTS.md 是事实来源
AGENTS.md 规范是没有必填字段的纯 Markdown,由 Linux 基金会旗下的 Agentic AI Foundation 管理,其支持者名单中列出了 Codex、Cursor、Gemini CLI、Windsurf、GitHub Copilot 的编码代理、VS Code、Zed、JetBrains Junie、Devin、Aider、Factory 等,使用它的开源项目超过 60,000 个。它是对比表中唯一一个每个工具都能原生读取或可以配置为读取的文件。其他文件都远远不及:CLAUDE.md 由 Claude Code 读取,并且仅在根目录时由部分 Copilot 界面读取;GEMINI.md 由 Gemini CLI 和同样那些 Copilot 界面读取;.cursor/rules 只有 Cursor 读取。
因此共享约定放进 AGENTS.md,其他每个文件都变成适配器:要么是一个持有工具专用指令并引入共享文件的精简桩文件,要么是一份由 CI 保持同步的生成副本。
Claude Code:导入,不要重复
这里的陷阱在于默认行为。Anthropic 的文档指出,只有当工作目录及其所有上级目录中都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时,Claude 才读取 AGENTS.md。一个同时拥有两个文件的仓库(因为有人为 Claude 专用笔记添加了 CLAUDE.md)会在 Claude Code 中悄无声息地停止加载 AGENTS.md。文档记载的解决办法是让 @AGENTS.md 成为 CLAUDE.md 的第一行;Claude 先读取被导入的文件,再读取下方的 Claude 专用内容,而且文档确认这种导入永远不会导致重复读取。
符号链接(ln -s AGENTS.md CLAUDE.md)也可行,但 Anthropic 警告,如果有人在 Windows 上克隆仓库就不要这样做:在那里创建符号链接需要管理员权限或开发者模式,而且除非启用了 core.symlinks,Git 会把提交的符号链接检出为只有一行的文本文件。我的大多数客户至少有一位 Windows 开发者,所以我使用导入。还有一个 Project instructions 设置,可取值 claude-md-and-agents-md,但它只在用户设置、--settings 或受管设置中生效,在项目设置和本地设置中会被忽略,因此你无法把它提交到仓库。导入才是可移植的答案。
GitHub Copilot:生成,不要指向
对于会读取 AGENTS.md 的 Copilot 界面,你已经完成了。对于 GitHub.com 上、Visual Studio 中和 JetBrains 中的 Copilot Chat,唯一会加载的仓库文件是 .github/copilot-instructions.md。在那个文件里写"请阅读 AGENTS.md"依赖于模型自行决定打开它,这正是 Anthropic 针对用文字告诉 Claude 去读 AGENTS.md 的 CLAUDE.md 所指出的同样弱点。可靠的模式是在 CI 中从 AGENTS.md 生成 .github/copilot-instructions.md,附上一个说明它是生成文件的头部,并加入一个在两者出现分歧时让流水线失败的检查。路径专用的 Copilot 行为,例如只适用于 **/*.sql 的规则,放进 .github/instructions/*.instructions.md,这在共享文件中没有对应物。
Cursor、Gemini CLI、Codex 与 Windsurf
Cursor 原生读取根目录和嵌套的 AGENTS.md,所以 .cursor/rules 收缩为 Cursor 专用、按 glob 限定范围的行为,以及管理员通过 Team Rules 强制执行的任何内容。Gemini CLI 需要提交一行配置:在 .gemini/settings.json 中把 context.fileName 设为 ["AGENTS.md", "GEMINI.md"],之后 GEMINI.md 只保留 Gemini 专用指令。Codex 和 Windsurf 无需配置即可读取共享文件;对于 Codex,把链条保持在 32 KiB 以内,只在临时本地覆盖时使用 AGENTS.override.md;如果你用 Codex 做 GitHub 代码评审,就在离被治理代码最近的 AGENTS.md 中加入一个 ## Code Review Rules 小节,这是 OpenAI 记载的机制。
哪些内容无法共享
指令文件是给模型看的文字。所有由工具强制执行而非向模型建议的内容,都留在该工具自己的配置中,而且每个工具都不一样:
| 关注点 | 可在 AGENTS.md 中共享? | 所在位置 |
|---|---|---|
| 构建、测试、lint 命令、约定、边界 | 是 | AGENTS.md,根目录和嵌套 |
| 工具权限(allow、ask、deny) | 否 | Claude Code 的 .claude/settings.json 和 settings.local.json;其他各工具自己的设置;Cursor Team Rules 用于强制行为 |
| 在工具调用前后运行的钩子 | 否 | Claude Code settings.json 中的 hooks;没有共享的对应物 |
| MCP 服务器注册 | 否 | 各工具自己的配置;Claude Code 把它放在自己的配置文件中,而不是 CLAUDE.md |
| 按路径限定范围的规则 | 部分 | 用嵌套 AGENTS.md 实现共享范围;用 Claude Code 带 paths 的 .claude/rules/、Cursor 的 globs、Copilot 的 applyTo、Windsurf 的 glob 实现工具专用范围 |
| 组织级策略 | 否 | Claude Code 受管 CLAUDE.md 与受管设置;Cursor Team Rules;Copilot 组织指令;Windsurf 系统规则 |
| 个人的、不提交的笔记 | 否 | CLAUDE.local.md、~/.codex/AGENTS.override.md、Cursor User Rules、Gemini 的 ~/.gemini/GEMINI.md |
Anthropic 的记忆页面说得很直白:Claude 把 CLAUDE.md 视为上下文,而不是强制配置;要无论模型如何决定都阻止某个操作,就要使用 PreToolUse 钩子或 permissions.deny 规则。本指南中的每个文件都是如此。把规则写进 AGENTS.md,让每个代理都知道它,然后在工具设置和 CI 中强制执行那些真正重要的规则。
monorepo 优先级:根文件与包级文件
表中的每个工具都支持一个根文件加嵌套文件,而每个工具合并它们的方式都略有不同。这正是共享 AGENTS.md 策略要么站得住、要么崩塌的地方。
| 工具 | 根文件 | 嵌套文件 | 如何合并 |
|---|---|---|---|
| Claude Code | 启动时随每个上级目录一起加载 | 当 Claude 触及该目录中的文件时按需加载 | 拼接,最近者最后;claudeMdExcludes 跳过你永远不想要的文件 |
| Codex | 最先加载 | 向下到工作目录,每个目录一个文件 | 从根向下拼接,越近的文件越靠后、越强;在 32 KiB 处停止;AGENTS.override.md 替换该目录的文件 |
| GitHub Copilot | 当它是最近的文件时使用 | 离该文件最近的 AGENTS.md 优先 | 文档未说明嵌套文件是否与根文件合并 |
| Cursor | 始终适用 | 适用于该目录及其子目录 | 与父级合并,更具体者胜出 |
| Gemini CLI | 全局加工作区及父目录 | 当工具触及该目录时按需加载 | 拼接 |
| Windsurf | 始终开启 | 自动按 glob 限定到其目录 | glob 匹配时两者同时生效 |
从那张表可以得出两条规则。第一,编写每个嵌套 AGENTS.md 时,都要确保无论根文件是否同时在上下文中它都正确。Copilot 的文档没有承诺合并,Codex 可能截断,而 Claude Code 只在代理实际触及该目录时才加载嵌套文件。重复那一两条漏掉就会酿成灾难的边界,并且永远不要与根文件矛盾;Anthropic 关于指令冲突时模型"可能任意选择一个"的建议适用于每个代理。第二,让根文件保持精短。Anthropic 的 200 行目标和 Codex 的 32 KiB 上限是约束你设计的两个数字,一个保持在大约 10 KB 以内的根文件,可以在 Codex 开始丢弃文件之前为两三个包文件留出空间。
对于拥有几十个包的团队,Claude Code 的大型代码库指南推荐两级拆分:根文件加每个包一个文件,由该包的所有者维护,并用 claudeMdExcludes 排除你永远不会涉及的包。这种所有权模式可以直接映射到其他所有工具的嵌套 AGENTS.md 文件上。
哪些内容属于共享文件,哪些属于工具专用文件
| 内容 | 放在 | 原因 |
|---|---|---|
| 安装、构建、测试、lint 和格式化命令,逐字记录 | AGENTS.md | 每个代理都会运行它们;最常见的漂移就是过期的命令 |
| 仓库布局以及各部分所在位置 | AGENTS.md | 为每个代理省去同样的探索 |
| 语言、框架和风格约定,各附一个具体示例 | AGENTS.md | 约定与工具无关 |
| 边界:绝不编辑生成的代码、绝不修改已合并的迁移、绝不提交密钥 | AGENTS.md,并在嵌套文件中重复 | 必须在截断和部分加载中幸存 |
| 安全规则:配置来自哪里、哪些模块需要人工评审 | AGENTS.md | 无论哪个代理做出更改都适用 |
| 拉取请求与提交约定 | AGENTS.md | Codex、Copilot 代码评审和 Claude Code 都会创建或评审 PR |
| 规划模式、模型选择、努力程度、自动记忆 | CLAUDE.md | Claude Code 的概念 |
权限规则、钩子、MCP 服务器、claudeMdExcludes | .claude/settings.json | 强制执行的配置,而非文字 |
| 针对某个框架按 glob 附加的规则 | .cursor/rules/*.mdc、.github/instructions/*.instructions.md、.windsurf/rules/*.md | 匹配时附加的行为没有共享对应物 |
| Codex 代码评审规则 | AGENTS.md 中的 ## Code Review Rules 小节 | Codex 从共享文件中读取它 |
我对每一行应用的检验标准是:如果开发者明天换了工具,这条指令还成立吗?成立,它就属于 AGENTS.md;只在某一个产品内部才有意义,它就属于该产品的文件。
治理:所有权、评审、版本管理、密钥与测试
所有权。把 AGENTS.md、适配文件和同步脚本加入 CODEOWNERS,由平台团队或开发者体验团队拥有根文件,由各包团队拥有各自的嵌套文件。Anthropic 的 monorepo 指南对每个目录的 CLAUDE.md 文件给出了同样的建议:每个目录的所有者维护自己的文件。
评审。指令文件的每一次更改都像代码一样走拉取请求流程。Claude Code 在这里提供了一个帮手:/doctor prompt-audit(v2.1.283 或更高版本)会检查 CLAUDE.md、CLAUDE.local.md 和 AGENTS.md 文件以及规则和技能,查找对不存在的文件或命令的引用、为旧模型编写的指令以及相互矛盾的文件,并提出修改建议,在你接受之前不会改动任何内容。在合并对共享文件的更改之前运行它,即使促成这次更改的工具不是 Claude Code。
版本管理。这些文件存放在 Git 中,所以它们本身就有版本。团队容易忘记的是要有意识地为生成副本做版本管理:提交 .github/copilot-instructions.md,并让 CI 在它过期时失败,而不是在构建时悄悄重新生成、让没人看到差异。
密钥。绝对不行。这些文件会被每个工具在每位开发者的机器上注入模型上下文,发送给该工具调用的任何厂商,并被生成器复制。AGENTS.md 中的一个连接字符串,就是五家厂商请求日志中的一个连接字符串。个人文件 CLAUDE.local.md 和 ~/.codex/AGENTS.override.md 虽然被 gitignore,但仍会进入上下文,所以它们同样不是存放密钥的地方。让代理指向环境变量或密钥管理器,并用强制手段支撑这条规则:例如 Claude Code 的 permissions.deny 规则 Read(./.env) 会无视模型意图直接阻止读取。
测试指令。把对共享文件的更改当作对构建脚本的更改来对待,并在每个工具中做冒烟测试。先确认加载:Claude Code 中的 /context 在 Memory files 下列出文件,Gemini CLI 中的 /memory show 打印合并后的上下文,GitHub.com 上的 Copilot Chat 在使用了该文件时会在 References 中列出 .github/copilot-instructions.md,OpenAI 则建议用 codex -c log_dir=./.codex-log 写出可供审计的日志。然后运行一组固定的提示(“哪个命令运行测试?““数据库查询应该放在哪里?")并对比各工具的回答。出现分歧就是你在开发者之前发现的漂移。
模板
一组简短而贴近实际、可直接复制的模板。仓库是一个虚构的支付平台,请替换具体内容。
AGENTS.md(事实来源)
# AGENTS.md: Payments Platform
## Project
Node 22 / TypeScript 5.6 monorepo using pnpm workspaces.
Services live under `services/`, shared libraries under `packages/`.
## Commands
- Install: `pnpm install --frozen-lockfile`
- Build: `pnpm -r build`
- Test: `pnpm -r test` (run before every commit)
- Lint and format check: `pnpm lint && pnpm format:check`
## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Database access goes through `packages/db`. No raw SQL in route handlers.
- Commit subjects: `<package>: <imperative summary>`, for example `api: add idempotency keys`.
## Boundaries
- Never edit files under `**/generated/`. Run `pnpm codegen` instead.
- Never modify a migration that has merged. Add a new one.
- Never commit secrets or `.env*` files. Configuration comes from the environment.
- Changes under `services/payments/` require a human reviewer from the payments team.
## Pull requests
- Title format: `[<package>] <summary>`. Run lint and tests before opening the PR.
## Code Review Rules
- Flag any new dependency without a justification in the PR description.
- Flag raw SQL strings outside `packages/db`.CLAUDE.md(精简适配文件)
@AGENTS.md
## Claude Code
- Use plan mode for any change under `services/payments/`.
- Permissions, hooks and MCP servers are configured in `.claude/settings.json`. Do not duplicate them here..cursor/rules/testing.mdc(Cursor 专用、按 glob 限定范围)
---
description: Testing conventions for the payments monorepo
globs: "**/*.test.ts"
alwaysApply: false
---
- Use Vitest. Never add Jest.
- Wrap database tests in a transaction that rolls back.
- Shared project rules live in AGENTS.md; this file holds Cursor-specific behaviour only..gemini/settings.json(把 Gemini CLI 指向共享文件)
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}scripts/sync-agent-instructions.sh(生成 Copilot 副本)
#!/usr/bin/env bash
set -euo pipefail
{
echo "<!-- GENERATED from AGENTS.md. Edit AGENTS.md and run scripts/sync-agent-instructions.sh. -->"
cat AGENTS.md
} > .github/copilot-instructions.md
# In CI, fail when the committed copy is out of date:
git diff --exit-code -- .github/copilot-instructions.md团队推广计划
- 第 1 周:盘点。列出每个仓库中的每个指令文件,例如用
git ls-files | grep -Ei 'claude\.md|agents\.md|cursorrules|cursor/rules|copilot-instructions|instructions\.md|gemini\.md|windsurf'。记录每个文件由谁编写、最后一次更改是什么时候。选一个正在活跃开发的仓库作为试点。 - 第 2 周:整合。用"这在任何工具中都成立吗?“的检验标准,把试点仓库的文件合并为一个
AGENTS.md。Claude Code 的/init会读取现有的 Cursor 和 Copilot 文件,在设置了CLAUDE_CODE_NEW_INIT=1时还会读取AGENTS.md、Windsurf 和 Cline 的文件,并提出一份整合草稿;把它当作起点,而不是结果。编写精简的CLAUDE.md、Gemini 设置和 Copilot 同步脚本。删除.cursorrules和任何重复的文字。 - 第 3 周:试点。三到五名开发者,他们合起来覆盖团队使用的每一个工具。每人运行加载检查和固定提示集,然后正常工作一周,记录代理忽略或弄错的每一条指令。修正文件,而不是修正开发者。
- 第 4 周:制度化。添加
CODEOWNERS条目、CI 同步检查和一个仓库模板。决定哪些内容上升到组织层:Claude Code 的受管CLAUDE.md与受管设置、Cursor Team Rules、Copilot 组织指令和 Windsurf 系统规则,是必须适用于每个仓库的规则应该存放的地方。然后把这套模式推广到接下来的仓库,每个仓库一个拉取请求。
应对措施
- 盘点你所有仓库中的每个指令文件,并为每个文件指定所有者。
- 创建一个根
AGENTS.md,包含命令、布局、约定、边界、安全规则和 PR 约定,并保持在 200 行以内。 - 如果已存在
CLAUDE.md,让@AGENTS.md成为它的第一行,并把所有非 Claude 专用的内容移出。 - 如果有人使用 Gemini CLI,在提交的
.gemini/settings.json中把context.fileName设置为包含AGENTS.md。 - 从
AGENTS.md生成.github/copilot-instructions.md,并添加一个在它过期时失败的 CI 检查。 - 删除
.cursorrules;保留.cursor/rules/*.mdc用于按 glob 限定范围、仅限 Cursor 的行为。 - 为每个包添加嵌套的
AGENTS.md文件,自成一体,永不与根文件矛盾,并重复关键边界。 - 把权限、钩子和 MCP 注册移入各工具的设置中,并用 deny 规则和 CI 强制执行重要的规则。
- 搜索每个指令文件中的密钥,将其删除,并添加针对
.env读取的 deny 规则。 - 把这些文件加入
CODEOWNERS,在合并更改前运行/doctor prompt-audit,并在每次更改后对每个工具做冒烟测试。
常见问题
AGENTS.md 和 CLAUDE.md 有什么区别? AGENTS.md 是由 Linux 基金会旗下 Agentic AI Foundation 管理的厂商中立文件,被 Codex、Cursor、Copilot 的代理、Gemini CLI 和 Windsurf 读取。CLAUDE.md 是 Claude Code 自己的文件,拥有共享格式所没有的 @path 导入、受管策略层、CLAUDE.local.md 和按路径限定范围的规则。共享约定放进 AGENTS.md;一个简短的 CLAUDE.md 导入它并添加 Claude 专用指令。
Claude Code 会读取 AGENTS.md 吗? 会,从 v2.1.277 开始,但仅当工作目录及其上级目录中不存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时。两个文件同时存在时它只读取 CLAUDE.md,除非 Project instructions 被设置为 claude-md-and-agents-md。可移植的解决办法是在 CLAUDE.md 第一行加入 @AGENTS.md 导入。
我应该用 .cursorrules 还是 .cursor/rules? 使用 .cursor/rules/*.mdc 或一个纯文本的 AGENTS.md。Cursor 当前的文档涵盖 .mdc 项目规则、Team Rules 以及位于根目录和子目录的 AGENTS.md;它不再记载 .cursorrules。
GitHub Copilot 会读取 AGENTS.md 吗? Copilot 云代理、GitHub.com 上的代码评审、VS Code 中的 Copilot Chat 和 Copilot CLI 会读取。GitHub.com 上、Visual Studio 中和 JetBrains IDE 中的 Copilot Chat 不会读取,只依赖 .github/copilot-instructions.md,因此请从 AGENTS.md 生成该文件。
monorepo 中嵌套的 AGENTS.md 文件如何工作? 规范规定最近的文件胜出,而明确的提示覆盖一切。Codex 从根向下拼接,越近的文件越强,并默认在 32 KiB 处停止;Cursor 把嵌套文件与父级合并;Windsurf 按 glob 自动限定其范围;Copilot 应用最近的文件。编写嵌套文件时务必确保它们永不与根文件矛盾。
如果你的团队不仅在管理指令,还在打包可复用的代理行为,gh skill GitHub CLI 指南介绍了如何在 Copilot、Claude Code、Cursor、Codex 和 Gemini CLI 之间安装和固定技能;同样的单一来源纪律在那里同样适用。
需要多一双手吗?Big Hat Group 为美国和加拿大的组织提供应用开发咨询,从为期两周的 AI 编码代理配置评估到覆盖所有仓库的完整多代理推广。预约一次需求沟通电话,聊聊你的环境。
来源
- How Claude remembers your project (CLAUDE.md, imports, rules, AGENTS.md),Claude Code 文档
- Settings files and precedence,Claude Code 文档
- Set up Claude Code in a monorepo or large codebase,Claude Code 文档
- AGENTS.md specification,Agentic AI Foundation
- Custom instructions with AGENTS.md,OpenAI Codex 文档
- Adding repository custom instructions for GitHub Copilot,GitHub Docs
- Support for custom instructions in GitHub Copilot,GitHub Docs
- Rules,Cursor 文档
- Provide context with GEMINI.md files,Gemini CLI 文档
- Rules and memories,Devin Desktop (Windsurf) 文档