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 个文件的改动正常一口气跑完要十几分钟。操作流程是这样的正常发起任务让它开始干活。跑到一半我按了暂停具体快捷键看你终端配置我这边是CtrlC一次触发优雅暂停而不是直接杀掉进程。它会输出当前进度摘要包括已完成步骤、待办步骤、已修改文件列表。关闭终端该干嘛干嘛。下次回来在项目目录下重新启动它会提示检测到未完成任务问你是否恢复。确认恢复后它先复述一遍当前状态然后从断点继续。我特意在恢复后检查了它有没有“失忆”。实测下来它在恢复时会重新读取AGENTS.md和CLAUDE.md并且把之前改过的文件重新纳入上下文。这一点很关键——它不是简单记住“我改过 auth.ts”而是重新读了改完之后的 auth.ts确保后续改动基于最新版本。实操心得暂停之前最好手动在对话里补一句“当前进度记一下我要暂停了”。这样它生成的进度摘要会更准确。我试过直接硬暂停恢复时它对某个中间状态的描述有点模糊补一句话之后明显清晰很多。3.3 恢复后如何验证它没“跑偏”恢复之后不要直接让它闷头继续先做一次快速校验。我的习惯是问它三个问题当前任务的目标是什么已经改了哪些文件每个文件改了什么下一步准备做什么如果这三个问题它答得清楚说明状态恢复没问题可以继续。如果答得含糊那就别急着让它改代码先手动把关键文件的状态跟它对齐。我还遇到过一次恢复后它想重复改一个已经改过的文件。原因是那个文件在暂停期间被我用编辑器手动动过它的记录和实际文件对不上。解决办法很简单恢复后先让它跑一次git status或者git diff用真实的版本控制状态校准它的记忆。这个习惯我现在每次都做基本杜绝了重复改动。4. 插件体系升级从“能装”到“能管”的跨越4.1 插件管理到底管的是什么之前的插件功能说白了就是“能装”。你装一个插件它多一个能力但装完之后你不太清楚它到底改了什么、占了多少上下文、会不会跟别的插件打架。插件一多整个工具的行为就变得不可预测。九月的更新把插件做成了“可管理”的形态。核心变化有这几个插件有了明确的启用/禁用开关不用卸载就能临时关掉。能看到每个插件注入了多少上下文、调用了哪些工具。插件之间的依赖和冲突有了基本检测。这个转变的意义在于你可以像管理浏览器扩展一样管理它们。哪个插件最近没用到先禁用需要的时候再开而不是装了一堆然后忍受越来越慢的响应。4.2 我实际在用的几个插件类型和选择逻辑插件这东西装多了是负担。我现在只留三类插件类型解决什么问题我的选择标准语言/框架增强让代理更懂特定技术栈只装当前项目主语言相关的外部工具桥接连接数据库、API 文档等按需临时启用用完就关工作流辅助格式化、提交信息生成等只留最高频的一两个我踩过的坑是“看到插件就装”。有一次装了五六个结果代理每次响应前要处理一大堆插件注入的上下文明显变慢而且行为开始变得奇怪——它会在不该调用某个工具的时候调用。后来我全部禁用只留两个真正高频的世界就清净了。注意禁用插件不等于卸载。禁用只是让它不参与当前会话配置还在。我建议新插件先禁用状态装好需要的时候再启用观察一两次会话的行为确认没问题再考虑长期开着。4.3 插件与 AGENTS.md 的配合方式插件提供的是“能力”AGENTS.md提供的是“规矩”。两者配合好了代理的行为会非常稳。举个例子我装了一个数据库查询插件同时在AGENTS.md里写清楚“查询生产库必须只读且必须先 explain”。这样插件给了它查库的能力规矩限制了它怎么用这个能力。反过来如果你只装插件不写规矩它可能会拿着查询能力到处乱查。我见过一次它在调试时直接对着一张百万行的表做了全表扫描虽然是在开发库但也够吓人的。从那以后凡是涉及外部资源的插件我一定在AGENTS.md里配套写清楚使用边界。5. 常见问题与排查技巧实录5.1 AGENTS.md 不生效怎么办这是我这段时间被问得最多的问题。排查顺序如下确认文件名大小写。必须是全大写的AGENTS.mdagents.md在部分系统上不认。确认文件在项目根目录也就是你启动 Claude Code 的那个目录。确认文件内容不是空的或者只有注释。如果同时有CLAUDE.md检查里面有没有把AGENTS.md的内容覆盖掉。重启会话。配置文件的读取发生在会话启动时改完文件要新开会话才生效。我遇到过一次怎么都不生效最后发现是文件里有个不可见的 BOM 头导致解析失败。用编辑器另存为无 BOM 的 UTF-8 就好了。这种问题很隐蔽建议用file AGENTS.md命令确认一下编码。5.2 长任务恢复后行为异常的处理恢复后如果发现它开始胡来按这个顺序处理先暂停别让它继续改。跑git diff看实际改了什么跟它的描述对比。如果实际改动和描述对不上手动把不一致的文件恢复到已知状态。重新启动会话这次不要恢复而是新开一个任务把当前真实状态作为起点告诉它。我个人的经验是恢复功能在“任务边界清晰”的时候很稳比如“改这三个文件”。但如果任务本身很发散比如“优化整个项目的性能”恢复后容易跑偏。所以我现在会把大任务拆成边界清晰的小任务每个小任务单独暂停恢复稳定性高很多。5.3 插件冲突的典型表现和解决插件冲突的表现通常很隐蔽不一定报错而是行为变得“怪”。常见信号响应明显变慢但任务复杂度没变。它开始调用一些你没让它用的工具。同一个问题两次回答的风格差异很大。遇到这些先把最近启用的插件禁用看是否恢复。如果恢复了再逐个启用定位到具体是哪个插件的问题。我遇到过一次两个插件都想接管文件读取结果代理每次读文件都要犹豫一下响应慢了一倍。禁用其中一个就好了。5.4 常见问题速查表现象可能原因处理方式AGENTS.md 不生效文件名/位置/编码问题检查大小写、根目录、BOM恢复后重复改文件暂停期间文件被手动改过恢复后先 git diff 校准响应变慢插件过多或冲突禁用最近启用的插件行为不符合规范AGENTS.md 没写清楚补充禁区和使用边界任务跑到一半失忆上下文超限拆小任务用暂停恢复6. 我个人的使用节奏和一些小技巧用到现在我形成了一套比较固定的节奏。每天早上开工先花两分钟把当天要做的事拆成几个边界清晰的任务每个任务对应一次会话。任务之间用暂停恢复衔接而不是一个会话从头跑到尾。这样即使中间被打断损失也有限。AGENTS.md我大概每周review一次把新踩的坑补进去。比如上周发现它老爱用console.log调试我就在规范里加了一条“调试用 debug 库不要留 console.log”。这种小规矩积累多了它的行为会越来越贴合你的习惯。插件方面我现在保持“最小可用集”。新插件先禁用装好观察一周再决定要不要长期开。这个习惯帮我省了不少排查冲突的时间。最后分享一个我觉得挺有用的小技巧在AGENTS.md里加一节“最近变更”记录最近几次你纠正过它的地方。比如“上次你把测试文件放错目录了测试统一放 tests/ 下”。它每次启动都会读到这些相当于带着你的反馈记忆开工重复犯错的概率明显下降。这个做法我从九月更新之后开始用效果比我想象的好。