1. 这次九月更新到底改了什么：从“能用”到“好用”的分水岭

九月份这波 Claude Code 的更新，我第一时间在自己的主力机上跑了一遍，最大的感受就是：它终于开始像一个“正经的工程工具”了，而不是一个只会聊天的命令行玩具。这次更新主要围绕三件事展开——AGENTS.md 的正式认领、长任务的暂停与续接、插件从“能装”进化到“能管”。如果你之前一直在用 CLAUDE.md 做项目上下文管理，那这次你得重新理解一下配置文件的分工了；如果你之前被长任务跑到一半断掉、上下文丢失的问题折磨过，那这次的暂停续接机制会让你舒服很多；如果你装了一堆插件但根本不知道谁在干活、谁在拖后腿，那新的插件管理能力就是为你准备的。

我先把结论放在前面：这次更新不是那种“加了个花哨功能”的小版本，而是把 Claude Code 从一个“单次对话式编码助手”往“可持续工程项目协作工具”方向推了一大步。适合谁来参考？三类人最值得看——第一类是把 Claude Code 当日常主力编码工具的开发者，第二类是在团队里推动 AI 辅助编码规范落地的技术负责人，第三类是之前因为长任务不稳定、插件管理混乱而放弃使用的人。接下来我会把每个更新点拆开，讲清楚它背后的设计逻辑、实际操作中怎么用、以及我踩过的那些坑。

2. AGENTS.md 被正式认领：配置文件的分工终于清晰了

2.1 为什么之前 CLAUDE.md 一家独大反而不好用

在九月更新之前，Claude Code 的项目上下文基本靠一个CLAUDE.md文件撑着。你可以在里面写项目结构说明、编码规范、常用命令、注意事项，Claude Code 启动时会自动读取这个文件，把它作为系统提示的一部分。这个机制本身没问题，但用久了就会发现一个尴尬的地方：CLAUDE.md 变成了一个“什么都往里塞”的杂物间。我见过不少项目里的 CLAUDE.md 写到几百行，既有“这个项目用 pnpm 不用 npm”这种工具约定，又有“用户模块的鉴权逻辑在 src/auth 下面”这种架构说明，还有“不要动 legacy 目录”这种禁忌事项。结果就是，每次 Claude Code 加载这个文件，都要吞下一大堆跟当前任务无关的信息，既浪费上下文窗口，又容易让模型抓错重点。

更麻烦的是团队协作场景。CLAUDE.md 通常是跟着项目仓库走的，但不同的人对“什么该写进去”理解不一样。有人把它当个人笔记，有人把它当团队规范，最后这个文件就变成了一个谁都不敢删、谁也不想维护的“祖传配置”。我之前在一个中型项目里就遇到过这种情况：CLAUDE.md 里有一半内容是某个已经离职的同事写的临时调试备注，但没人敢清理，因为怕删了之后 Claude Code 的行为会变。

2.2 AGENTS.md 的定位：给“代理行为”单独开一份说明书

九月更新之后，Claude Code 正式认领了AGENTS.md这个文件。注意，是“认领”而不是“替代”。CLAUDE.md 依然有效，但 AGENTS.md 的出现让配置有了更清晰的分层。我的理解是这样的：CLAUDE.md 管的是“这个项目是什么”，AGENTS.md 管的是“你作为代理应该怎么做”。前者偏向静态的项目知识，后者偏向动态的行为约束。

具体来说，AGENTS.md 里适合放这些东西：代理在执行任务时的操作规范，比如“修改文件前必须先读一遍再改”“执行破坏性命令前要二次确认”“提交代码前要跑一遍 lint”；还有代理的权限边界，比如“不要自动安装依赖”“不要修改 CI 配置”；以及一些流程性的约定，比如“遇到不确定的架构问题先问我，不要自己猜”。这些内容的特点是，它们不是项目本身的知识，而是对代理行为的约束，放在 AGENTS.md 里比塞进 CLAUDE.md 更合适。

我实测下来的感受是，把行为约束从 CLAUDE.md 拆到 AGENTS.md 之后，Claude Code 在执行任务时的“听话程度”明显提升了。原因也不难理解：当行为规范单独成文、结构清晰时，模型更容易把它当作硬性规则来遵守，而不是淹没在一堆项目描述里被忽略。

