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

九月份这波 Claude Code 的更新，我第一时间在自己的主力开发机上跑了一遍。说实话，之前我对它的定位一直是“终端里能聊两句的编码助手”，但这次更新之后，它开始有点“正经项目协作工具”的样子了。核心变化集中在三块：AGENTS.md 被正式认了、长任务支持暂停与恢复、插件体系从“能装”进化到“能管”。这三个点单独看都不算炸裂，但叠在一起，意味着你可以把它塞进一个真实的、跨天甚至跨周的开发流程里，而不是每次开个新会话从头讲一遍背景。

先给还没上手的朋友一句话说明白：Claude Code 是一个跑在终端里的编码代理工具，能读你的项目文件、执行命令、改代码、跑测试。它跟那种“在 IDE 里补全一行”的插件不是一回事，它更像一个能自己动手的实习生。而这次九月更新，解决的是“这个实习生记性差、干到一半被打断就废了、工具乱堆一气”这三个老大难问题。

适合谁看？如果你已经在用 Claude Code，或者正在犹豫要不要把它引入日常开发流，这篇梳理能帮你省下至少两三个晚上的试错时间。如果你只是听说过 CLAUDE.md 但还没搞明白 AGENTS.md 是干嘛的，我也会从零讲清楚。全文基于我自己的实操记录和踩坑经验，参数和步骤都可以直接抄。

2. AGENTS.md 被正式认了：多工具协作的“通用说明书”

2.1 为什么之前 CLAUDE.md 一家独大，现在要认 AGENTS.md

之前 Claude Code 只认项目根目录下的CLAUDE.md，你所有的项目背景、编码规范、命令约定都写在这里面。问题是，现在终端里的编码代理不止一家，今天用这个、明天试那个，每个工具都要你写一份自己的配置文件，维护成本直接翻倍。AGENTS.md这个约定最早是社区推起来的，思路很简单：用一份通用的 Markdown 描述项目对 AI 代理的期望，谁认这个格式，谁就能读。

九月更新之后，Claude Code 会同时读取AGENTS.md和CLAUDE.md。我实测下来的优先级是这样的：如果两个文件都存在，CLAUDE.md里的内容会覆盖或补充AGENTS.md的同名条目。这个设计挺聪明——AGENTS.md放跨工具通用的部分，CLAUDE.md放 Claude Code 特有的调优，各管一摊。

注意：不要在两个文件里写互相矛盾的指令。我踩过一次坑，AGENTS.md里写了“测试用 pytest”，CLAUDE.md里手滑写了“测试用 unittest”，结果它每次跑测试都犹豫，最后按CLAUDE.md走，白白浪费了一轮对话。

2.2 AGENTS.md 里到底该写什么：一份可直接抄的模板

很多人第一次写这个文件，要么写得太虚（“请写出高质量代码”），要么写得太细（把整个架构文档搬进去）。我的经验是，控制在 50 到 150 行之间，只写“代理必须知道、否则会做错”的信息。下面是我现在项目里在用的结构，你可以直接改：

# AGENTS.md ## 项目概览 - 这是一个 Node.js + TypeScript 的后端服务，入口在 src/index.ts - 包管理器用 pnpm，不要用 npm 或 yarn ## 常用命令 - 安装依赖：pnpm install - 跑测试：pnpm test（单个文件：pnpm test <path>） - 类型检查：pnpm typecheck - 本地启动：pnpm dev ## 编码约定 - 所有导出函数必须有 JSDoc 注释 - 错误处理统一用 src/utils/errors.ts 里的 AppError - 不要引入新的第三方依赖，除非我先同意 ## 禁区 - 不要动 migrations/ 目录下的文件 - 不要修改 .env 和任何密钥相关文件 - 提交前必须跑通 pnpm typecheck 和 pnpm test

这份模板的关键在于“禁区”那一节。代理再聪明，也不知道哪些文件是碰不得的。你把红线画清楚，它就不会在半夜自动帮你“优化”数据库迁移脚本。

2.3 多工具共存时的目录组织技巧

如果你同时用多个终端代理工具，我建议的目录结构是这样：

project-root/ ├── AGENTS.md # 通用约定，所有工具都读 ├── CLAUDE.md # Claude Code 专属调优 ├── .claude/ # Claude Code 的本地配置和插件 └── src/

AGENTS.md里写通用的命令和约定，CLAUDE.md里写“Claude Code 特有的提示”，比如你希望它用某种特定的思考方式、或者针对某个模型版本的调优。这样换工具的时候，只需要维护一份通用文件，专属文件各写各的，互不干扰。

