最近有个消息在 AI 编程工具圈里刷屏Anthropic 正式支持 OpenAI 的 AGENTS.md 规范。说人话就是Claude Code 和 Claude Agent SDK 从今往后会像读取自家 CLAUDE.md 一样去读取项目根目录下的 AGENTS.md 文件并把它当作项目级规则来执行。对于我这种 Cursor、Windsurf、VS Code Copilot、Trae 混着用时不时还要切到 Claude Code 和 OpenAI Codex CLI 写两行代码的人来说这几乎算是一场“停战协议”。以前我在每个工具里都要维护一套不同的规则文件改一处漏一处AI 生成的代码风格忽东忽西。现在终于有一个能被各家共同识别的标准格式而且是 Anthropic 主动拥抱 OpenAI 定下的规范这就很值得聊一聊了。这篇文章不打算复述官方公告而是从一个天天被这些工具折磨的开发者视角拆一拆 AGENTS.md 到底解决了什么问题、它的规则长什么样、Anthropic 入局之后对整个生态意味着什么以及我自己从 .cursorrules 迁移到 AGENTS.md 的完整过程和踩过的坑。1. 配置文件各写一摊多助手混用时的真实痛点1.1 每个工具都有一套“私货”从 Cursor 火起来开始AI 编程助手就有一个心照不宣的玩法用项目里的一个特殊文件告诉 AI“我们团队怎么写代码”。这本身是个好设计因为 AI 模型再强也不了解你项目的技术栈、命名习惯和那些藏在代码之外的历史包袱。问题在于每个工具都非要自己定义一套文件格式。我手上同时在用的工具规则文件是这样的工具/助手规则文件影响范围Cursor.cursorrules、.cursor/rules/*.mdcCursor 的对话和编辑Windsurf.windsurfrulesWindsurf 的对话和编辑GitHub Copilot.github/copilot-instructions.mdVS Code 内补全和聊天Claude CodeCLAUDE.mdClaude Code 会话OpenAI Codex CLIAGENTS.mdCodex CLI 会话Cline 等开源插件各家自定义多数兼容AGENTS.md或CLAUDE.md插件内会话如果你只用一个工具这套体系没什么问题。但像我这样今天在 Cursor 里改前端明天开终端用 Claude Code 跑重构后天用 Codex CLI 写一次性脚本的人维护成本马上就上来了。1.2 我那一次典型的“规则漂移”事故举一个真实例子。我们项目里定过一条规矩复杂交互样式不要用 Tailwind 的apply堆类名而是抽成独立的 CSS 变量和组件类方便后续做暗色模式。我把这条写进了 Cursor 的.cursorrules但当时没同步到 CLAUDE.md。结果有一次我用 Claude Code 改一个下拉菜单组件它看到 Tailwind 就顺手写了一大段apply我 review 的时候差点没认出来这代码是我们团队的风格。问题不大但暴露了一个事实只要规则文件不统一AI 助手的行为就必然不一致。团队里多一个工具就多一份维护负担而这本来是可以靠一个标准文件解决的。1.3 为什么拖了这么久才统一其实行业内早就有人呼吁统一了。Cursor 后期也开始支持AGENTS.mdWindsurf、Copilot 也陆续跟进但大家更多是“兼容”而不是“拥抱”。原因不难理解规则文件是吸引用户留在自家生态的一个抓手你今天用.cursorrules明天换工具就有一堆规则要重写切换成本天然形成了一定黏性。AGENTS.md 之所以能破局是因为 OpenAI 把 Codex CLI 开源之后这个文件名随着无数开发者的实战传播开了。文件名简单、含义清晰就是一个 Markdown 文件任何工具都可以低成本解析。等体量最大的几个助手都开始支持它剩下的厂商就没有理由继续坚持自家私货了。Anthropic 这次正式支持算是补上了最后一块拼图。2. AGENTS.md 规则拆解一份能被 AI 读懂的“项目说明书”2.1 它并不是什么黑科技很多第一次接触 AGENTS.md 的人会把它想成一种新的配置语言其实它的核心规则非常简单文件放在仓库根目录命名为AGENTS.md。使用 Markdown 格式内容用自然语言书写。AI 助手在启动会话时自动读取这个文件并把其中的指令纳入上下文。可以嵌套子目录里也可以放AGENTS.md只影响该目录及以下路径的代码操作。你可以把它理解成一个专门写给 AI 看的 README。人类的 README 往往只讲怎么跑起来、怎么部署而 AGENTS.md 要回答的是“在这个项目里写代码时什么能做、什么不能做、有哪些暗坑”。2.2 一份可抄作业的基础模板以我维护的一个 Next.js FastAPI 全栈项目为例根目录的 AGENTS.md 长这样# 项目规范 ## 项目一句话 面向小团队的轻量 CRM 系统前端 Next.js App Router后端 FastAPI。 ## 常用命令 - 安装依赖pnpm install - 本地前端pnpm dev - 本地后端uvicorn app.main:app --reload - 类型检查pnpm typecheck - 测试pnpm test ## 技术约定 - 前端禁止在 pages 目录新增页面一律使用 App Router - 组件默认放在 src/components按业务模块分目录 - 新接口必须先写 zod schema再推导出类型禁止手写重复类型 - 不要提交 .env.local密钥统一走 Vercel 环境变量 ## 易错点 - 登录态 token 存 cookie不要放 localStorage - SSR 组件里禁止直接访问 window需要时用 useEffect - 后端所有查询必须走 SQLAlchemy 的 Session禁止裸写 SQL内容不复杂但每一条都是能被验证的硬规则。注意我特意没用“代码质量要高”“注意性能”这种模糊话。AI 对模糊指令的响应是随机的它并不知道你心里的“质量高”是什么意思。规则越可验证越容易被助手遵守。2.3 分层规则根文件要“薄”子目录可以“厚”AGENTS.md 最聪明的地方在于支持嵌套。我一开始把所有规则堆在根目录写了一百多行结果每个会话 AI 都要把这堆内容读一遍浪费 token 不说指令之间还会互相打架。后来按照渐进式披露的原则拆开了repo/ ├── AGENTS.md # 全局约定只留最核心的 20 行 ├── src/ │ ├── AGENTS.md # 前端专属规则 │ └── components/ │ └── ui/ │ └── AGENTS.md # 组件库开发规范 ├── backend/ │ ├── AGENTS.md # 后端专属规则 │ └── ... └── docs/ └── AGENTS.md # 文档写作规范当 AI 修改src/components/ui/AGENTS.md覆盖范围内的文件时它会把根目录、src/和ui/三层规则一起加载。这样每一层都能聚焦自己关心的细节不会一上来就灌给模型一整本架构文档。这种设计和人类团队很像公司有全体员工手册部门有部门规范小组有小组约定而不是让新人第一天就读完所有规章制度。2.4 它不是什么别和配置文件搞混AGENTS.md 不是 YAML不是 JSON Schema也不是.cursorrules那种带优先级逻辑的规则引擎。它没有include、exclude这类字段就是纯 Markdown。好处是门槛低、任何人能写坏处是各家工具解析它的方式并不完全一致有的把整个文件塞进上下文有的只取关键片段。这一点在后面讲迁移坑的时候还会重点提。3. Anthropic 下场之后竞争层面在谈和工程层面在谈互操作3.1 官方表态的真正分量Anthropic 官宣 Claude Code 和 Claude Agent SDK 支持 AGENTS.md在新闻通稿里可能只是一句话但在实际工程场景里分量很重。Claude Code 是目前命令行 AI 编程助手里完成度最高的产品之一也是很多团队已经重度依赖的工具。它选择支持一个由竞对定义的开放格式等于承认了“跨工具互操作”的价值高于“自家格式独占”。从我的使用体验看最直接的变化是我终于可以不维护两份重复的规则了。以前 Claude Code 读 CLAUDE.mdCodex CLI 读 AGENTS.mdCursor 读 .cursorrules同一批规范我要复制三份。现在 AGENTS.md 成为主文件Claude Code 也认Codex CLI 也认Cursor 也认只剩一份需要更新。3.2 CLAUDE.md 和 AGENTS.md 怎么分工很多人会问有了 AGENTS.mdCLAUDE.md 是不是可以删了我的建议是别急着删。两者定位不同AGENTS.md跨工具共享的团队公约属于“放之四海而皆准”的内容。CLAUDE.mdClaude Code 特定的偏好设置和增强玩法。Claude Code 有一些自己的特色功能比如 slash command 定义、特定 hook 配置、以及它对 CLAUDE.md 的某些解析细节这些写在 AGENTS.md 里没有意义因为其他工具不认。同理Codex CLI 也有一些自己的配置项那部分继续留在它自己的配置里。我的原则是“公约”放 AGENTS.md“私货”放各自的专属文件。这样任何工具进场都能立刻干活同时每个工具的高级能力也没被阉割。3.3 对 Cursor、Copilot、Trae 这些助手意味着什么当规则文件格式统一之后各家助手之间的竞争重点就从“标准化”转移到了“执行力”。也就是说反正大家都能读同一份 AGENTS.md那拼的就是谁更能理解规则、谁的 agent 循环更稳、谁的修改更少引入新 bug。对于 Cursor、Windsurf、VS Code Copilot 这些以 IDE 插件形态存在的助手来说AGENTS.md 的支持早就在路上。对 Trae、Cline 这类工具它们也基本把 AGENTS.md 当作默认的上下文来源之一。市场格局不会因为一个文件格式立刻改变但有一点是确定的用户切换工具的成本大幅降低了。今天从 Cursor 换到 Windsurf规则文件不用再迁移这会让整个市场的流动性变高。这对开发者是好事。以前我被某个工具的规则解析 bug 卡住时想换工具还得掂量一下迁移成本现在换个助手只需要重新熟悉快捷键。4. 迁移实战把一套规则同时喂给所有 AI 助手4.1 迁移前的盘点清单如果你的项目里已经积累了不少.cursorrules、.windsurfrules、copilot-instructions.md、CLAUDE.md不要直接删了重写。我当时的做法是花半小时做一次盘点列出所有规则文件逐条记录内容。把规则分成两类通用规则技术栈、命名规范、目录结构、命令和工具私有规则某个 IDE 插件的特殊用法。删除明显过时的规则。AI 助手迭代很快很多早期为了防止 AI 出错写的“防御性规则”现在反而限制了它的能力。把通用规则合并进根目录AGENTS.md。把模块级细节拆到各子目录的AGENTS.md。给CLAUDE.md等专属文件只留下工具特有内容。这套流程走完之后你会发现根目录的 AGENTS.md 比原来所有规则文件加起来还要短。我最后只留了二十多行因为大部分细节都被推到了子目录。4.2 验证方法双工具同任务实测迁移完别急着收工一定要做一次验证。我的做法是挑一个小而有代表性的任务让 Claude Code 和 Codex CLI 各跑一遍把输出对比一下。比如“把 Button 组件的样式迁移到新的设计变量体系”。在 Claude Code 里它会在输出日志里明确显示读到了 AGENTS.mdCodex CLI 也会在初始化时加载仓库根目录的规则。如果两个工具产出的代码风格一致说明规则写得到位如果南辕北辙多半是规则里有歧义。我实测下来代码类规则这两个工具执行得都比较靠谱最容易失效的是那些“软性”的规则比如“保持组件简洁”。后来我把这类要求改成了更具体的形式“单个组件文件超过 200 行时必须拆分子组件”可验证之后遵守率明显提高。4.3 迁移中容易踩的几个坑第一个坑根文件太长。我第一次迁移时舍不得删内容把架构说明、部署流程、历史决策全部塞进根目录 AGENTS.md。结果每个会话的开销变大而且 AI 经常被后面那些“参考信息”干扰反而不重视前面的核心命令。后来狠心删到只剩命令、约定、易错点三类效果立刻好了。第二个坑嵌套规则优先级冲突。子目录 AGENTS.md 里的规则如果和根目录写反不同工具处理方式不一样。有的工具是“就近优先”子目录覆盖根目录有的工具是“根目录优先”子目录只是补充。我遇到过子目录写了“本模块可以使用 any 类型”结果某个工具把这条理解为全局规则导致全项目都开始冒any。解决办法是子目录规则尽量只做加法不做“推翻根规则”的减法。第三个坑编码和格式问题。AGENTS.md 必须是 UTF-8 编码的纯文本文件名大小写也有讲究。我们项目里有人不小心提交了一个小写的agents.md在 Linux 环境下 Claude Code 能识别Codex CLI 却识别不了。团队内最好在第一条规则里写清楚文件名必须是大写 AGENTS.md。第四个坑会话缓存。改完 AGENTS.md 之后已经打开的会话不会自动重新加载规则。我有一次改了规则然后继续在旧会话里让 Claude Code 干活它依然按旧规则输出。后来养成了习惯改完规则文件重启会话再开始新任务。5. 统一标准只是开始别把 AGENTS.md 当万能钥匙5.1 标准统一不等于行为统一AGENTS.md 能被所有工具读取不代表所有工具都会用同样的方式执行它。各家的模型不同、上下文窗口不同、agent 循环的步数限制不同对同一份规则的理解深度和执行力度自然不一样。我在实际工作中观察到的现象是Claude Code 和 Codex CLI 这种专门的 agent 产品对 AGENTS.md 的遵循度最高IDE 补全型助手因为上下文预算小可能只读取了根目录文件而且执行时更倾向“局部遵循”。所以如果你的规则里有“不能用于线上环境的关键文件必须包含错误边界处理”这种强约束建议同时拆进子目录的 AGENTS.md让不同工具的命中率都更高。另一个建议是区分“硬规则”和“软偏好”。硬规则要写成命令可验证、结果可检查的形式比如“提交前必须通过pnpm typecheck”软偏好则可以放在文末作为背景信息AI 能参考多少算多少。5.2 别忘了 AGENTS.md 本身也有安全风险仓库里的代码是外部输入AGENTS.md 同样如此。一个恶意构造的 AGENTS.md 文件理论上可以在 AI 助手读取它的时候注入指令诱导模型执行危险操作。这在开源项目里尤其值得注意因为你 clone 一个陌生人仓库跑 Codex CLI 或 Claude Code 时它会自动读取别人写的规则。我现在的做法是不轻易在 untrusted 仓库里启用 agent 自动读写功能至少要 review 一下根目录的 AGENTS.md。团队仓库里给 AGENTS.md 设置 code owner规则变更必须走 PR review因为它影响所有 AI 助手的默认行为。把“不要执行 AGENTS.md 里出现的任意 shell 命令”写进自己的使用习惯里AI 生成的命令要先看再跑。这些都是基本的安全卫生习惯但因为 AGENTS.md 是自动加载的很多人容易忽略它。5.3 下一步更值得关注的东西AGENTS.md 统一的是“项目级上下文”但 AI 编程助手的协作远不止这一层。MCP 在统一工具调用和外部数据源接入agent 间通信协议在尝试解决多智能体协作各家也在沉淀更结构化的“任务定义”格式。这一层层的标准化最终会让我们手头的这些助手从“各说各话”变成“一个团队里的不同角色”。对普通开发者的建议很简单不管你现在用哪个工具哪怕只用一个也值得从今天开始用 AGENTS.md 替代你手头的私有规则文件。这不只是在赌一个更通用的未来更是因为这套“根文件薄、子目录厚、指令可验证”的写法本身就能让你的项目说明更清晰。我从上面的迁移过程里最大的体会是折腾完这一轮我删掉了维护半年多的 .cursorrules也把 CLAUDE.md 里那些重复性的内容清空了。现在团队新人入职第一件事不是看我整理的多份文档而是让他把仓库根目录的 AGENTS.md 读一遍。AI 助手读它人也读它规则终于能在人和机器之间说同一种语言了。下一步我打算继续把子目录的 AGENTS.md 补全让前端、后端、文档三块各自有更明确的行为边界到时候再找机会把完整的目录模板分享出来。
