1. 这次九月更新到底改了什么从“能用”到“好用”的分水岭Claude Code 这个工具我从早期版本就开始跟说实话前几个月的更新节奏虽然快但总给人一种“功能堆得挺多、用起来还是别扭”的感觉。九月份这波更新不一样它解决的是三个长期被用户吐槽的硬伤配置文件到底认哪个、长任务断了怎么办、插件装完就没人管了。这三个问题看起来零散实际上串起来就是一条线——Claude Code 正在从一个“能跑命令的聊天窗口”变成一个“有工程规范、有任务管理、有插件生态”的完整开发环境。先说最直观的变化。以前你在项目根目录放一个CLAUDE.mdClaude Code 会读但如果你同时放了AGENTS.md它就不一定认了。很多团队用AGENTS.md来统一管理多个 AI 工具的配置比如 Cursor、Windsurf、Claude Code 共用一份 agent 定义。九月更新之后Claude Code 正式把AGENTS.md纳入识别范围而且优先级逻辑做了明确如果两个文件都存在它会先读AGENTS.md再读CLAUDE.md后者作为补充覆盖。这个改动看似小但对多工具混用的团队来说省掉了大量“为什么 Claude Code 不按我的规则来”的排查时间。第二个变化是长任务暂停与恢复。以前跑一个大型重构或者批量代码生成中途要是终端断了、网络抖了、或者你手动 CtrlC 了整个任务上下文就丢了只能从头再来。现在 Claude Code 会把任务状态持久化到本地重新进入会话时可以通过特定命令恢复上一次的进度。这个功能对跑长时间代码分析、批量文件处理、多轮迭代重构的场景来说简直是救命稻草。第三个变化是插件管理。之前插件是“能装就行”装完你也不知道它到底加载了没有、版本对不对、有没有冲突。九月更新引入了插件生命周期管理包括启用、禁用、查看状态、检查更新、卸载清理。这意味着插件从“一次性安装”变成了“可维护的依赖项”对重度用户来说终于不用靠猜来排查插件问题了。提示如果你之前因为配置混乱或者任务丢失而放弃 Claude Code这次更新值得重新捡起来试一遍。尤其是团队协作场景AGENTS.md的统一管理能力会明显降低沟通成本。2. AGENTS.md 正式认领多工具配置统一的正确姿势2.1 为什么 AGENTS.md 比 CLAUDE.md 更适合团队协作先搞清楚一个基本问题CLAUDE.md和AGENTS.md到底有什么区别。CLAUDE.md是 Claude Code 专属的配置文件里面写的是给 Claude Code 看的指令比如“这个项目用 pnpm 不用 npm”“测试命令是pnpm test:unit”“不要动legacy/目录”。而AGENTS.md是一个更通用的 agent 配置文件格式它的设计初衷是让多个 AI 编程工具共用同一份行为定义。我实际带团队的时候遇到过这种情况前端用 Cursor后端用 Claude Code还有人用 Windsurf 做原型。如果每个工具都维护一份独立配置改一个规则要同步三个地方漏一个就出问题。AGENTS.md的好处是你只需要维护一份所有支持这个格式的工具都会读。九月更新之前Claude Code 对AGENTS.md的支持是“能读但不保证”现在是“正式认领且优先级明确”。具体优先级逻辑是这样的Claude Code 启动时会先扫描项目根目录如果发现AGENTS.md先加载它作为基础配置然后检查同目录下有没有CLAUDE.md如果有再把CLAUDE.md的内容合并进来冲突的地方以CLAUDE.md为准。这个设计很合理——AGENTS.md管通用规则CLAUDE.md管 Claude Code 特有的覆盖项。2.2 一份可直接抄的 AGENTS.md 模板很多人不知道AGENTS.md该写什么我把自己项目里用了半年的模板整理出来你可以直接改改就用# AGENTS.md ## 项目概览 - 技术栈TypeScript React Vite Tailwind - 包管理器pnpm禁止使用 npm 或 yarn - Node 版本 20.11.0 ## 常用命令 - 安装依赖pnpm install - 开发启动pnpm dev - 单元测试pnpm test:unit - 端到端测试pnpm test:e2e - 类型检查pnpm typecheck - 代码格式化pnpm format ## 代码规范 - 所有组件使用函数式写法禁止 class 组件 - 状态管理优先用 zustand复杂场景才用 redux toolkit - API 请求统一走 src/lib/api.ts 封装禁止在组件里直接 fetch - 提交信息遵循 conventional commits 格式 ## 目录约定 - src/components/ 放通用组件 - src/features/ 放业务模块每个模块自带 hooks 和 utils - src/lib/ 放工具函数和第三方封装 - legacy/ 目录是历史遗留代码除非明确要求否则不要修改 ## 禁止事项 - 不要自动生成 console.log 调试语句 - 不要修改 pnpm-lock.yaml 除非明确要求升级依赖 - 不要删除任何 .test.ts 文件这份模板的关键在于命令要具体、规范要可执行、禁止事项要明确。我见过太多人写AGENTS.md写成“请写出高质量代码”这种废话AI 读了等于没读。你要把它当成给一个新入职同事写的上手文档越具体越好。2.3 多文件共存时的排查思路实际使用中最容易出问题的是“我明明写了规则Claude Code 就是不遵守”。这时候按下面这个顺序排查确认文件位置AGENTS.md和CLAUDE.md必须放在项目根目录放在子目录里默认不读。确认文件编码必须是 UTF-8带 BOM 的有时会解析异常。确认优先级如果两个文件都有CLAUDE.md覆盖AGENTS.md检查是不是CLAUDE.md里写了冲突规则。确认加载日志启动 Claude Code 时加--verbose参数能看到它实际读了哪些配置文件。确认缓存改完配置后重启会话旧会话可能还持有旧配置。注意如果你在 monorepo 里工作根目录的AGENTS.md会被所有子包继承。如果某个子包需要特殊规则在该子包目录下再放一个AGENTS.mdClaude Code 会优先读最近的。3. 长任务暂停与恢复断了不用从头再来3.1 这个功能解决的是什么场景先描述一个真实场景。上周我让 Claude Code 帮我做一个跨 30 多个文件的 API 迁移把旧的request库全部换成fetch封装。这个任务跑了大概 40 分钟中间它需要读文件、分析依赖、逐个修改、跑测试验证。跑到第 25 分钟的时候我手贱按了 CtrlC 想看看进度结果整个任务上下文直接没了只能重新描述需求从头跑。九月更新之后这种情况有了明确的处理方式。Claude Code 现在会把长任务的执行状态写入本地的一个任务记录文件包括已完成步骤、待处理文件列表、当前上下文摘要。当你重新进入会话时可以用/resume命令查看最近的任务记录选择继续执行。它不会完全恢复所有内存状态但会恢复任务目标和进度指针相当于“接着上次断的地方继续干”。3.2 实际操作流程与命令具体操作分三步第一步启动长任务时明确标记。你可以在指令里加上“这是一个长任务请分步骤执行并记录进度”Claude Code 会更积极地做状态持久化。比如请帮我完成以下长任务分步骤执行每完成一个步骤记录进度 1. 扫描 src/ 下所有使用 request 库的文件 2. 逐个替换为 fetch 封装 3. 每替换 5 个文件跑一次测试 4. 全部完成后跑完整测试套件第二步中断后恢复。重新进入 Claude Code 会话输入/resume它会列出最近的任务记录格式大概是[1] 2024-09-15 14:30 API 迁移任务 进度 18/32 文件 状态可恢复 [2] 2024-09-14 09:15 测试补全任务 进度 7/12 模块 状态已完成选择对应的编号Claude Code 会加载任务上下文然后你输入“继续”即可。第三步手动清理。已完成的任务记录不会自动删除时间长了会堆积。用/resume --clean可以清理超过 7 天的记录或者/resume --delete 编号删除指定记录。3.3 哪些任务适合用暂停恢复哪些不适合不是所有任务都值得用这个功能。我实测下来适合的场景是批量文件处理、多轮重构、长时间代码分析、跨模块迁移。这些任务的共同点是步骤多、耗时长、中断成本高。不适合的场景是快速问答、单文件修改、交互式调试。这些任务本身几分钟就结束了用暂停恢复反而增加操作步骤。还有一个坑要注意暂停恢复依赖本地状态文件如果你换了机器或者清了缓存目录记录就没了。所以重要任务建议在指令里让它同时输出一份进度日志到项目目录比如migration-progress.md这样即使状态文件丢了你也能根据日志手动续上。提示状态文件默认存在~/.claude-code/tasks/目录下你可以定期备份这个目录或者把它纳入 dotfiles 管理。4. 插件从能装到能管生命周期管理实操4.1 插件管理命令一览九月更新之前插件相关操作基本就是“装”和“删”中间状态完全黑盒。现在有了完整的管理命令我整理成表格方便查阅命令作用常用场景/plugin list列出所有已安装插件及状态排查插件是否加载/plugin enable 名称启用指定插件临时关闭后重新开启/plugin disable 名称禁用指定插件但不卸载排查插件冲突/plugin info 名称查看插件详情、版本、依赖确认版本是否匹配/plugin update 名称更新到最新版本修复已知问题/plugin update --all更新所有插件定期维护/plugin remove 名称完全卸载插件清理不再使用的插件/plugin doctor检查插件健康状态排查加载失败原因/plugin doctor是我用得最多的命令。它会检查每个插件的依赖是否满足、配置文件是否合法、有没有版本冲突。之前我装了一个代码格式化插件一直不生效用doctor一查发现它依赖的某个库版本和另一个插件冲突了禁用其中一个之后立刻正常。4.2 插件冲突的典型表现与排查插件冲突最常见的表现有三种一是 Claude Code 启动变慢二是某些命令行为异常三是插件功能时灵时不灵。排查思路是二分法先/plugin list看装了哪些然后逐个/plugin disable每禁用一个重启会话测试一次直到问题消失就能定位到冲突插件。我遇到过最隐蔽的一次冲突是两个插件都试图 hook 文件保存事件一个做格式化一个做 lint 检查结果保存时互相触发对方形成死循环文件保存卡死。这种问题用doctor不一定能查出来只能靠禁用排查。注意禁用插件不会删除它的配置和数据重新启用后状态还在。但卸载会清理所有相关文件卸载前确认没有其他插件依赖它。4.3 插件选型的经验法则装了十几个插件之后我总结出几条选型原则。第一优先选维护活跃的看最近一次更新是不是在三个月内。第二优先选依赖少的依赖链越长越容易冲突。第三功能重叠的只留一个比如格式化插件装一个就够了装三个只会互相打架。第四生产环境和实验环境分开新插件先在测试项目里跑一周再放到主力项目。还有一点插件不是越多越好。我现在的主力项目只留了四个插件一个做代码格式化、一个做 lint 集成、一个做 git 辅助、一个做测试运行器。其他花里胡哨的都卸了启动速度明显快了一截。5. 常见问题与排查技巧实录5.1 配置文件不生效的排查清单现象可能原因解决方法规则完全不生效文件不在根目录移到项目根目录部分规则生效两个文件冲突检查 CLAUDE.md 覆盖项改完没反应会话缓存旧配置重启会话中文乱码编码不是 UTF-8转成 UTF-8 无 BOMmonorepo 子包不生效根目录规则被覆盖子包单独放 AGENTS.md5.2 长任务恢复失败的常见原因恢复失败通常有四个原因状态文件被清理、任务记录超过保留期限、项目路径变了、Claude Code 版本升级导致格式不兼容。前两个好解决定期备份状态目录就行。第三个要注意如果你把项目挪了位置恢复时它按旧路径找文件会找不到这时候手动把状态文件里的路径改一下。第四个最麻烦大版本升级有时会改状态文件格式旧记录读不了只能重新跑。我的习惯是跑长任务之前先手动在项目里建一个task-log.md让 Claude Code 每完成一步就追加一行记录。这样即使状态文件丢了我还能根据日志知道跑到哪了手动续上。5.3 插件加载失败的快速定位插件加载失败先跑/plugin doctor它会给出具体错误。常见错误码和处理方式DEP_MISSING依赖缺失跑/plugin update 名称重新拉依赖。VERSION_CONFLICT版本冲突禁用冲突插件或降级。CONFIG_INVALID配置文件格式错检查插件的配置文件。PERMISSION_DENIED权限问题检查插件目录的读写权限。如果doctor也查不出来就去看日志文件默认在~/.claude-code/logs/plugin.log里面会有详细的加载过程记录。6. 我个人的使用体会与后续扩展思路这套更新用下来最大的感受是 Claude Code 终于开始认真对待“工程化”这件事了。以前它更像一个聪明的助手但缺少工程工具该有的稳定性和可管理性。AGENTS.md的正式支持让团队协作有了统一入口长任务暂停恢复让重活变得可中断可续接插件管理让扩展生态有了基本秩序。我目前的做法是每个项目根目录放一份AGENTS.md管通用规则CLAUDE.md只写 Claude Code 特有的覆盖项保持精简。长任务一律加进度日志输出状态文件每周备份一次。插件每两周跑一次update --all和doctor保持环境干净。后续我打算把AGENTS.md和项目的 CI 流程打通让配置文件变更也走代码审查避免有人随手改规则导致 AI 行为漂移。另外长任务的进度日志可以考虑自动生成结构化数据方便做任务耗时统计和瓶颈分析。这些还在摸索有进展再分享。