1. 从两份说明书说起AGENTS.md 到底解决了谁的痛点如果你同时用 Claude Code 和 Codex 这两个编码 Agent大概率经历过这样的场景项目根目录下躺着一个CLAUDE.md写着项目的技术栈、目录结构、编码规范、测试命令后来为了用 Codex又在同一个目录下建了一个AGENTS.md内容大同小异只是措辞和格式稍微调整了一下。再后来团队里有人用别的 Agent 工具又加了一份配置文件。三份文件三套说法改了一处忘了同步另外两处新来的同事看着三个文件不知道该信哪个。这个问题的本质不是文件太多而是项目上下文没有单一可信来源。Agent 类工具在启动时会读取项目根目录下的说明文件把它作为系统提示的一部分注入到对话里用来告诉模型这个项目是干什么的、代码怎么组织、有哪些约定不能违反。不同厂商、不同工具各自定义了自己的文件名和读取规则于是同一份知识被复制成了多份。Claude Code 正式支持AGENTS.md这件事价值就在这里它不再只认CLAUDE.md而是把AGENTS.md也纳入了读取范围。这意味着你可以把项目说明收敛到一份文件上让 Claude Code、Codex 以及其他遵循AGENTS.md约定的工具共用同一份上下文。跨 Agent 维护两份说明书的时代至少在 Claude Code 这一侧可以结束了。这篇文章适合三类人看一是已经在日常开发里用 Claude Code 或 Codex 的工程师想知道怎么迁移和配置二是团队里负责工程规范的人想统一 Agent 的项目上下文三是刚开始接触 Agent 编码工具、还没搞清楚这些 md 文件到底起什么作用的新手。我会从文件读取机制讲起把优先级、迁移方案、多 Agent 共存写法、踩坑经验都过一遍尽量让你看完就能直接动手改自己的项目。2. AGENTS.md 与 CLAUDE.md 的读取机制拆解2.1 Agent 是怎么读项目说明书的要理解这次支持的意义得先搞清楚 Agent 工具读取项目说明文件的完整链路。以 Claude Code 为例它在一次会话启动时会从几个位置收集上下文全局配置目录下的用户级说明、项目根目录下的项目级说明、以及当前工作目录向上逐级查找的说明文件。这些内容会被拼接成一段文本作为系统提示的一部分发给模型。关键点在于查找顺序和优先级。工具通常按越靠近当前工作目录、越具体的原则来决定谁覆盖谁。用户级配置提供的是个人偏好比如我习惯用 pnpm 不用 npm项目级配置提供的是团队约定比如这个仓库用四空格缩进、提交信息遵循 Conventional Commits。当两者冲突时项目级通常优先因为它更贴近当前任务的实际约束。AGENTS.md被纳入支持后读取逻辑变成了工具会同时检查CLAUDE.md和AGENTS.md是否存在按既定优先级决定加载哪些、以什么顺序拼接。这里有个容易误解的地方——支持不等于自动合并去重。如果两个文件都存在且内容有冲突工具不会智能判断哪句是对的它只是按顺序把内容都塞进上下文最终模型看到的是两份说明的叠加。冲突内容会让模型产生困惑所以支持 AGENTS.md的正确用法是二选一或明确分工而不是无脑两份都留。2.2 为什么是 AGENTS.md 而不是继续用 CLAUDE.mdAGENTS.md这个名字本身就是一种去厂商化的信号。它不绑定任何一家工具语义上就是给 Agent 看的说明。Codex 早期就采用了这个约定社区里其他 Agent 工具也陆续跟进。当多个工具都认这个文件名时它就从某家的私有约定变成了事实上的通用约定。Claude Code 选择支持它本质上是承认了这个事实标准。对用户来说好处很直接项目里只需要维护一份AGENTS.mdClaude Code 能读Codex 能读未来接入其他工具大概率也能读。你不再需要为了换工具而重写一遍项目说明也不用担心某个工具更新后读取规则变了导致上下文丢失。从工程管理角度看这降低了上下文漂移的风险。所谓上下文漂移就是同一份知识在不同文件里被维护成了不同版本时间一长没人知道哪个是最新的。收敛到单一文件后代码评审时改AGENTS.md的 diff 一目了然谁改了什么、为什么改都有迹可循。2.3 读取优先级与冲突处理的实际表现实测下来当CLAUDE.md和AGENTS.md同时存在时不同版本的行为不完全一致有的版本会优先加载CLAUDE.md有的会把两者都加载。这个不确定性本身就是风险——你无法保证模型最终看到的是哪一份。我的建议很明确迁移完成后删掉CLAUDE.md只留AGENTS.md。如果你确实需要保留CLAUDE.md比如团队里还有人在用旧版本工具那就让CLAUDE.md只写一句项目说明见 AGENTS.md把它当成一个指针而不是第二份说明书。这样既兼容了旧工具又避免了内容重复。还有一种情况是 monorepo。根目录放一份AGENTS.md写全局约定各个子包目录下再放各自的AGENTS.md写包内特定规则。工具在进入某个子目录工作时会加载该目录及向上各级的说明文件形成全局 局部的上下文叠加。这种分层写法比把所有内容堆在一个文件里要清晰得多也更容易维护。3. 迁移实操把 CLAUDE.md 平滑换成 AGENTS.md3.1 迁移前的盘点你的 CLAUDE.md 里都写了什么动手之前先做一次内容盘点。把现有CLAUDE.md从头读一遍把内容分成几类项目概述类项目是做什么的、技术栈、核心模块。结构说明类目录布局、关键文件位置。规范约定类代码风格、命名规则、提交信息格式。命令类构建、测试、lint、启动开发服务器的命令。个人偏好类某个开发者自己的习惯比如我喜欢用某个库。分类的目的是判断哪些该留在项目级文件里哪些该挪到用户级配置。个人偏好类内容不应该出现在项目级AGENTS.md里因为它对团队其他人不适用放进去反而会干扰模型。命令类和规范约定类是项目级的核心内容必须保留。项目概述和结构说明类可以精简因为模型也能通过读代码自己推断一部分写太多反而占上下文。3.2 直接重命名还是重写两种策略的取舍最简单的迁移方式是git mv CLAUDE.md AGENTS.md改个名字就完事。这种方式适合内容本来就写得比较干净、没有厂商特定措辞的项目。但如果你原来的CLAUDE.md里有一些针对 Claude 的特定表述比如作为 Claude你应该……那重命名后读起来就有点怪建议顺手改成中性表述。另一种策略是借这次迁移重写一遍。我倾向于这种方式原因是大多数项目的CLAUDE.md都是长期迭代堆出来的里面有不少过时内容、重复表述、甚至互相矛盾的规则。趁迁移的机会清理一遍把文件压缩到真正必要的部分对模型理解和后续维护都有好处。重写时有个原则写约束不写教程。AGENTS.md不是给人看的入门文档是给模型看的约束清单。所以运行测试用pnpm test比本项目使用 pnpm 作为包管理器pnpm 是一个快速、节省磁盘空间的包管理工具……要好得多。模型不需要你解释 pnpm 是什么它需要知道在这个项目里该敲哪条命令。3.3 迁移后的验证怎么确认 Agent 真的读到了改完文件名不代表就生效了。你需要验证 Agent 确实加载了新文件。最直接的办法是在会话里问它一个只有AGENTS.md里才有的信息比如这个项目的测试命令是什么看它回答得对不对。如果答错了或者答不上来说明文件没被读到或者路径不对。另一个验证点是观察 Agent 的行为是否符合约定。比如你在AGENTS.md里写了所有新文件必须带 license header然后让它新建一个文件看它有没有自动加上。行为验证比问答验证更可靠因为它检验的是模型有没有真正把约束内化到操作里。如果验证失败排查顺序是文件是否在项目根目录、文件名拼写是否正确注意大小写Linux 下agents.md和AGENTS.md是两个文件、工具版本是否支持、是否有其他配置文件覆盖了它。这几点按顺序查一遍基本能定位问题。4. 多 Agent 共存一份 AGENTS.md 怎么喂饱所有工具4.1 Claude Code、Codex 与其他工具的读取差异虽然大家都认AGENTS.md但不同工具在细节上还是有差异。Codex 对AGENTS.md的支持比较早读取逻辑相对成熟支持在子目录里放局部说明文件。Claude Code 现在也支持了但在优先级处理上和 Codex 可能有细微不同。其他工具比如一些开源的 Agent 框架有的认AGENTS.md有的认自己的文件名有的支持配置自定义路径。这些差异意味着一份AGENTS.md要写得足够中性才能被所有工具正确理解。避免使用某个工具特有的语法或占位符比如某些工具支持的{{variable}}模板语法换个工具就读不懂了。用最朴素的 Markdown 写标题、列表、代码块这些是所有工具都能解析的。4.2 用符号链接还是真文件一个容易被忽略的选择有人会想我能不能建一个AGENTS.md然后给CLAUDE.md做个符号链接指向它技术上可行ln -s AGENTS.md CLAUDE.md一行命令搞定。但这里有个坑部分工具在读取文件时会做路径解析符号链接可能导致读取失败或读到错误内容。而且符号链接在 Windows 上支持不好团队里如果有 Windows 用户就会出问题。更稳妥的做法是只保留AGENTS.md需要兼容旧工具时用指针文件方案——CLAUDE.md里只写一行See AGENTS.md for project instructions。这样既没有符号链接的兼容性问题又保证了内容单一来源。4.3 分层组织根目录与子目录的 AGENTS.md 怎么配合大型项目建议用分层写法。根目录的AGENTS.md写全局内容项目定位、整体技术栈、跨模块的通用规范、全局命令。子目录的AGENTS.md写局部内容这个模块的特殊约定、模块内特有的命令、该模块依赖的注意事项。举个例子一个前后端同仓的项目根目录写这是一个 TypeScript monorepo前端用 React后端用 Node统一用 pnpm workspace 管理。frontend/AGENTS.md写前端组件用函数式写法样式用 CSS Modules测试用 Vitest。backend/AGENTS.md写后端用 Fastify数据库访问统一走 repository 层测试用 Node 内置 test runner。这样 Agent 在前端目录工作时加载的是根目录加前端目录的说明上下文精准且不冗余。分层写法的另一个好处是变更影响范围可控。改前端规范只动frontend/AGENTS.md不会影响后端。代码评审时diff 的范围也清晰。5. 写一份高质量 AGENTS.md 的实战要点5.1 内容取舍什么该写什么不该写写AGENTS.md最容易犯的错是什么都往里塞。文件越长模型抓重点的能力越弱而且每次会话都要消耗上下文预算。我的经验是控制在一到两屏能读完的长度超过这个量就该考虑拆分或精简了。该写的内容不可从代码推断的约定比如提交信息用中文、容易踩错的命令比如测试必须先启动 mock server、架构层面的约束比如不要在组件里直接调 API走统一的 service 层。不该写的内容能从代码看出来的东西比如项目用 React——看 package.json 就知道、通用编程常识比如写清晰的变量名、临时性的任务说明那应该放在 issue 里而不是项目说明里。一个判断标准如果这条信息删掉后Agent 有较大概率做错事那就该写如果删掉后它大概率还是能做对那就不写。5.2 措辞技巧怎么让模型更准确地遵守给模型写约束措辞直接影响遵守率。几个实测有效的技巧用祈使句不用描述句。使用四空格缩进比本项目采用四空格缩进风格更直接。用具体例子代替抽象描述。导入顺序先第三方库再项目内模块最后相对路径比保持导入顺序整洁有用得多。把强约束和弱建议分开强约束用必须禁止弱建议用建议优先。还有一个技巧是给出反例。有些约定光说要怎样不够还得说不要怎样。比如不要用 default export统一用 named export这样模型就不会在两种写法之间犹豫。5.3 维护节奏什么时候该更新这份文件AGENTS.md不是写完就一劳永逸的。项目演进过程中技术栈会变、目录结构会调整、命令会更新这些都需要同步到文件里。我的做法是把它纳入代码评审流程任何改变了项目结构或约定的 PR如果没同步更新AGENTS.md评审时就应该提出来。另一个更新时机是发现 Agent 反复犯同一个错。如果它总是用错某个命令或者总是违反某条约定说明这条约定要么没写、要么写得不够醒目。这时候就该去AGENTS.md里补一条或者把已有的那条加粗、提前。定期清理也很重要。过时的约定比没有约定更糟糕因为它会误导模型。每隔一两个月扫一遍把不再适用的内容删掉。6. 踩坑记录迁移过程中真实遇到的问题6.1 文件名大小写导致的文件不存在这个坑我在 Linux 环境下踩过。当时把文件命名为agents.md全小写本地测试没问题因为 macOS 文件系统默认大小写不敏感。推到 CI 或者部署到 Linux 服务器后工具按AGENTS.md去找找不到上下文直接丢失。排查了半天才意识到是大小写问题。统一用全大写AGENTS.md这是社区约定也是各工具默认查找的名字。在大小写敏感的系统上这一点必须严格遵守。6.2 内容冲突两份文件同时存在时的诡异行为前面提过CLAUDE.md和AGENTS.md同时存在时行为不确定。我遇到的具体表现是Agent 有时候遵守CLAUDE.md里的旧约定有时候遵守AGENTS.md里的新约定同一个会话里前后不一致。这种精神分裂式的行为非常难排查因为你看不到模型到底加载了哪些内容。解决办法就是前面说的迁移后删掉旧文件或者把旧文件改成指针。不要给模型两份可能冲突的说明书。6.3 上下文预算文件太长反而拖累效果有一次我接手一个项目CLAUDE.md写了将近八百行从项目背景到每个模块的详细说明应有尽有。结果 Agent 的表现反而不好经常忽略一些关键约定。后来分析发现文件太长导致关键信息被淹没在大量次要内容里模型的注意力被稀释了。精简到一百多行后Agent 的遵守率明显提升。这个经历让我意识到给模型的上下文不是越多越好而是要密度高、重点突出。把八百行压缩到一百行删掉的都是模型能自己推断或根本用不上的内容留下的都是真正影响行为的约束。6.4 子目录文件不生效的排查路径分层写法虽然好但子目录的AGENTS.md不生效是常见问题。排查路径是这样的先确认文件确实在子目录里且名字正确再确认 Agent 当前的工作目录是不是那个子目录如果它在根目录工作就不会加载子目录的说明然后确认工具版本是否支持子目录读取最后看是不是被根目录的同名配置覆盖了。实测下来最常见的原因是工作目录不对。Agent 在根目录启动你却在子目录里放了说明文件它自然读不到。解决办法是要么在子目录里启动 Agent要么把关键约定也写一份到根目录。7. 这套方案还能怎么扩展AGENTS.md收敛之后下一步可以考虑的是把项目说明和实际工程实践打通。比如在 CI 里加一个检查确保AGENTS.md里提到的命令都是真实可用的或者写个脚本从package.json的 scripts 自动生成命令说明段落减少手工维护。另一个方向是团队协作层面的规范化。把AGENTS.md的编写纳入新项目脚手架每个新仓库初始化时就带一份模板包含项目概述、命令、规范三个基本段落。这样团队里所有项目的 Agent 上下文格式统一切换项目时不用重新适应。我个人在实际操作中的体会是AGENTS.md这件事看起来只是改个文件名但它背后反映的是 Agent 工具生态正在从各自为政走向约定趋同。对使用者来说这意味着更少的重复劳动和更低的迁移成本。早点把项目说明收敛到一份文件上后面换工具、加工具的时候你会感谢现在的自己。