1. “认了”AGENTS.md项目级指令的开放标准时代如果你跟我一样从上半年就开始把 Claude Code 当主力编码工具用那你对CLAUDE.md一定不陌生。它是 Claude Code 用来读取项目说明、理解仓库上下文、约束代码风格的主配置文件。过去小半年里CLAUDE.md 几乎是每个正经接入 Claude Code 的团队的“标配”你要让 Claude 改代码时不开倒车、不碰雷区所有规则都得写进这文件里。但有一个尴尬一直卡在那里Claude Code 认 CLAUDE.mdCursor 认 AGENTS.md别的 Agent 工具又认别的文件。我刚从 Cursor 迁到 Claude Code 那阵仓库里同时挂着CLAUDE.md和AGENTS.md一份项目规范拆成两份维护改一版要同步两处。这种“工具私有的项目指令”设计在小团队里还能忍放到稍微大一点的协作场景里就是灾难。所以九月这次更新Claude Code 宣布正式支持 AGENTS.md我第一时间就把两份文件合并了。1.1 为什么说“认了”是个分水岭先把这事的本质说透。AGENTS.md 不是 Anthropic 发明的它是从社区里长出来的一个跨工具约定意思是“给 AI Agent 看的项目说明”。Cursor、Codex、OpenAI 那边都陆续在往这个标准上靠。Claude Code 之前只认CLAUDE.md本质上是一种异步——它能理解项目上下文但这个上下文文件的格式只有自己用。这次更新之后Claude Code 在读取项目指令时会按优先级依次处理AGENTS.md和CLAUDE.md同时存在时哪个生效、哪个作为补充官方有一个明确的读取顺序。我把两套规则合并成一套 AGENTS.md 之后实测下来Claude Code 对仓库的“理解基线”基本没变化但我的维护成本直接少了一半——同一个规范文件Cursor 拿去能用Claude Code 拿去也能用其他工具也认。这个动作背后其实是生态位的判断AI 编程工具正在从“各立山头”走向“共享项目语境”。对做仓库基建、做团队 AI 规范的人来说这是一个值得跟进的信号。1.2 AGENTS.md 到底怎么用优先级和灰度细节我知道很多人还停在“听说过 AGENTS.md但不知道该怎么落”的状态。这很正常因为这个文件跟 CLAUDE.md 长得像但使用细节有差异。先说最基本的写法# Project Guide ## 项目概述 - 这是一个基于 FastAPI 的支付网关服务对外提供 REST API - 调用链路client - gateway - payment provider - callback ## 代码规范 - Python 版本 3.11所有新代码必须带类型注解 - 异步函数统一用 asyncio禁止使用 gevent - 数据库迁移必须走 alembic不允许直接改库结构 ## 注意事项 - 修改 payment/callback 相关代码时必须保留幂等逻辑 - 所有金额操作统一用 Decimal禁止用 float - 涉及第三方接口重试的统一走 retry_queue不直接写重试循环这块跟 CLAUDE.md 的写法基本一致。但需要注意几个和以前不一样的灰度细节第一AGENTS.md 支持嵌套读取。子目录里放一个AGENTS.mdClaude Code 在涉及那个目录下的文件时会把根目录的和当前目录的叠加起来一起作为上下文。我在一个 monorepo 里验证过这个行为根目录的 AGENTS.md 描述全局规范services/order/AGENTS.md描述订单模块的特殊规则当 Claude 修改services/order/下的代码时两份都会被读到。这个能力比原来的 CLAUDE.md 单一文件方案强不少以前要实现类似效果得在 CLAUDE.md 里写一堆“如果涉及 xxx 目录”的位面文案维护起来非常痛苦。第二AGENTS.md 和 CLAUDE.md 共存时的优先级。测试下来官方实测的规则是如果同一目录下同时存在两者项目级指令以 AGENTS.md 为准CLAUDE.md 里和它冲突的内容会被忽略。如果你现在仓库里还有一套完整的 CLAUDE.md不用慌可以把它降级成“补充说明”把核心规则迁到 AGENTS.md 里。迁移时我建议这样处理把 CLAUDE.md 里的“必须/禁止”类强约束全部搬到 AGENTS.md把工具链相关的使用说明比如“调试时用这种命令”“构建时执行那个脚本”留在 CLAUDE.md 或 README跑一轮回归让 Claude 改一个你已经知道正确答案的小功能确认它行为没跑偏第三文件的忽略与生效范围。AGENTS.md 不是所有改动都会触发重新读取的——Claude Code 会对项目文件做哈希追踪只有涉及相关路径的任务才会触发对应 AGENTS.md 的加载。这意味着长会话里修改了 AGENTS.md当前会话可能不会立刻生效。我实测下来最稳妥的做法是改完 AGENTS.md 之后重启一个新会话别在旧会话里继续验证。1.3 为什么要迁移一份规范文件打天下的红利我见过太多团队把项目规范散落在 README、Confluence、企业 wiki 三处Claude Code 能读到的只是其中一部分结果就是 AI 经常产出风格跳脱、常识缺失的代码。有了 AGENTS.md 这个统一载体之后规范文件可以做到“人机同源”人看README、文档站AI 看AGENTS.md / CLAUDE.md一旦 Claude Code 认了 AGENTS.md意味着你仓库里的 AI 指令文件可以同时喂给不同工具。这带来的实际收益不是“少维护一个文件”那么简单而是团队的 AI 协作规范终于有了一个不绑定厂商的落点。如果你现在还在用 CLAUDE.md我的建议是给仓库建一个 AGENTS.md把真正的约束规则迁进去CLAUDE.md 只保留工具特定的杂项。这样即便将来团队换工具项目级的 AI 行为规范也不会推倒重来。2. 长任务暂停接上中断恐惧症的终结Claude Code 这个工具功能上限很高但过去有个非常让人恼火的体验跑长任务时中途一旦断了基本等于前功尽弃。我说的“断”不一定是报错。可能是你临时要切去修个线上 bug可能是某个工具调用的交互卡住了也可能是笔记本合盖、网络闪断。总之那个 40 分钟前启动的“全仓库重构”任务上下文已经走完一半结果中断回来它要么告诉你“继续”实际却从某个模棱两可的状态开始瞎猜要么干脆上下文丢失只能重新跑。九月这版更新官方把“暂停续接”做成了正经能力。先说结论这次不是简单的“恢复了之前的对话记录”而是把任务的执行状态真正保存了下来恢复之后是“接着干”不是“重新干”。2.1 之前的断点续跑为什么那么虚要理解这次更新的价值得先知道之前的问题出在哪。Claude Code 以前也支持“恢复会话”——它在本地保存对话历史你重新打开会话时能输/resume找回之前的记录。但问题是对话记录和“任务执行状态”是两码事。举个例子。我让 Claude 做“全仓库代码格式化 测试修复”这个任务正常它要分十几步执行先扫描文件再批量改代码再逐个跑测试遇到报错还要自我修复。这一步一步的执行过程是由 Claude 的上下文驱动的——它必须记得“我改到第几个文件了”“上一个测试为什么挂了”“接下来按什么顺序推进”。以前的“恢复会话”只是恢复了聊天文本Claude 重新加载之后理论上还能从文本里“回忆”自己干到哪但一旦任务中途产生了大量文件改动而文本记录又比较粗恢复后的它经常出现“不清楚到底哪些文件已经改过”的状态轻则重复修改重则误判进度。2.2 新机制保存的是什么状态这次更新之后Claude Code 在暂停任务时会把三类状态一起保存下来上下文状态当前任务的对话上下文但不只是文本还包括“当前做了什么决策”“下一步计划是什么”工作区状态暂停那一刻的已改动文件清单、新建文件、还有待执行的步骤队列子任务执行状态如果任务拆成了多个子任务比如先重构 A 模块再修 B 模块恢复后能精确到“A 已完成B 进行到一半”这个粒度我实测的一个场景是让 Claude 跑一个 50 文件的 TypeScript 类型标注补全任务跑到第 21 个文件的时候我手动暂停接着去开了一个小时会。回来恢复之后它直接从第 22 个文件接着干没有重新扫描、没有问“是否继续”连前面改过的文件都是已标记状态。这个体验的差异类似“浏览器崩溃后恢复标签页”和“浏览器让你重新打开所有链接”的区别。前者是恢复后者是重来。2.3 哪些任务适合用暂停续接哪些不建议我用了一段时间之后总结了一个判断标准任务里是否有“外部状态依赖”。适合暂停的任务批量代码生成、补全、规范化纯靠上下文驱动多文件重构且改动逻辑可以独立分块长测试修复Claude 需要逐文件定位、改码、复测文档整理、依赖分析、架构梳理不太建议依赖暂停的任务涉及交互式进程的比如跑起了一个 dev server指望暂停后还能原样接上中间步骤要求人工做决策的暂停恢复不会帮你做决策只负责保存现场依赖外部服务的比如要调线上数据库、要跑 CI一句话这个功能是“任务现场保留”不是“虚拟化回滚”。它对纯代码状态的保存很好但对运行环境的持久化基本不负责。2.4 实测中的三个注意点第一模块规模越大恢复精度相对越低。我做过对比20 个文件以内的任务恢复后几乎无损上百个文件的大任务恢复后偶尔会出现“它以为某个子任务完成了但实际上文件还没保存”的情况。所以大任务我还是建议拆成几个中等规模的批次别全塞一次。第二暂停前最好留一个“可验证的中间态”。我在跑重构时习惯让 Claude 每完成一个模块就 git commit 一次暂停前也会确保工作区是有意义的、能编译的状态。这样恢复后就算状态有偏差也能基于一个干净基座去处理而不是从一团乱麻里猜进度。第三恢复后第一件事让它“汇报当前完成度和下一步计划”不要在恢复后直接说“继续”。我实测下来让 Claude 先概括一遍它理解的当前状态可以有效避免它带着错误进度认知往下跑。这多花 20 秒能省后面大量返工。这个功能上线后我最大的改变是敢给 Claude 派大活了。以前超过 20 分钟的任务我都习惯性拆碎现在完全可以一条指令推完中途要开会就暂停回来接着跑。这对我来说比那些花哨的新模型能力实在得多。3. 插件从“能装”到“能管”生态位的一次关键升级如果你观察够久会发现 Claude Code 的插件体系经历了三个阶段。最早是“基本没有”后来社区做了一堆外围脚本靠配置文件硬塞进去“能装但是糙”九月这次更新之后插件不再只是“装上能用”而是进入了可管理、可配置、可控制的状态。这次更新里插件管理相关的改动表面看是“多了个列表界面”和“几个管理命令”但往深了看它解决的是所有工具生态都会遇到的那个坎安装的数量多了以后插件之间怎么协调、怎么排查冲突、怎么按项目启停。3.1 “能装”时代的痛点装上容易管起来想骂人我算是“能装”时代比较早的一批用户。当时第三方插件基本是社区脚本安装路径不统一有的需要手动 clone 仓库有的是一段脚本往settings.json里塞配置有的还要偷偷改.claude目录。那个阶段最痛苦的不是“装不上”而是“装多了之后你根本不知道当前会话里到底生效了哪些插件”。比如你装了一个自动补全工具、一个 git 提交流程增强、还有一个 MCP 服务器管理插件三个都改了全局配置一旦某个工具行为异常你根本分不清是哪个插件在搞鬼只能逐个禁用再猜。更头大的还有版本管理。社区插件的更新方式多种多样有 git pull 的、有重新下载的、有靠命名的。你根本不知道自己装的是哪个版本跟 Claude Code 版本之间是否兼容。基本上属于“能用就算赢别问为什么能用”。3.2 “能管”之后启停、配置、目录都稳了这次更新之后插件在 Claude Code 里有了规范化的管理入口。我在实际使用中有这几个直观变化第一插件有了统一的查看和启停入口。我可以在会话里直接查询当前加载了哪些插件、它们的启用状态、来源路径。需要临时禁用某个插件时不用再去改文件一个命令切掉就行。这对排障来说意义重大——以前是“不信邪地挨个试”现在是“逐个启停观察行为”。第二插件配置有了标准的目录结构和字段约定。每个插件可以在项目级的配置里声明自己的参数不会再把全局配置搞得一团乱。这意味着换项目时插件配置可以跟着项目走而不是跟个人电脑走。我目前实际用的目录结构是这样的.claude/ ├── settings.json # 全局/项目级配置 ├── plugins/ # 插件目录 │ ├── code-review/ # 代码评审插件 │ ├── git-helper/ # git 流程增强 │ └── mcp-manager/ # MCP 服务管理每个插件目录下有独立的README.md或配置文件记录这个插件是干什么的、需要什么权限、配置了哪些参数。这套结构对于一个长期维护的项目来说很重要——settings.json里不会再堆一坨只有自己能看懂的插件路径。第三控制粒度更细了。之前插件启用后就是对所有任务生效的“全量模式”现在可以按项目配置甚至按任务类型决定插件是否参与。比如“代码评审”这个插件我在重构类的任务里会禁用掉避免它在我还没改完的时候就开始输出一堆无关评审意见干扰主线。3.3 插件管理对团队和个人的实际意义说到这肯定有人觉得“这不就是加了几个管理命令吗有什么了不起”。但如果你在一个团队里维护过 AI 编码工具的准入清单就会明白这步升级的分量。插件管理能力成熟之前团队里各人装各人的插件同一个项目在不同开发者的机器上可能行为完全不一致。你这边代码评审插件默认开同事那边没装你这边配了 git 提交流程自动检查同事那边提交流程跟裸奔一样。代码规范靠 AGENTS.md 可以约束插件行为的一致性没有抓手。“能管”之后团队可以这样落地在项目配置里固定一组推荐插件写明每个插件的用途新成员 clone 项目后按配置文件一键加载插件不需要手动四处找权限和对系统的影响集中在配置文件里code review 时能注意到个人开发者也能从中受益——至少不会出现“换台电脑工具链全废”的情况。以前我换开发机要把插件目录重新 clone 一遍配置文件还要手动检查对齐现在配置里写清楚来源一条命令就能把插件环境拉起。3.4 “能装”到“能管”下一步会是“能审”插件管理的规范化还有很多可以继续深挖的方向。我比较期待的是“插件声明式依赖”和“插件审计”比如插件声明自己需要访问哪些目录、读取哪些文件、要不要执行外部命令。这样安装之前就能知道自己装的东西有多大权限而不是装完之后才发现它要改全局配置。当然这次从“能装”到“能管”的升级给插件生态打了一个不错的基础。对普通用户来说最直接的感受就是装插件不再是一件“野路子”操作而是一件可以放心交付给团队里任何一个人去做的事。4. 从老版本迁移我实测的升级清单和三个坑如果你已经在用 Claude Code想升级到九月这版别直接更新完就开始干活。我这次升级前后折腾了小半天有些地方是文档里没说透、但实际一定会遇到的。4.1 迁移前建议备份的几样东西升级第一步不是跑更新命令而是先备份。需要备份的有.claude/整个目录这里有你的全局设置、项目设置、插件启用配置CLAUDE.md以及已有的AGENTS.md升级过程不会删你的文件但你有迁移动作保底备份没坏处settings.json如果你手动维护过一堆自定义项升级前一定要留个副本备份完了之后再执行升级。升级命令本身没什么可说但升级完成后有两个检查动作很关键确认当前版本号以及插件管理相关的命令是否生效跑一个简单的“冒烟测试”——让 Claude 读一下项目说明文件改一个无关紧要的小文件确认 AGENTS.md 被正确加载这一步冒烟测试能提前暴露 80% 的配置兼容问题比你直接扔一个大数据迁移任务过去靠谱得多。4.2 坑一AGENTS.md 和旧 CLAUDE.md 冲突导致指令重复执行升级完第一天我发现 Claude 的行为有异常同一个规则它像执行了两遍。比如 AGENTS.md 里写了“所有新代码必须加类型注解”CLAUDE.md 里也有一句类似的结果就是 Claude 在面对函数时反复确认“是否满足类型注解要求”拖慢速度而且偶发多余动作。这个问题的根源很简单就是两套文件并存导致指令冗余。解决方式也很直接迁移时别只把 CLAUDE.md 复制成 AGENTS.md 就完事而是主动做个去重和合并。我最后把 CLAUDE.md 精简成“工具加载方式说明”这一小段其余规范全部统一到 AGENTS.md再跑就顺了。建议的做法把 CLAUDE.md 的强约束部分提炼后写入 AGENTS.md对比两边内容删掉重复项跑一次“指令读取验证”观察 Claude 执行时是否还会复述已有规则4.3 坑二长任务暂停后环境变量和未保存配置恢复不如预期长任务暂停续接这个功能很爽但别指望它能恢复一切。我遇到的情况是一个任务里我让 Claude 读取了一个临时环境变量任务暂停恢复之后这个环境变量的上下文丢失了它却以为自己还记得——结果后续操作里用它推理给出的结果明显偏了。这不是 bug而是“任务状态”和“运行环境状态”的边界问题。环境变量、临时文件、系统状态这些不在任务现场保存范围内。所以我现在的习惯是进入长任务之前把所有要用到的配置、参数、前提条件让 Claude 先写到一个明文的上下文清单里比如放AGENTS.md或者会话开头的指令文件这样即使现场状态丢失它也有依据可以重新校准。4.4 坑三老插件的兼容性不是所有都能无缝进“可管理”体系升级之后我原来手动安装的几个社区插件有一个在新版的管理命令下根本识别不到。原因倒不复杂——新版插件管理侧重点是“统一配置文件 标准目录”我这个老插件是直接塞进全局配置的结构不符合新的加载预期。处理方式分两步先看插件有没有对应的新版本或官方迁移说明没有的话按新目录结构手动迁移在.claude/plugins/下建目录把插件的加载说明写进配置这一步说起来轻巧实际操作时要多留个心眼插件迁移后先启用它跑两个使用该插件功能的任务验证再正式并入常规使用。别一次性迁所有插件迁一个验证一个。4.5 给团队协作场景的额外提醒如果你所在团队把 Claude Code 作为共享工具这次升级还有个值得留意的点AGENTS.md 和插件配置都属于“随仓库走”的文件建议纳入 code review 流程。也就是说修改 AGENTS.md 或插件配置应该跟改代码一样走 MR而不是某个人在自己本地改了就算完事。我见过不少团队AGENTS.md 更新全凭个人自觉改完也不通知别人结果就是仓库里的规范文件和团队的“实际就业规则”逐渐脱节。把它纳入 review 流程之后至少能保证每次规则变更都有记录、有讨论。另外如果团队里有多个分支长期并行注意 AGENTS.md 的合并策略。它本质上是文本文件git 合并时可能会遇到冲突。处理思路跟代码冲突一样以“最近更新的规则优先”为准拿不准的先找当事人确认不要自己拍板删掉某一方的规则。5. 九月这波更新我的整体评价和使用建议聊完三个具体功能最后说点整体的感受。Claude Code 这半年一直在快速迭代但九月这波更新的风格和之前不太一样。之前几次更新更多是能力上的加法比如多模态输入、更长的上下文、更强的工具调用。这次的重点其实是围绕“工程化可用性”做文章AGENTS.md 是让项目规范有标准落点长任务暂停续接是让长流程执行更可靠插件管理是让生态从“社区自留地”走向“正式基础设施”。对我个人来说最大的心态变化是Claude Code 越来越像一个可以稳定依赖的工程工具而不是一个“每天都要关注它有没有跑偏”的实验品。建议分角色来应对这次更新如果你只是个人用户先把 AGENTS.md 用起来替换掉你零散的 CLAUDE.md长任务暂停功能会在某次你临时要打断任务的时候救你一命。如果你是团队里负责 AI 工具落地的人重点放在插件管理上。趁着这次升级把插件目录、配置、启停规则一次性梳理干净后面维护成本会显著下降。如果你对生态趋势比较敏感建议持续关注 AGENTS.md 的跨工具兼容。它很可能成为未来半年各个 AI 编程工具之间互操作的最大公约数。最后提醒一句以上这些实测结论是我在九月这个版本上验证的具体到你手上的版本命令名称、配置字段可能有细微差别。动手前先瞄一眼官方更新日志能少踩很多坑。