我实测下来，这样组织之后，新开一个会话让代理理解项目背景的时间，从原来的三四轮对话压缩到基本一轮就位。因为它一进来就把该读的读了，不用你反复解释。

3. 长任务暂停与恢复：终于不用一口气干完了

3.1 长任务为什么会“断”，之前的痛点在哪

在讲新功能之前，先说清楚之前的坑。Claude Code 执行一个复杂任务时，比如“重构整个认证模块并补全测试”，它会在一个会话里连续跑很多步。问题是，这个会话是有上下文窗口限制的，任务越长，前面的信息越容易被挤掉，跑到后面它就开始“忘事”——忘了你之前定的规范，甚至忘了自己改过哪些文件。

更现实的问题是，你不可能一直盯着它跑。跑到一半你要去开会、要下班、要重启机器，之前的做法只能中断，下次从头再来。而“从头再来”意味着它可能做出跟上次不一样的改动，你之前review过的部分全白费。

九月的暂停与恢复功能，解决的就是这个“跨会话续接”的问题。它会把当前任务的进度、已改动的文件、待办事项持久化下来，下次你回来的时候，从断点接着跑。

3.2 暂停与恢复的实际操作流程

我拿一个真实任务跑了一遍：给一个 Express 项目加一套基于 JWT 的鉴权中间件，并且补上对应的单元测试。这个任务大概涉及 8 到 10 个文件的改动，正常一口气跑完要十几分钟。

操作流程是这样的：

1. 正常发起任务，让它开始干活。
2. 跑到一半，我按了暂停（具体快捷键看你终端配置，我这边是Ctrl+C一次触发优雅暂停，而不是直接杀掉进程）。
3. 它会输出当前进度摘要，包括已完成步骤、待办步骤、已修改文件列表。
4. 关闭终端，该干嘛干嘛。
5. 下次回来，在项目目录下重新启动，它会提示检测到未完成任务，问你是否恢复。
6. 确认恢复后，它先复述一遍当前状态，然后从断点继续。

我特意在恢复后检查了它有没有“失忆”。实测下来，它在恢复时会重新读取AGENTS.md和CLAUDE.md，并且把之前改过的文件重新纳入上下文。这一点很关键——它不是简单记住“我改过 auth.ts”，而是重新读了改完之后的 auth.ts，确保后续改动基于最新版本。

实操心得：暂停之前，最好手动在对话里补一句“当前进度记一下，我要暂停了”。这样它生成的进度摘要会更准确。我试过直接硬暂停，恢复时它对某个中间状态的描述有点模糊，补一句话之后明显清晰很多。

3.3 恢复后如何验证它没“跑偏”

恢复之后不要直接让它闷头继续，先做一次快速校验。我的习惯是问它三个问题：

• 当前任务的目标是什么？
• 已经改了哪些文件，每个文件改了什么？
• 下一步准备做什么？

如果这三个问题它答得清楚，说明状态恢复没问题，可以继续。如果答得含糊，那就别急着让它改代码，先手动把关键文件的状态跟它对齐。

我还遇到过一次恢复后它想重复改一个已经改过的文件。原因是那个文件在暂停期间被我用编辑器手动动过，它的记录和实际文件对不上。解决办法很简单：恢复后先让它跑一次git status或者git diff，用真实的版本控制状态校准它的记忆。这个习惯我现在每次都做，基本杜绝了重复改动。

4. 插件体系升级：从“能装”到“能管”的跨越

4.1 插件管理到底管的是什么

之前的插件功能，说白了就是“能装”。你装一个插件，它多一个能力，但装完之后你不太清楚它到底改了什么、占了多少上下文、会不会跟别的插件打架。插件一多，整个工具的行为就变得不可预测。

九月的更新把插件做成了“可管理”的形态。核心变化有这几个：

• 插件有了明确的启用/禁用开关，不用卸载就能临时关掉。
• 能看到每个插件注入了多少上下文、调用了哪些工具。
• 插件之间的依赖和冲突有了基本检测。

这个转变的意义在于，你可以像管理浏览器扩展一样管理它们。哪个插件最近没用到，先禁用，需要的时候再开，而不是装了一堆然后忍受越来越慢的响应。

4.2 我实际在用的几个插件类型和选择逻辑

插件这东西，装多了是负担。我现在只留三类：

