多个 AI 编码工具规则对不齐?一份 AGENTS.md 全管住,改一处全生效(附模板)

我前阵子同时开着 Claude Code 和 Cursor 写同一个项目，两边的规则文件各写一份。有次在 Claude 那边加了条「提交前必须跑测试」，Cursor 那边压根不知道，过了两天才在一个没跑测试的提交里发现俩工具早就对不上了。你如果同时用两个以上的 AI 编码助手，几乎都栽过这个跟头。

这篇后面的 AGENTS.md 模板是要直接抄进仓库根的，建议先收藏。下次新开项目照着建一份，三个工具就齐活了，不用再改一处同步三处。

为什么规则会漂

每个 AI 编码工具有自己认的那份规则文件：Claude Code 读 CLAUDE.md，Cursor 读 .cursorrules，Codex 读 AGENTS.md。同一条「提交前跑测试」，你得写进三个文件。只要改一处忘了同步，三个 Agent 的行为就分叉，这种漂移没人盯着根本发现不了。

转机在 2026-09-18：Claude Code 2.1.277 更新之后，项目里没有 CLAUDE.md 时会自动改读 AGENTS.md。而 AGENTS.md 本来就是个跨厂商的开放格式，由 Linux Foundation 旗下的 Agentic AI Foundation 在维护，Codex、Cursor、Gemini CLI、Windsurf 这些 30 多个工具都读它，6 万多开源仓库已经在用了。一句话讲透：把共享规则只写进 AGENTS.md，三拨 Agent 读同一份，漂移就消失了。

第一步：确认 Claude Code 版本够新

目标：AGENTS.md 回退是 2.1.277 才有的能力，老版本不认这个文件。

在终端里执行：

claude --version

验证：输出版本号要 ≥ 2.1.277（写这篇时最新是 2.1.278）。低于这个数，Claude Code 不会去读 AGENTS.md，得先升级：

npm i -g @anthropic-ai/claude-code

升级完再跑一次版本检查，确认数字上去了再往下走。

第二步：建一份 AGENTS.md 写共享规则

目标：让所有 Agent 读同一份，不再各写各的、各漂各的。

在仓库根目录新建 AGENTS.md，把共享规则写进去。下面这份是我常用的五节骨架，直接复制，控制在 100 行内：

# 项目规则（AGENTS.md）  ## 环境 - 依赖安装：npm install - 本地起服务：npm run dev  ## 代码风格 - TypeScript strict 模式常开 - 提交前必须过 ESLint - 不用 any，除非旁边写原因  ## 测试 - 提交前必须跑：npm test - CI 不绿不准合并  ## 提交与 PR - Commit 用约定式格式 - PR 至少 1 审批 + CI 绿  ## 安全边界 - 不删库、不 force push 主干 - 装依赖改配置前先问我

验证：文件建好后，用任意编辑器打开确认 UTF-8 编码、扩展名是 .md 而不是 .md.txt（Windows 记事本另存为最爱干这事）。这份模板就是今天最该抄走的那一份，关注后也能私信「规则」领带注释的版本。

第三步：让 Claude Code 读这份 AGENTS.md

目标：老项目大多已经有 CLAUDE.md，Claude Code 默认只读它，不会碰 AGENTS.md，所以要明着告诉它。

二选一：

方案 A（推荐，不破坏现有 CLAUDE.md）：在 CLAUDE.md 顶部加一行引入：

@AGENTS.md

方案 B（干净做法）：把 CLAUDE.md 改名或删掉，Claude Code 检测到没有 CLAUDE.md，会自动改读 AGENTS.md。

验证：开一个新会话，Claude Code 启动时会打印一行：

no CLAUDE.md found

 

看到这行就说明它已经去读 AGENTS.md 了。我自己的经验是先用方案 A 最稳，因为老项目里 CLAUDE.md 往往还藏着别的 Claude 专属配置，直接删了容易把那些也带走。

第四步：让 Gemini CLI 也读同一份

目标：Gemini CLI 默认只认 GEMINI.md，不认 AGENTS.md，不配它就读不到。

编辑项目下的 .gemini/settings.json（没有就新建一个），加一段：

"context": {   "fileName": [     "AGENTS.md",     "GEMINI.md"   ] }

验证：重启 Gemini CLI 会话，问它「提交前该跑什么命令」，它应该回答 AGENTS.md 里写的 npm test，而不是说不知道。

排错三连

一、改了 AGENTS.md，Claude Code 跟没看见一样。

报错现象：规则写了跟没写一样，Agent 还是按老习惯来，没有任何报错。

原因：项目里（或者上层目录）还留着 CLAUDE.md、.claude/CLAUDE.md，或者一个不起眼的 CLAUDE.local.md。Claude Code 只要看到它们，就不会去读 AGENTS.md。官方文档特意点名 CLAUDE.local.md 会静默挡住 AGENTS.md，这个坑我翻 release notes 和多篇解读都确认过。

动作：先搜一遍项目里有没有这些文件：

ls CLAUDE.md .claude/CLAUDE.md ls CLAUDE.local.md

有就按第三步方案 A 加 @AGENTS.md，或者直接把挡路的那个改名。

二、claude --version 出来低于 2.1.277。

报错现象：版本号停在 2.1.276 或者更老。

原因：客户端太旧，压根没 AGENTS.md 回退这个功能。

动作：升级后重跑版本检查：

npm i -g @anthropic-ai/claude-code

三、Gemini CLI 还是不读 AGENTS.md。

报错现象：问它规则，它回答的是 GEMINI.md 的内容或者不认。

原因：没配 context.fileName，它只认 GEMINI.md 那一份。

动作：按第四步在 .gemini/settings.json 里把 AGENTS.md 加进 fileName 数组，重启会话再问一次。

进阶和我的取舍

个人全局规则也能统一。把「提交格式、永远别 force push」这类跨项目偏好写进一份文件，用 deja 这类工具同步到 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md、~/.gemini/GEMINI.md。Windows 上这几个路径就是 C:\Users\你的用户名\.claude\CLAUDE.md 那一串。我没能把每家全局路径都实跑一遍，建议你先在一个仓库里跑通上面 4 步，再扩到全局，别一上来就动全局配置。

我的建议是先用方案 A（@AGENTS.md 引入），因为不破坏你已有的 CLAUDE.md，老项目最稳；只有新仓库我才直接用方案 B 干掉 CLAUDE.md。被浪费的不是写代码的时间，是对齐规则的时间，这份账长期看比想象的贵。

这次的信息来源：Claude Code 官方 release notes（v2.1.277，2026-09-18）、terminalblog 与 aicoderscope 对该行为的多方解读、AGENTS.md 规范站点（Agentic AI Foundation，Linux Foundation 旗下）。版本号、文件路径、读取优先级均以官方文档为准。

你平时同时用哪几个 AI 编码工具？规则漂移最让你头疼的是哪一条？评论区说下，我把高频那条写进下篇的默认模板。

关注后私信「规则」，领这份 AGENTS.md 完整模板（带注释版）和同步到全局的脚本，改完就能跑，不用手抄。