2.3 两个文件怎么配合：我的实际配置方案

我现在的主力项目里，两个文件是这么分工的。CLAUDE.md 保持在 50 行以内，只写最核心的项目信息：技术栈、目录结构概览、常用命令、以及三到五条最重要的编码约定。AGENTS.md 则根据任务类型分了几块：通用行为规范、代码修改流程、测试与验证要求、以及禁止事项清单。

这里有个实操细节值得注意：AGENTS.md 的加载优先级和 CLAUDE.md 是并列的，不是覆盖关系。也就是说，如果两个文件里有冲突的指令，模型会同时看到，然后自己判断。这就意味着你不能在 CLAUDE.md 里写“提交前不用跑测试”，又在 AGENTS.md 里写“提交前必须跑测试”，否则模型会陷入精神分裂。我的做法是，凡是涉及“代理该怎么做”的内容，一律只写在 AGENTS.md 里，CLAUDE.md 里不重复。

还有一个坑我踩过：AGENTS.md 的文件名是大小写敏感的。我一开始写成了agents.md，结果 Claude Code 根本没识别。后来改成全大写AGENTS.md才生效。这个细节官方文档里提了一句，但很容易被忽略。另外，如果你在子目录里也放了 AGENTS.md，Claude Code 会按照目录层级逐层加载，子目录的配置会叠加在根目录配置之上。这个机制适合做 monorepo 场景下的精细化控制，比如前端目录和后端目录可以有不同的代理行为规范。

2.4 从 CLAUDE.md 迁移到 AGENTS.md 的实操步骤

如果你手头已经有一个写得很满的 CLAUDE.md，想迁移到新的分工模式，我建议按这个顺序来。第一步，先把 CLAUDE.md 通读一遍，把里面的内容分成三类：项目知识、行为规范、临时备注。第二步，项目知识留在 CLAUDE.md，行为规范挪到新建的 AGENTS.md，临时备注直接删掉或者挪到单独的 TODO 文件里。第三步，把 AGENTS.md 的内容按“通用规范”“修改流程”“禁止事项”三个小节组织，每节用简洁的列表表达，不要写成大段散文。第四步，在两个文件开头各加一行注释，说明这个文件的职责范围，方便后续维护的人理解。

迁移完之后，我建议跑一个简单的验证：让 Claude Code 执行一个需要遵守行为规范的任务，比如“帮我改一下某个函数的返回值类型”，然后观察它有没有按照 AGENTS.md 里的要求先读文件再改、改完有没有跑测试。如果它跳过了这些步骤，说明你的 AGENTS.md 写得不够明确，或者指令之间有冲突，需要回去调整。

3. 长任务暂停与续接：终于不用一口气跑完了

3.1 长任务之前为什么容易“翻车”

在九月更新之前，Claude Code 处理长任务的方式基本是“一口气跑到底”。你给它一个复杂任务，比如“重构整个用户模块的错误处理逻辑”，它会从头到尾连续执行，中间你没法暂停，也没法在它跑到一半的时候插入新的指令。这个模式在短任务上没问题，但一旦任务链条变长，问题就来了。

首先是上下文窗口的压力。长任务意味着大量的文件读取、代码修改、命令执行，这些都会消耗上下文。跑到后面，模型可能已经“忘了”前面读过什么，开始重复劳动或者做出矛盾的修改。其次是错误累积。如果它在第三步做了一个错误的假设，后面所有步骤都会基于这个错误假设继续推进，等你发现的时候已经改了一大堆文件。最后是人的因素——你不可能一直盯着它跑，但你又不敢完全放手，因为不知道它跑到哪一步会出问题。

我之前处理一个跨十几个文件的重构任务时，就遇到过这种情况：Claude Code 跑到一半，我接了个电话回来，发现它已经把三个不相关的模块也“顺手”改了，理由是“保持一致性”。这就是长任务失控的典型表现。

3.2 暂停与续接机制的实际操作方式

九月更新之后，长任务支持暂停和续接了。具体操作上，你可以在任务执行过程中随时中断，Claude Code 会把当前的任务状态保存下来，包括已经完成了哪些步骤、当前正在处理哪个文件、以及下一步计划是什么。等你准备好之后，可以从断点继续，它会接着之前的状态往下跑，而不是从头再来。