我踩过的坑是“看到插件就装”。有一次装了五六个，结果代理每次响应前要处理一大堆插件注入的上下文，明显变慢，而且行为开始变得奇怪——它会在不该调用某个工具的时候调用。后来我全部禁用，只留两个真正高频的，世界就清净了。

注意：禁用插件不等于卸载。禁用只是让它不参与当前会话，配置还在。我建议新插件先禁用状态装好，需要的时候再启用，观察一两次会话的行为，确认没问题再考虑长期开着。

4.3 插件与 AGENTS.md 的配合方式

插件提供的是“能力”，AGENTS.md提供的是“规矩”。两者配合好了，代理的行为会非常稳。举个例子：我装了一个数据库查询插件，同时在AGENTS.md里写清楚“查询生产库必须只读，且必须先 explain”。这样插件给了它查库的能力，规矩限制了它怎么用这个能力。

反过来，如果你只装插件不写规矩，它可能会拿着查询能力到处乱查。我见过一次它在调试时直接对着一张百万行的表做了全表扫描，虽然是在开发库，但也够吓人的。从那以后，凡是涉及外部资源的插件，我一定在AGENTS.md里配套写清楚使用边界。

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

5.1 AGENTS.md 不生效怎么办

这是我这段时间被问得最多的问题。排查顺序如下：

1. 确认文件名大小写。必须是全大写的AGENTS.md，agents.md在部分系统上不认。
2. 确认文件在项目根目录，也就是你启动 Claude Code 的那个目录。
3. 确认文件内容不是空的，或者只有注释。
4. 如果同时有CLAUDE.md，检查里面有没有把AGENTS.md的内容覆盖掉。
5. 重启会话。配置文件的读取发生在会话启动时，改完文件要新开会话才生效。

我遇到过一次怎么都不生效，最后发现是文件里有个不可见的 BOM 头，导致解析失败。用编辑器另存为无 BOM 的 UTF-8 就好了。这种问题很隐蔽，建议用file AGENTS.md命令确认一下编码。

5.2 长任务恢复后行为异常的处理

恢复后如果发现它开始胡来，按这个顺序处理：

• 先暂停，别让它继续改。
• 跑git diff看实际改了什么，跟它的描述对比。
• 如果实际改动和描述对不上，手动把不一致的文件恢复到已知状态。
• 重新启动会话，这次不要恢复，而是新开一个任务，把当前真实状态作为起点告诉它。

我个人的经验是，恢复功能在“任务边界清晰”的时候很稳，比如“改这三个文件”。但如果任务本身很发散，比如“优化整个项目的性能”，恢复后容易跑偏。所以我现在会把大任务拆成边界清晰的小任务，每个小任务单独暂停恢复，稳定性高很多。

5.3 插件冲突的典型表现和解决

插件冲突的表现通常很隐蔽，不一定报错，而是行为变得“怪”。常见信号：

• 响应明显变慢，但任务复杂度没变。
• 它开始调用一些你没让它用的工具。
• 同一个问题，两次回答的风格差异很大。

遇到这些，先把最近启用的插件禁用，看是否恢复。如果恢复了，再逐个启用，定位到具体是哪个插件的问题。我遇到过一次两个插件都想接管文件读取，结果代理每次读文件都要犹豫一下，响应慢了一倍。禁用其中一个就好了。

5.4 常见问题速查表

6. 我个人的使用节奏和一些小技巧

用到现在，我形成了一套比较固定的节奏。每天早上开工，先花两分钟把当天要做的事拆成几个边界清晰的任务，每个任务对应一次会话。任务之间用暂停恢复衔接，而不是一个会话从头跑到尾。这样即使中间被打断，损失也有限。

AGENTS.md我大概每周review一次，把新踩的坑补进去。比如上周发现它老爱用console.log调试，我就在规范里加了一条“调试用 debug 库，不要留 console.log”。这种小规矩积累多了，它的行为会越来越贴合你的习惯。

插件方面，我现在保持“最小可用集”。新插件先禁用装好，观察一周再决定要不要长期开。这个习惯帮我省了不少排查冲突的时间。

最后分享一个我觉得挺有用的小技巧：在AGENTS.md里加一节“最近变更”，记录最近几次你纠正过它的地方。比如“上次你把测试文件放错目录了，测试统一放 tests/ 下”。它每次启动都会读到这些，相当于带着你的反馈记忆开工，重复犯错的概率明显下降。这个做法我从九月更新之后开始用，效果比我想象的好。