最近在调多Agent协作流程一个困扰很久的问题被一次更新顺手解决了Claude Code 官方支持了 AGENTS.md。这句话放在社区里可能只是一条更新日志但对我这种同一个仓库要同时维护Claude Code、Cursor、Cline等好几款AI编码工具的人来说真的是“项目说明书终于能只写一份了”。过去我经常在改代码规范时更新完CLAUDE.md转头忘记同步给其他工具过几天用另一个Agent干活它还在按旧的约定跑代码风格自然就乱了。这篇文章我就从AGENTS.md的来源讲起把这次更新涉及的加载规则、迁移步骤、多Agent共存策略和踩坑经验一次性梳理清楚。无论你只用Claude Code还是跟我一样同时开着好几个Agent工具这篇都能直接用上。1. AGENTS.md 是什么它凭什么成为通用说明书1.1 各家AI编码工具自建“说明书”的混乱期我最早接触Claude Code的时候项目里维护的是CLAUDE.md。当时感觉挺自然Claude Code读取这个文件作为项目级记忆告诉我这个仓库是干什么的、用什么命令、守什么规矩。后来开始用Cursor发现人家默认读的是.cursorrules再后来试Cline它又习惯看自己的规则文件还有人以context.md作为泛化约定把上下文说明放在里面。本质都是同一件事给Agent一段“仓库级背景知识”。问题是格式不互通于是同一个项目就得给每个工具各备一份而它们的内容又高度重叠都是技术栈、常用命令、目录结构、代码风格这些信息。真正让人崩溃的是维护过程。你改了测试命令CLAUDE.md更新了其他工具的文件忘了同步过两天用Cursor开个会话Agent还在跑旧的命令报错了都不知道为什么。团队里如果正好有同事只用某一个工具情况会更乱规则文件散落在各个目录没人分得清哪份是有效的。那段时间我甚至想把所有说明合并成一个docs/project-guide.md让每个工具都去读它但各家工具并不认识这种自定义文件名设想一直没落地。所以当AGENTS.md被当作通用标准推出来时我是第一批跟着切换的人。1.2 AGENTS.md 能成为通用格式的几个关键原因GitHub在推动Agent协作规范的时候把AGENTS.md定位成了仓库级的默认说明书相当于告诉所有AI编码工具想了解这个仓库的规则先来看这个文件。很快Cursor、Cline、Windsurf包括GitHub Copilot等工具都开始对齐这个规范Claude Code这次正式支持AGENTS.md算是把最后一块关键的拼图补上了。我用下来觉得它能在短时间内被各家接受主要靠三点文件名足够直白。AGENTS.md一眼就知道是给Agent看的东西不像CLAUDE.md那么绑定单一产品也不像.cursorrules那样一看就是某个工具的私有格式。语法足够简单。就是普通Markdown不需要学任何私有语法现有的CLAUDE.md内容几乎可以原样搬过来。兼容成本很低。各工具大都是在原有规则文件之外新增读取AGENTS.md而不是强制替换对存量项目非常友好。第三点对存量项目太重要了。我手头几十个仓库里已经有一批CLAUDE.md写得非常成熟如果官方一刀切说“以后只认AGENTS.md”迁移风险会大很多。现在这种“新增支持”的方式就可以一边保留CLAUDE.md一边慢慢把规则迁到AGENTS.md上过渡期不会让现有工作流断掉。另外也有朋友问过context.md跟AGENTS.md到底选哪个我的看法是AGENTS.md目前在工具兼容性上远远领先context.md更像是泛化命名不建议拿它当主文件否则又回到了“各读各的”老路上。2. Claude Code 读取 AGENTS.md 的核心机制2.1 作用域根目录负责全局子目录负责局部先说加载位置。按照社区通用约定AGENTS.md 和 CLAUDE.md 一样是有作用域概念的。放在仓库根目录意味着你对整个项目生效放在某个子目录里则只在该目录下干活时生效。这个设计在项目里非常实用。举一个我实际碰到的场景。公司有个monorepo前端部分用ReactTypeScript后端是Python的FastAPI。根目录AGENTS.md里写的是“本仓库是什么、如何安装依赖、如何跑全量测试”这类全局信息前端子目录的AGENTS.md里写“必须使用严格模式、UI组件统一走design-system包”后端子目录的AGENTS.md里写“接口入参校验用Pydantic、数据库迁移必须先生成再review”。这样每个Agent进入对应子目录工作时拿到的是更精准的局部约束不会被根目录里无关的规则干扰。还有一点容易忽略如果你是直接在Claude Code执行任务的目录里放了AGENTS.md规则才会被加载有些项目习惯把规则文件保存在docs/或.agents/目录里这类自定义路径未必会被默认读取。我自己一般有两种做法要么把AGENTS.md直接放在对应目录下要么在主文件里通过引用方式把docs里的内容引进来避免依赖不标准的读取行为。如果某个子目录的规则始终加载不进去先确认是不是目录层级太深或者文件名被拼成了AGENTS.MD。2.2 AGENTS.md 与 CLAUDE.md 同时存在时听谁的这是问得最多的一个问题项目里已经有CLAUDE.md现在又多了AGENTS.md两个文件同时生效时到底谁说了算从官方更新说明的行为来看Claude Code并不是把两者做成“二选一”而是都会读取并合并到上下文里。CLAUDE.md作为Claude Code一直以来的产品级规则文件地位并没有被废除AGENTS.md则承担起跨工具共享的部分。合并后如果出现冲突不会有绝对的“谁压谁”的结论具体行为跟规则内容的表述方式、会话加载的顺序都有关系。所以我不建议去摸索谁优先级更高这种偏门玩法它既不可控也没必要。我的处理原则很简单不让它们有冲突的机会。把“所有工具都该知道的事情”放进AGENTS.md把“只有Claude Code需要知道的特殊偏好”留在CLAUDE.md。比如项目通用命令、技术栈、目录结构这些放AGENTS.md而“优先使用Claude Code内置的Agent Skills”“不要主动调用某个测试工具”这类跟特定工具绑定的内容留在CLAUDE.md。这样两个文件各管一摊合并时也不会打架。本质上就是把AGENTS.md当成团队公共区CLAUDE.md当成个人偏好区边界清晰了优先级问题自然就消失了。2.3 内容规划什么该写什么千万别写AGENTS.md写得好不好直接影响Agent的工作质量。我总结了一个简单的分法写“长期不变的项目事实”不写“短期任务和临时状态”。该写的内容就四类项目身份一句话说清项目是什么、服务谁、有什么核心模块技术栈与目录地图包括框架、语言版本、包管理器以及关键目录的作用Agent刚进仓库时最需要这张地图常用命令安装、构建、测试、Lint、格式化每一条都给出可执行的完整命令不要只写一句“跑测试”编码与行为规范命名风格、禁止模式、提交信息规范、review要求写得越具体越好“禁止使用any”比“注意代码质量”有用十倍。千万别写的内容也有几类。第一是临时任务比如“接下来我们要实现登录功能”这类应该放在对话上下文里而不是项目说明书第二是敏感信息像密钥、内网地址、带人名的工作安排写进AGENTS.md等于把秘密暴露给每一个读取它的Agent第三是特别长的日志和代码片段真的需要示例时放一小段有代表性的就够了塞大量代码会稀释Agent对重点规则的注意力还白白占用上下文窗口。我会把项目的历史背景、技术选型讨论这类叙事内容放到独立文档里只把可执行的结论留在AGENTS.md。3. 迁移实操把两份说明书合并成一份3.1 动手之前先盘点仓库里的说明书迁移最忌讳直接凭印象改。我建议开工前先花十分钟把仓库里跟“Agent说明书”相关的文件全部列出来。常见的包括CLAUDE.md、CLAUDE.local.md、AGENTS.md、.cursor/rules、CLINE.md、CONTEXT.md以及散落在docs里但实际起规则作用的指南文件。列的时候顺便做两件事一是标出每份文件的最后更新时间太久没动的基本是僵尸规则直接考虑废弃二是提炼每份文件里最核心的约束记到一张草稿里。我习惯用表格梳理四列就够文件路径、作用范围、核心内容、是否继续保留。比如文件路径作用范围核心内容处理动作CLAUDE.md全仓库技术栈、测试命令、编码规范迁入AGENTS.md后精简.cursor/rules/01-frontend.mdcsrc/frontend前端组件规范合并到前端子目录AGENTS.mddocs/project-guide.md全仓库历史决策、架构说明保留原文AGENTS.md引用链接一开始动作别太大。先挑一个单模块的小仓库试点把这个仓库的规则摸清、写顺再推广到复杂仓库。如果在monorepo上直接动手规则冲突会把你淹没在排查里迁移体验会很差还容易让团队对AGENTS.md产生抵触心理。3.2 一份可以直接套用的 AGENTS.md 模板下面这份模板是我在几个真实项目里迭代过的版本你可以直接复制后按自己项目改。原则是先用短句子说清楚事实再用命令和禁区约束行为。# AGENTS.md ## 项目概览 - 项目名order-service - 一句话说明订单履约核心服务负责下单、支付回调、库存扣减。 - 语言与框架Java 17 Spring Boot 3.x构建工具 Maven。 - 基础设施MySQL 8Redis 7消息队列 RocketMQ。 ## 目录地图 - src/main/java/com/company/order业务代码 - controllerHTTP 接口层只做参数转换不写业务 - service业务逻辑层核心交易流程都在这里 - repository数据访问层所有数据库操作必须走这里 - src/test/java单元测试新增业务逻辑必须配套测试 ## 常用命令 - 启动本地服务mvn spring-boot:run - 跑全部测试mvn test - 只跑某个模块测试mvn test -pl order-service - 代码检查mvn checkstyle:check ## 编码规范 - 所有接口入参必须使用 DTO禁止直接用 Map 接收参数。 - 金额计算使用 BigDecimal禁止使用 double。 - 异常不允许吞掉要么向上抛要么记录日志后做补偿。 - 提交信息使用 conventional commits 格式feat/fix/refactor...。 ## 禁区 - 不要修改 flyway 已发布的迁移文件新变更一律新建版本号。 - 不要在 controller 里直接调用 repository。 - 不要通过 Redis 存订单主数据Redis 只做缓存与限流。这份模板的关键在于每条规则都是Agent可以“直接执行”的而不是需要它自己发挥的模糊描述。你把“所有接口入参必须使用DTO”这句话给Agent它写代码时就会反射性地想“这次是不是又漏了DTO”比“注意接口设计质量”有效太多。目录地图也别画得像文档一样复杂最简单的方式就是把物理路径列出配上一句话职责说明。3.3 验证加载与平滑切换策略写完AGENTS.md后别急着删CLAUDE.md。先在项目根目录启动一个Claude Code会话用/memory命令看看当前加载了哪些记忆文件或者直接问它一句“你读到了这个项目的哪些规则”它会把读到的内容复述出来你对照检查AGENTS.md里的核心条目是否都在。这一步一定要做不要默认工具一定会读到所有内容文件路径、大小写、目录层级都会影响加载结果。我推荐的切换节奏是这样的第一周让AGENTS.md和CLAUDE.md内容保持一致两边都放相同的核心规则日常开发继续用Claude Code观察有没有异常确认稳定后把CLAUDE.md精简成一句“项目规则见根目录AGENTS.md”或者干脆只保留Claude Code特有的配置再运行一两周如果团队里没有谁依赖旧文件报错就可以把冗余的版本清掉了。如果是团队协作项目记得把这次变动写进README或PR描述里避免同事误以为AGENTS.md是新来的无关文件。切换期间如果发现Agent行为异常第一步永远是检查两份文件里有没有互相矛盾的指令而不是去调提示词。4. 多 Agent 协作场景下的配置与排障4.1 同一套规则喂饱多个 Agent 的编排思路既然AGENTS.md的定位是跨工具通用说明书那多Agent并存时最大的收益就是“一份规则到处生效”。我现在的典型配置是根目录AGENTS.md管全局子目录AGENTS.md管局部然后让Cursor、Cline、Windsurf这些工具直接读取同一份文件对实在不识别AGENTS.md的老旧工具就在工具自己的规则入口里写一句“先看根目录AGENTS.md”把该工具的规则文件变成薄薄一层的转发页。这里要特别提醒一句不同工具对AGENTS.md的读取策略并不完全一致有的工具会全部加载有的只加载根目录有的还有自己的优先级规则。所以上线前一定要在每个工具里都验证一次方法是在对应工具开一个新会话问它读到了什么。我自己就遇到过某个工具在特定模式下不读子目录AGENTS.md的情况如果没提前验证局部规则就悄悄失效了等代码风格跑偏才发现返工成本很高。另外规则文件的更新也要纳入团队协作流程。我见过最典型的翻车现场是一个人更新了AGENTS.md里的构建命令但没提交到仓库其他同事拉代码时根本看不到改动Agent自然还在用旧命令。把AGENTS.md当成跟代码同等重要的产物随代码一起走review而不是“有时间再改改”的附属品。4.2 高频问题排查速查表这几个月我收集了不少实际踩坑经验整理成下面这张速查表遇到问题可以按图索骥现象可能原因解决办法Agent完全没提到AGENTS.md内容文件名大小写不对、文件被.gitignore排除、当前工作目录层级太深确认文件名是AGENTS.md重开会话在项目根目录或目标子目录验证子目录AGENTS.md没生效工具只在会话入口目录读取根级文件把子目录关键规则提到根目录AGENTS.md或用引用方式拆到统一目录规则互相矛盾Agent行为不稳定CLAUDE.md和AGENTS.md对同一件事写了不同要求明确单一事实来源另一个文件只保留工具特有配置上下文被撑爆回复变慢AGENTS.md塞了大量代码示例和日志删减到必要信息详细参考迁移到独立文档用链接代替内联多人协作时规则被悄悄改坏没有把AGENTS.md纳入评审流程把AGENTS.md放进PR常规review范围重要变更走双人确认某个工具仍然读不到该工具版本过旧或不支持AGENTS.md标准升级工具版本不行则保留一份适配版的转发规则文件排查这类问题有个通用技巧把问题从“工具为什么不听话”变成“工具到底读到了什么”。只要是规则加载类问题让Agent复述上下文比猜原因高效得多。我之前花了半小时调一个“规则没生效”的问题最后发现是会话里带上了历史记忆新规则被旧指令覆盖了新开会话后一切正常。4.3 几条来自一线的实操心得最后分享几个比较主观但很实用的心得。第一AGENTS.md不是越详细越好。我把一份写了三百多行的规则文件删到八十行后Agent在代码生成和命令选择上的表现反而更稳定了。信息太多时Agent会抓不住重点甚至把某条历史约束误当成当前必须遵守的硬规则。写规则时可以用一个判断标准如果这句话删掉之后Agent的行为不会变差那就删掉它。第二写规则时多用“要做什么”的命令式少用“不应该”的文件风格描述。直接给正面的正确做法比列一堆禁止项更有效。比如与其写“不要在controller里写SQL”不如写“controller只做参数转换所有数据访问走repository层”Agent理解后者更准确执行时也不会因为语义模糊而自由发挥。第三AGENTS.md也要做维护别写一次就当传家宝。依赖升级、目录调整、命令变化时顺手更新一下。我的做法是每次重构涉及目录或命令变动时把更新AGENTS.md记进同一张任务清单避免项目结构变了但Agent还拿着旧地图。说白了AGENTS.md就是给Agent看的新员工入职手册入职手册都不维护新员工自然会乱。目前我的主力项目已经全部收敛到“AGENTS.md为主、CLAUDE.md只做薄转发”的方案跑了大半个月最明显的变化是所有Agent工具第一次“看到”的项目背景完全一致了跨工具迁移或并行干活时不用再反复对齐说法。如果你也正被多份说明书困扰我的建议是别急着删先把AGENTS.md写好并逐个工具验证加载再平滑切换。最后想提醒一句AGENTS.md只是让Agent更懂你的项目它不会挽救混乱的代码结构真正决定产出质量的还是你写在文件里的那几行规则本身的质量。