9 月 19 日Claude Code 发布 2.1.277 版本更新日志第一行只有一件事项目里没有 CLAUDE.md 时Claude 会自己去读 AGENTS.md。这条更新开发者等了一年多。GitHub 上那条「请支持 AGENTS.md」的 Issue 从 2025 年 8 月挂到现在攒了 5200 多个赞是整个仓库票数最高的功能请求高出第二名四倍。消息出来Codex 团队负责人第一时间跑去留言Come to the light。一场持续一年的「说明书格式内战」就这么结束了。这篇文章讲清楚三件事这场战争怎么打起来的现在两个文件怎么分工以及你的项目应该怎么迁移。01 先回顾为什么一个 Markdown 文件能打一年CLAUDE.md 和 AGENTS.md 本质上是同一个东西写给 AI 看的项目说明书。告诉编程 Agent 这个项目怎么编译、测试怎么跑、代码按什么规矩写。每次开新对话AI 先读一遍说明书再动手。区别在于谁认。CLAUDE.md 是 Anthropic 的自留地只有 Claude Code 读。AGENTS.md 是 OpenAI 在 2025 年 8 月推出的通用格式Codex、Cursor、GitHub Copilot、Gemini CLI、Devin 都认。到今年全球超过六万个开源项目用上了 AGENTS.md活跃度抽样显示 6.2% 的 GitHub 活跃仓库有 AGENTS.md反超 CLAUDE.md 的 5.4%。1.1 痛点很真实。团队里有人用 Claude Code有人用 Codex有人用 Cursor。同一个项目得维护两份内容几乎一样的文件改个构建命令要同步改两处加个环境变量要双份复制。稍有疏忽Claude 建议你删掉 .envCodex 提醒你必须保留新人入职第一天就怀疑人生。1.2 民间想出的土办法更惨。有人做符号链接把 CLAUDE.md 链到 AGENTS.mdWindows 用户 clone 下来直接傻眼。有人用 导入语法新同事打开文件看到一行玄学咒语截图发群问这是 bug 还是行为艺术。1.3 讽刺的是Anthropic 自己就是 AGENTS.md 的推手之一。2025 年 12 月 OpenAI 把 AGENTS.md 捐给 Linux 基金会新成立的 Agentic AI FoundationAnthropic 当场签字还捐了自家的 MCP 协议。嘴硬一年身体很诚实。02 现在的规则两个文件怎么分工Claude Code 这次的默认行为叫「claude-md-or-agents-md」逻辑很简单项目里有 CLAUDE.md就读 CLAUDE.md忽略 AGENTS.md没有 CLAUDE.md就去读 AGENTS.md想改这个行为在 /config 里切换2.1 注意这个优先级设计。CLAUDE.md 优先意味着它不是简单的「兼容」而是给两个文件划了分工文件定位放什么AGENTS.md通用层所有 AI 工具都读项目规范、构建命令、测试方式、代码风格CLAUDE.md专属层只有 Claude Code 读Claude 特有的配置Hooks、MCP、sub-agent、自定义命令2.2 这个分工其实挺合理。通用规则大家共享一份工具特有的高级配置各放各的。就像 README 给人看AGENTS.md 给所有 AI 看CLAUDE.md 只给 Claude 交代私房话。2.3 目前还有些小毛病。AGENTS.md 的嵌套文件只在文本类型的 Read 操作时触发部分命令和快捷键对它支持还不完善。新功能正常等迭代就行。03 实操你的项目现在该怎么改分三种情况。3.1 项目里只有 CLAUDE.md团队只用 Claude Code什么都不用动。默认行为下一切照旧。3.2 项目里只有 CLAUDE.md但团队混用多个工具建议把通用内容抽出来建成 AGENTS.md。具体做法第一步把 CLAUDE.md 里的通用规则技术栈、代码规范、构建测试命令、业务约定原样复制到 AGENTS.md。第二步CLAUDE.md 里只留 Claude 特有的东西比如 Hooks 配置、sub-agent 定义、自定义 slash 命令的说明。第三步两份文件里都不要写重复内容各自引用自己管的领域。不然过两个月又回到「改一处忘一处」的老路。3.3 新项目从零开始直接建 AGENTS.md不用建 CLAUDE.md。除非你确定要用 Claude 特有的 Hooks 或 sub-agent 配置再补一个精简版 CLAUDE.md。04 一份能打的 AGENTS.md 长什么样格式战争结束了下一个问题是内容怎么写。大部分项目的说明书对 AI 没用因为写成了产品介绍。「本项目是一个先进的、高性能的电商平台」这种话 AI 看了等于没看。它要的是约束不是形容词。4.1 一个有效的骨架# 项目概览 一句话说清这是什么用什么技术栈 # 构建与测试 - 安装依赖pnpm install - 本地启动pnpm dev - 跑测试pnpm test提交前必须通过 - 构建产物输出到 build/ 目录不是 dist # 代码规范 - TypeScript 严格模式禁止 any - 组件用 PascalCasehooks 用 useXxx - 接口返回统一走 ApiResponse 包装 # 业务红线 - 金额一律用分存储展示时才转元 - 用户 ID 用内部 userId不混用第三方 ID # 常见坑 - 布局依赖 body 原生滚动父容器别加 overflow-y-auto - 改完 sitemap 相关代码要重新跑 generate:sitemap 校验4.2 最有价值的是最后那节「常见坑」。你踩过的坑写进去一次所有 AI 都不会再踩。这比任何 prompt 技巧都省钱。4.3 写完记得验证。分别用你团队在用的两三个工具开新对话问一句「这个项目的测试命令是什么」看它们能不能从 AGENTS.md 里答出来。答不出来说明文件没被读到检查文件名和位置。05 最后说两句过去一年 AI 编程圈的很多「分裂」都在收口MCP 统一了工具调用AGENTS.md 统一了项目说明书。对开发者来说这是纯好事配置成本在降工具切换的摩擦力在消失。这件事真正的启发是AI 工具的竞争壁垒正在从「锁定用户」转向「融入生态」。你的项目资产规范、流程、经验沉淀成标准格式之后换工具就像换编辑器一样轻。早一天把这些资产整理成 AGENTS.md就早一天不被任何一家绑架。今天就能动手打开你的项目把 CLAUDE.md 里的通用规则抽成 AGENTS.md十分钟的事。相关阅读AI 工具导航与 AI 资讯ai345.info收录几千个 AI 工具Claude Code、Codex、Cursor 都有实测介绍按场景分类挑工具很省事上篇别再复制粘贴 Prompt 了用 CLAUDE.md 和 Hooks 把 AI 编程工具调教成你的专属助手AGENTS.md 官方站点https://agents.mdIT之家报道https://m.ithome.com/html/1004351.htm