我实测下来的操作流程是这样的：启动一个长任务后，如果你想暂停，直接按中断键，Claude Code 会输出一个状态摘要，告诉你它当前进行到哪了。这个摘要会保存在会话里。之后你可以选择继续，它会读取这个摘要，从断点恢复。如果你在暂停期间想调整方向，比如“刚才那个改法不对，换个思路”，也可以直接说，它会基于新的指令调整后续步骤，但已经完成的部分不会自动回滚——这点要注意，回滚还是得手动来。

这里有个使用技巧：暂停的时机最好选在一个“逻辑步骤”完成之后，而不是文件改到一半的时候。虽然 Claude Code 会尽量保存状态，但如果在一个文件的多处修改中间暂停，恢复时可能会出现部分修改已应用、部分未应用的情况，需要你手动检查。我的习惯是，在让它执行长任务之前，先让它把任务拆成明确的步骤列表，然后我在每个步骤之间决定是否暂停检查。

3.3 续接时的上下文管理：哪些信息会被保留

续接机制的核心是上下文保留。根据我的实测，Claude Code 在暂停时会保留这几类信息：任务的整体目标和当前进度、已经读取过的关键文件内容摘要、已经做出的修改记录、以及待办步骤列表。但有一些信息可能不会被完整保留，比如它之前执行过的命令的完整输出、以及一些中间推理过程的细节。

这就意味着，如果你暂停的时间很长，或者中间做了很多其他操作，恢复时它可能需要重新读取一些文件来补充上下文。这个重新读取的过程会消耗额外的时间和 token，但好处是能保证后续步骤基于最新的文件状态，而不是过时的缓存。

我遇到过一个情况：暂停之后我手动改了某个文件，然后恢复任务，Claude Code 重新读取了这个文件，发现内容跟它之前记录的不一样，于是主动问我“这个文件被修改过，是否要基于新版本继续”。这个行为我觉得挺聪明的，避免了它基于旧版本继续改导致冲突。

3.4 长任务拆分策略：什么时候该暂停，什么时候该一口气跑

虽然现在支持暂停续接了，但并不意味着所有任务都应该拆成碎片来跑。我的经验是，任务拆分要按“逻辑边界”来，而不是按“时间长短”来。一个逻辑边界通常是一个可验证的中间状态，比如“完成了数据层的修改，测试通过”或者“完成了接口定义，但实现还没写”。

具体来说，我会把长任务分成三类来处理。第一类是“探索型任务”，比如“帮我看看这个模块为什么性能差”，这种任务适合一口气跑完，因为中间暂停反而会打断它的分析思路。第二类是“修改型任务”，比如“把这个模块的错误处理统一成新的模式”，这种适合按文件或按子模块拆分，每改完一个部分暂停一下，我检查完再继续。第三类是“混合型任务”，比如“先分析再重构”，这种我会让它先跑完分析阶段，暂停，我看完分析结果确认方向没问题，再让它进入重构阶段。

还有一个实用技巧：在启动长任务之前，先让 Claude Code 输出一个任务计划，包括它打算分几步、每步做什么、预计影响哪些文件。你看完这个计划之后，可以调整步骤顺序或者增减步骤，然后再让它开始执行。这个“先计划后执行”的模式，比直接让它开跑要可控得多。

4. 插件管理：从“能装”到“能管”的进化

4.1 之前的插件机制差在哪

Claude Code 的插件机制在早期版本里基本是“能装就行”。你可以通过配置文件或者命令行安装插件，装完之后它就会在会话里生效。但问题在于，你很难知道当前装了哪些插件、每个插件在干什么、以及某个插件是不是在拖慢响应速度或者干扰输出。

我之前的做法是，装完插件就不管了，直到某天发现 Claude Code 的行为变得很奇怪，才想起来可能是某个插件在捣乱。但那时候已经很难排查了，因为没有一个统一的界面能看到插件的状态和影响。更麻烦的是，有些插件之间会冲突，比如两个插件都想修改同一类文件的处理逻辑，结果就是行为不可预测。

4.2 新的插件管理能力：查看、启用、禁用、排查

