Claude Code九月更新：AGENTS.md、长任务续接与插件管理详解-育师

1. “认了”AGENTS.md：项目级指令的开放标准时代

如果你跟我一样，从上半年就开始把 Claude Code 当主力编码工具用，那你对CLAUDE.md一定不陌生。它是 Claude Code 用来读取项目说明、理解仓库上下文、约束代码风格的主配置文件。过去小半年里，CLAUDE.md 几乎是每个正经接入 Claude Code 的团队的“标配”：你要让 Claude 改代码时不开倒车、不碰雷区，所有规则都得写进这文件里。

但有一个尴尬，一直卡在那里：Claude Code 认 CLAUDE.md，Cursor 认 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.md，Claude 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 越来越像一个可以稳定依赖的工程工具，而不是一个“每天都要关注它有没有跑偏”的实验品。

建议分角色来应对这次更新：