1. 从两份说明书说起AGENTS.md 到底解决了什么痛点如果你同时用 Claude Code 和 Codex 写代码大概率经历过这种别扭事项目根目录下躺着一个CLAUDE.md写着项目结构、编码规范、测试命令转头打开 Codex它不认这个文件你得再维护一份AGENTS.md内容大差不差但格式要求、字段命名又略有出入。改一次架构两个文件都得动漏掉一个就开始出现Agent 按旧规范写代码的诡异现象。Claude Code 正式支持AGENTS.md这件事本质上就是把这份重复劳动砍掉了一半。现在你可以只维护一份AGENTS.mdClaude Code 会把它当作项目级上下文来读取和 Codex 共用同一套说明。对多 Agent 协作的团队来说这不是多支持一个文件名这么简单而是把项目说明书从每个工具一份变成了项目一份、工具共享。先把概念理清楚避免后面绕晕。AGENTS.md是一份放在项目仓库里的 Markdown 文件用自然语言描述这个项目的关键信息目录结构、技术栈、构建与测试命令、代码风格、禁止事项、常见坑。它的定位是给 AI 编码助手看的 README——README 是给人看的讲的是怎么用这个项目AGENTS.md是给 Agent 看的讲的是怎么改这个项目。CLAUDE.md是 Claude Code 早期专属的项目记忆文件格式和AGENTS.md高度相似但只被 Claude Code 识别。Codex 走的是AGENTS.md路线OpenAI 那边把它作为跨工具的项目约定来推。两边各认各的就出现了开头说的双份维护问题。这次支持之后Claude Code 的读取优先级大致是这样的如果项目里同时存在CLAUDE.md和AGENTS.md它会按自己的规则合并或择一具体行为随版本演进建议以你本地版本的实测为准如果只有AGENTS.md它就直接用。这意味着新项目可以直接上AGENTS.md老项目可以逐步把CLAUDE.md的内容迁移过去最终只留一份。谁最该关注这件事三类人。第一类是同时用多个 Agent 的独立开发者省下的是实打实的维护时间。第二类是团队里负责AI 工程化的人统一说明书意味着新人接入任何 Agent 都看同一份规范。第三类是刚开始接触 Agent 编码工具的新手从第一天就用对文件比后面迁移省事得多。提示AGENTS.md不是配置文件没有严格的 schema它是自然语言文档。写得越具体、越贴近真实操作Agent 的表现越稳写得越空泛越容易被忽略。2. AGENTS.md 与 CLAUDE.md 的差异拆解与选型思路2.1 两者到底差在哪从字段到读取逻辑很多人以为这俩只是文件名不同其实在细节上有几处值得注意的差异。下面这张表是我在实际项目里对比出来的供你选型时参考。维度CLAUDE.mdAGENTS.md主要服务对象Claude Code跨工具约定Codex 等均识别文件位置项目根目录也支持子目录项目根目录支持嵌套子目录格式约束自然语言无强制 schema自然语言社区有推荐结构多文件支持支持分层覆盖支持分层覆盖子目录就近优先迁移成本迁到 AGENTS.md 基本是复制粘贴迁到 CLAUDE.md 需检查字段差异从表里能看出来AGENTS.md的定位更中立。它不绑定某一个厂商的工具谁认这个约定谁就能读。这也是为什么这次 Claude Code 跟进支持被很多人看作向通用约定靠拢的信号。选型思路其实很简单新项目直接上AGENTS.md别犹豫。老项目如果只有CLAUDE.md先别急着删确认你当前 Claude Code 版本对AGENTS.md的支持稳定后再把内容迁过去保留一段时间双文件并行做过渡。团队协作场景下统一到AGENTS.md的收益最大因为 Codex 用户和 Claude Code 用户看的是同一份东西评审时不会出现你按你的规范、我按我的规范。2.2 为什么是 AGENTS.md 胜出而不是各搞各的这里有个容易被忽略的逻辑Agent 编码工具的核心竞争力之一是对项目的理解程度。理解从哪来从上下文来。上下文里最稳定、最可控的部分就是项目自己提供的说明书。如果每个工具都要求一份专属说明书那项目维护者就被绑死在工具选择上——换工具等于重写文档迁移成本高得离谱。AGENTS.md作为跨工具约定把这个成本降下来了。它的价值不在于格式多先进而在于大家都认。这跟.editorconfig统一编辑器风格、package.json统一 Node 项目元信息是一个道理约定本身不神奇神奇的是生态都接受它。Claude Code 支持它等于承认了项目说明书应该是项目资产而不是工具资产。这个转变对长期维护的项目意义很大。你想想一个跑了两年的项目CLAUDE.md里积累了无数踩坑记录和架构决策如果哪天团队决定换工具这些内容能不能带走能只要它在AGENTS.md里。2.3 迁移前必须想清楚的三件事第一件内容归属。CLAUDE.md里有些内容是 Claude Code 特有的技巧比如某些提示词写法这些迁到AGENTS.md后可能对 Codex 无意义甚至产生误导。迁移时要把通用项目信息和工具专属技巧分开前者进AGENTS.md后者可以留在本地或单独文档。第二件层级结构。两个文件都支持子目录嵌套但覆盖规则可能不同。迁移前先确认你项目里有没有子目录级的CLAUDE.md如果有要一并规划子目录的AGENTS.md否则会出现根目录规范生效、子目录规范丢失的情况。第三件版本兼容。不同版本的 Claude Code 对AGENTS.md的支持程度不一样有的版本可能只读根目录有的支持嵌套。迁移前用一个小项目实测一遍确认读取行为符合预期再动主项目。注意迁移不是删旧建新就完事。建议保留CLAUDE.md至少一个迭代周期观察 Agent 行为有没有退化确认无误后再清理。3. 一份高质量 AGENTS.md 的结构设计与实操写法3.1 推荐结构从项目是什么到别碰什么写AGENTS.md最忌讳的是写成散文。Agent 读文档是为了执行任务它需要的是可检索、可定位的信息。我实践下来下面这个结构最稳按重要性排序项目概述一句话说清项目做什么、技术栈是什么。目录结构关键目录及用途标注哪些是生成物、哪些是手写代码。构建与测试命令精确到可直接复制执行的命令。代码规范命名、格式、导入顺序、注释要求。禁止事项明确列出不能做的事比如不能改生成文件、不能引入某类依赖。常见坑与背景知识那些不看就会踩的隐性规则。这个顺序的逻辑是先让 Agent 建立全局认知再给它操作手段最后用禁止事项兜底。很多人的AGENTS.md只写了前两条结果 Agent 能看懂项目但一动手就出错问题往往出在缺少禁止事项和背景知识。3.2 每个部分怎么写才有效项目概述部分控制在三到五行。写清楚技术栈版本很关键比如Node 20 TypeScript 5.4 pnpm而不是笼统的用 Node 和 TS。版本信息直接影响 Agent 生成的代码语法写清楚能省掉大量返工。目录结构部分用列表而不是树形图。树形图好看但难检索列表更实用。每个目录后面跟一句用途说明比如src/core/核心业务逻辑纯函数为主不依赖框架。src/adapters/外部接口适配层所有网络请求集中在这里。generated/自动生成代码禁止手动修改。构建与测试命令部分给完整命令不要给运行测试这种模糊描述。要写成pnpm test --filtercore这种可直接执行的。如果测试有前置步骤比如先起本地服务也要写进去。代码规范部分只写那些Agent 容易搞错的点。通用的格式规范交给 linter 就行不用在AGENTS.md里重复。重点写项目特有的约定比如所有异步函数必须显式处理错误禁止裸 await。禁止事项部分是价值最高的。把你踩过的坑都写进去不能改哪些文件、不能引入哪些依赖、不能用的 API。这一部分写得越具体Agent 越不容易闯祸。3.3 一个可直接抄的模板下面这份模板是我在多个项目里迭代出来的你可以直接拿去改。# AGENTS.md ## 项目概述 - 技术栈Node 20 TypeScript 5.4 pnpm - 用途订单处理服务对外提供 REST API - 入口src/index.ts ## 目录结构 - src/core/核心业务逻辑纯函数无框架依赖 - src/adapters/外部接口适配网络请求集中于此 - src/api/HTTP 路由与参数校验 - generated/自动生成禁止手动修改 - tests/测试用例与 src 目录结构对应 ## 构建与测试 - 安装依赖pnpm install - 本地开发pnpm dev - 运行测试pnpm test - 单文件测试pnpm test file - 类型检查pnpm typecheck ## 代码规范 - 异步函数必须显式 try/catch禁止裸 await - 导入顺序node 内置 → 第三方 → 本地组间空行 - 所有导出函数必须有 JSDoc 注释 - 禁止使用 any必要时用 unknown 类型守卫 ## 禁止事项 - 禁止修改 generated/ 下任何文件 - 禁止在 core/ 中引入网络请求库 - 禁止新增依赖如需新增先说明理由 - 禁止提交 console.log 调试代码 ## 常见坑 - 测试依赖本地 Redis跑测试前先执行 pnpm redis:start - 时区统一用 UTC禁止用本地时间 - 金额字段统一用整数分禁止用浮点这份模板大概一百多行覆盖了日常开发 90% 的场景。你可以根据项目特点增删但建议保留禁止事项和常见坑这两块它们是防止 Agent 犯错的关键。3.4 子目录 AGENTS.md 的用法大项目里根目录的AGENTS.md不可能写全所有细节。这时候用子目录级的AGENTS.md做局部覆盖。比如src/adapters/AGENTS.md里写这个目录特有的约定所有适配器必须实现统一的接口、错误必须转成项目自定义错误类型、超时时间统一配置。子目录文件的读取逻辑是就近优先Agent 处理src/adapters/下的文件时会同时读根目录和该子目录的AGENTS.md冲突时子目录优先。这个机制让你可以把通用规范放根目录、局部规范放子目录避免根目录文件无限膨胀。提示子目录AGENTS.md不要写和根目录重复的内容只写差异部分。重复内容不仅浪费上下文还容易在更新时漏改一处导致矛盾。4. 多 Agent 协作下的实操流程与配置细节4.1 从零搭建新项目的标准动作新项目第一天就把AGENTS.md建起来比后面补要省事得多。我的标准动作是初始化项目后先写AGENTS.md骨架再写第一行业务代码。骨架不用很全把项目概述、目录结构、构建命令三块填上就行剩下的随着开发逐步补。为什么先写文档再写代码因为写文档的过程会逼你想清楚项目结构。很多人上来就写代码写到一半发现目录乱了、命令不统一回头再补文档文档和现实已经对不上了。先写文档相当于先画图纸再施工返工少。具体步骤创建项目初始化package.json或对应语言的工程文件。在根目录创建AGENTS.md填入项目概述和预期目录结构。确定构建、测试、类型检查命令写进文档。提交一次让文档成为项目的一部分。后续每次调整结构或命令同步更新文档。第 5 步是最容易被忽略的。文档一旦和现实脱节Agent 就会按过时信息操作反而添乱。建议把更新 AGENTS.md写进代码评审清单改结构必须改文档。4.2 老项目迁移分三步走老项目迁移别想着一步到位分三步更稳。第一步盘点。把现有CLAUDE.md通读一遍把内容分成三类通用项目信息、Claude Code 专属技巧、过时内容。通用信息是要迁的专属技巧留着或单独归档过时内容直接删。第二步试迁。在项目里新建AGENTS.md把通用信息填进去先不删CLAUDE.md。用 Claude Code 跑几个典型任务观察行为有没有变化。重点看它是否还遵守原来的规范、是否出现新的错误。第三步切换。确认无误后把CLAUDE.md精简成一行指向AGENTS.md的说明或者直接删除。保留一个迭代周期后彻底清理。这个流程的核心是可回退。直接删旧文件风险太大万一新文件有遗漏Agent 行为退化你都不知道从哪查。保留旧文件做对照出问题能快速定位。4.3 和 Codex 共用的注意事项既然目标是一份文档两个工具用那就要考虑两个工具的读取差异。实测下来有几个点要注意。命令写法上Claude Code 和 Codex 对命令的解析能力不同。有些复杂命令带管道、带环境变量在一边能跑另一边可能被截断。建议AGENTS.md里的命令尽量简单复杂操作拆成多步写。文件引用上两个工具对路径的解析基准可能不同。写路径时统一用相对项目根目录的路径避免歧义。上下文长度上两个工具对AGENTS.md的读取长度限制不同。文档太长可能被截断导致后面的内容读不到。建议把最重要的信息放前面禁止事项和常见坑这类关键内容不要放太后面。注意如果你的AGENTS.md超过几百行考虑拆分到子目录文件而不是全堆在根目录。上下文是有限资源别浪费在重复和冗余上。4.4 团队协作下的文档治理一个人用AGENTS.md和团队用是两回事。团队场景下文档会变成多人编辑的公共资产需要治理规则。谁负责更新建议指定一个文档 owner或者按模块分工改src/adapters/的人负责更新对应的子目录文档。避免出现谁都不管、文档烂掉的情况。怎么评审把AGENTS.md的改动纳入代码评审。改文档和改代码一样需要 review防止有人塞进错误信息误导 Agent。怎么处理冲突多人同时改文档容易冲突。建议小步提交每次只改一个主题减少合并冲突。冲突时以更具体、更贴近当前代码的版本为准。版本怎么管AGENTS.md跟着代码走用同一个版本控制。不要单独维护一份文档版本那样迟早对不上。5. 常见问题排查与踩坑实录5.1 Agent 不读 AGENTS.md 怎么办最常见的问题是我写了文档但 Agent 好像没看。排查顺序如下。先确认文件名和位置。必须是根目录下的AGENTS.md大小写敏感。写成agents.md或放在子目录里可能读不到。再确认版本支持。老版本 Claude Code 可能不支持AGENTS.md只认CLAUDE.md。升级到支持版本再试。然后确认内容格式。文档开头如果有大量无关内容Agent 可能读到了但没重视。把关键信息放前面用清晰的标题分隔。最后用测试验证。在文档里写一条明显的规则比如所有函数名用 snake_case然后让 Agent 写个函数看它是否遵守。遵守说明读取正常不遵守说明有问题。5.2 文档写了但 Agent 不遵守读取正常但不遵守通常是文档写得太模糊。比如写代码要整洁Agent 不知道什么叫整洁。改成函数不超过 50 行、嵌套不超过 3 层就可执行了。另一个原因是规则太多、互相冲突。Agent 面对矛盾规则时会随机选一个。定期清理文档删掉过时和矛盾的条目。还有一种情况是规则和代码现实不符。文档说用 A 方案代码里全是 B 方案Agent 会倾向于跟随代码。这时候要么改代码要么改文档别让两者打架。5.3 排查速查表现象可能原因排查动作Agent 完全无视文档文件名/位置错误、版本不支持检查文件名大小写、升级版本部分规则不生效文档太长被截断关键内容前移、拆分文件规则互相矛盾文档未清理通读全文、删除冲突条目子目录规则不生效子目录无 AGENTS.md在子目录补建文件迁移后行为退化内容遗漏对照旧 CLAUDE.md 逐条核对两个工具行为不一致命令/路径写法差异简化命令、统一相对路径5.4 几个我踩过的坑第一个坑把AGENTS.md写成了项目 README 的复制品。README 讲怎么用AGENTS.md讲怎么改两者受众不同。复制 README 会导致 Agent 拿到一堆用户视角的信息缺少开发者视角的规范。第二个坑文档里写了参考 xxx 文件。Agent 不一定去读那个文件写了等于没写。要么把关键内容直接写进AGENTS.md要么明确说修改前必须先读 xxx 文件。第三个坑迁移时把 Claude Code 专属的提示词技巧也搬过去了。这些技巧对 Codex 无意义还占上下文。迁移时要做减法不是全盘复制。第四个坑文档更新滞后。改了构建命令没改文档Agent 按旧命令执行失败排查半天才发现是文档问题。现在我把改命令必须改文档当成硬规则。第五个坑子目录文档写太多。每个子目录都写一大篇结果 Agent 读的时候上下文被塞满反而忽略了根目录的关键规则。子目录文档只写差异越短越好。6. 把 AGENTS.md 用出复利长期维护的几个习惯AGENTS.md的价值不是一次写成的是长期维护出来的。我观察下来用得好的项目都有几个共同习惯。习惯一把踩过的坑即时写进去。每次 Agent 犯了个错排查完就在AGENTS.md里加一条规则防止再犯。这样文档会越来越贴合项目实际Agent 表现越来越稳。这比一次性写一篇完美文档有用得多因为真实项目里的坑是逐步暴露的。习惯二定期精简。文档只增不减会越来越臃肿上下文被浪费。每隔一段时间通读一遍删掉过时内容、合并重复条目、把不再需要的规则移除。精简后的文档 Agent 读起来更聚焦。习惯三区分必须遵守和建议。必须遵守的用明确措辞禁止必须建议的用推荐优先。Agent 对措辞的敏感度比人高措辞清晰能减少误判。习惯四和代码同步演进。项目重构、换依赖、改命令时把AGENTS.md当成代码的一部分一起改。别让它变成历史文档。习惯五跨工具验证。既然目标是多工具共用就定期用不同工具跑同一批任务看行为是否一致。不一致的地方往往是文档写得不够明确正好借机改进。这套习惯坚持下来AGENTS.md会从一份说明变成项目的活文档。新人和新 Agent 接入时读这一份就能上手不用再问东问西。这才是它真正的复利所在——省下的不只是维护两份文档的时间还有每次沟通、每次排查、每次返工的成本。最后分享一个我自己的小做法在AGENTS.md末尾留一个最近更新区块记录最近几次改了什么、为什么改。这样回溯时能快速知道某条规则的来龙去脉避免误删。这个区块不用长一两行一次就够但长期积累下来它本身就是一份项目决策日志。