九月更新之后，插件管理有了明显的改进。现在你可以通过命令查看当前安装的所有插件列表，每个插件会显示它的名称、版本、状态（启用/禁用）、以及它声明的作用范围。这个列表是实时更新的，你装了新插件或者禁用了旧插件，列表会立刻反映出来。

更重要的是，现在支持按会话启用或禁用插件。也就是说，你可以在一个会话里只启用跟当前任务相关的插件，避免无关插件干扰。比如我在做前端任务时，就只启用跟 JavaScript/TypeScript 相关的插件，把 Python 相关的插件禁掉。这个功能看起来简单，但实际用起来对输出质量的提升很明显——模型不用在一堆无关的插件指令里做取舍了。

排查方面，现在如果某个插件导致异常行为，你可以单独禁用它来验证。我之前遇到过一个情况：Claude Code 在读取某个配置文件时总是报错，排查了半天发现是一个第三方插件在拦截文件读取操作。以前这种情况只能靠猜，现在可以直接在插件列表里找到可疑对象，禁用后重试，几分钟就能定位问题。

4.3 插件选型与组合的实战建议

基于我这段时间的使用经验，插件不是越多越好。我的建议是保持“最小必要集”：只装你当前项目真正需要的插件，并且定期清理不再使用的。具体来说，我会按项目类型来配置插件组合。做 Node.js 后端项目时，启用跟 npm/pnpm、TypeScript、数据库相关的插件；做前端项目时，启用跟框架、样式、构建工具相关的插件；做脚本类任务时，只保留最基础的插件，避免干扰。

还有一个细节：插件的加载顺序有时会影响行为。如果两个插件都试图修改同一类操作，后加载的可能会覆盖先加载的。虽然新版本的管理界面没有直接暴露加载顺序的调整，但你可以通过禁用其中一个来避免冲突。我的做法是，如果发现两个插件功能重叠，就只保留更活跃、更新更频繁的那个。

另外，我建议在 AGENTS.md 里加一条关于插件的说明，比如“当前项目启用的插件列表及用途”，这样即使换了机器或者换了会话，你也能快速回忆起当前的插件配置。这个习惯在团队协作场景下尤其有用，因为不同人的插件配置可能不一样，导致同一个任务在不同人那里表现不同。

5. 三个更新点的联动效应：实际工作流怎么变

5.1 一个完整的长任务工作流示例

把这三个更新点串起来，我现在的工作流是这样的。假设我要做一个跨模块的重构任务。第一步，我先检查 AGENTS.md 里的行为规范是否覆盖了这个任务类型，比如有没有“修改公共接口前必须先确认调用方”这样的约束。第二步，我启动 Claude Code，让它先输出任务计划，我确认后开始执行。第三步，执行过程中，如果任务超过了我预期的复杂度，我就在一个逻辑步骤完成后暂停，检查修改结果，确认没问题再续接。第四步，如果发现某个插件在干扰输出，我就在插件列表里把它禁掉，然后让 Claude Code 重新执行当前步骤。

这个流程比之前顺畅很多，核心原因是每个环节都有“检查点”。以前是“启动-等待-看结果”，现在是“计划-执行-暂停-检查-续接”，可控性完全不一样。

5.2 团队协作场景下的配置管理

在团队场景下，这三个更新点的价值更明显。AGENTS.md 可以跟着仓库走，成为团队共享的代理行为规范。新成员拉下代码后，Claude Code 会自动读取这份规范，行为跟老成员保持一致。长任务暂停续接则解决了“交接”问题——一个人跑到一半的任务，可以暂停后把状态摘要发给另一个人，另一个人在自己的环境里续接，不需要从头解释背景。插件管理则让团队可以统一插件配置，避免“你的环境能跑我的环境跑不了”这种问题。

我建议团队里指定一个人负责维护 AGENTS.md 和插件配置清单，每次有新的行为规范或者插件调整，都通过代码评审的方式更新。这样能保证配置的变更是有记录、可追溯的，而不是某个人在自己机器上偷偷改了导致行为不一致。

5.3 我踩过的三个坑和对应的解法

第一个坑是 AGENTS.md 写得太啰嗦。我一开始把很多“常识性”的规范也写进去了，比如“不要删除生产数据库”，结果发现这些冗余指令反而稀释了真正重要的约束。后来我精简到只写“这个项目特有的、容易出错的”规范，效果好了很多。

第二个坑是暂停续接时忘了检查文件状态。有一次我暂停后手动改了一个文件，恢复任务时没告诉 Claude Code，结果它基于旧版本继续改，产生了冲突。后来我养成了习惯：暂停期间如果有手动修改，恢复时第一句话就是“我手动改了某个文件，请重新读取后再继续”。

第三个坑是插件禁用后忘了恢复。我有一次为了排查问题禁用了某个插件，任务完成后忘了重新启用，结果后面几天都以为那个插件坏了。现在我会在 AGENTS.md 里记一笔“临时禁用的插件”，任务结束后对照检查。

6. 常见问题与排查技巧实录

6.1 AGENTS.md 不生效怎么办

最常见的原因是文件名大小写不对。必须是全大写AGENTS.md，写成agents.md或者Agents.md都不会被识别。其次检查文件位置，根目录的 AGENTS.md 一定会被加载，子目录的需要在对应目录下执行任务时才会加载。如果确认文件名和位置都没问题，可以试着在会话里直接问 Claude Code“你读到了哪些 AGENTS.md 配置”，它会列出当前生效的配置来源，方便你定位问题。

还有一个容易被忽略的点：如果 AGENTS.md 里有语法错误，比如列表格式混乱或者有特殊字符，可能导致解析失败。我的做法是保持格式极简，只用标题和列表，不用复杂的嵌套或者特殊符号。

6.2 长任务续接后行为异常怎么排查

续接后行为异常通常有两个原因：上下文丢失或者文件状态不一致。排查方法是，恢复任务后先让它输出当前的任务状态摘要，看看它认为已经完成了哪些步骤、下一步计划是什么。如果摘要跟你的预期不符，说明上下文保留出了问题，可能需要重新描述任务目标。如果摘要没问题但执行结果不对，那大概率是文件状态不一致，让它重新读取相关文件再继续。

另外，如果续接后它开始重复之前已经做过的步骤，说明进度记录丢失了。这种情况我建议不要强行续接，而是让它重新输出任务计划，你手动把已经完成的部分标记出来，然后从下一个未完成步骤开始。

6.3 插件冲突的典型表现和解决路径

插件冲突的表现通常有三种：输出格式突然变化、某些操作被静默跳过、或者报错信息指向不存在的文件。排查路径是：先在插件列表里禁用最近新装的插件，重试任务；如果问题消失，说明就是这个插件的问题，可以考虑找替代品或者调整配置。如果禁用后问题还在，就继续禁用其他插件，直到定位到冲突源。

我整理了一个简单的排查表，方便快速对照：

6.4 版本升级后的配置迁移检查清单

每次 Claude Code 大版本更新后，我都会跑一遍这个检查清单：确认 AGENTS.md 和 CLAUDE.md 都被正确读取；确认长任务的暂停续接功能正常；确认插件列表没有出现未知插件；确认之前禁用的插件没有被自动启用；确认行为规范里的关键约束仍然生效。这个清单跑下来大概五分钟，但能避免很多“更新后行为变了但不知道哪里变了”的困惑。

7. 我对这套更新组合的实际体会

用了一个多月下来，我最大的体会是：Claude Code 这次更新的核心思路是“把控制权还给使用者”。AGENTS.md 让你能精细控制代理行为，长任务暂停续接让你能控制执行节奏，插件管理让你能控制环境干扰。这三个控制点加起来，才让 Claude Code 从一个“黑盒工具”变成了一个“可调试、可干预、可复现”的工程伙伴。

如果你还没开始用 AGENTS.md，我建议先从一个小项目试起，把最常用的三到五条行为规范写进去，感受一下差异。长任务暂停续接则适合在你下次遇到复杂重构时主动用起来，不要等它跑飞了才后悔。插件管理嘛，养成定期清理的习惯就好，别让环境变成杂物间。

最后分享一个我最近发现的小技巧：在 AGENTS.md 里加一条“每次任务开始前，先输出你打算遵守的关键约束”，这样你能在任务启动阶段就确认它有没有正确加载配置，比跑到一半才发现问题要省事得多。这个技巧在切换项目或者切换会话时特别有用，几秒钟就能完成一次配置自检。