1. 九月这波更新真正值得关注的是三件事九月份 Claude Code 的更新日志我翻来覆去看了好几遍第一反应是这次不是那种“修了几个 bug、优化了若干体验”的凑数版本。它动了三个很实在的地方——AGENTS.md 被正式认了、长任务可以暂停再续、插件从“能装”进化到“能管”。这三件事单独拎出来都不算惊天动地但凑在一起指向的是一个很明确的信号这个工具正在从“尝鲜玩具”往“日常主力”过渡。先说清楚这篇东西适合谁看。如果你已经在用 Claude Code 写代码、跑终端命令、做重构那这篇能帮你把新能力用起来如果你还在观望纠结要不要从别的工具迁过来那这篇能让你判断它现在到底能不能扛住真实项目。我不打算复述官方 changelog那种东西你直接看文档就行。我想聊的是这些更新背后解决了什么实际问题以及我在实际使用中踩到的那些文档里不会写的坑。关键词里出现了 AGENTS.md、CLAUDE.md、插件、长任务这几个词正好对应这次更新的三条主线。我按“为什么这个改动重要 → 怎么用 → 我踩了什么坑”的顺序来拆尽量说人话。先说一个背景方便后面理解。Claude Code 本质上是一个跑在终端里的编码助手它能读你的项目文件、执行命令、改代码。但“能读能写”和“知道该读什么、该守什么规矩”是两码事。早期大家靠 CLAUDE.md 这个文件给模型喂项目上下文相当于在项目根目录放一张“说明书”告诉它这个项目用什么框架、代码风格是什么、哪些目录别乱动。这个机制好用但有个问题它是 Claude Code 专属的。你换个工具这张说明书就废了。九月的更新核心就是在解决“专属”和“通用”之间的矛盾同时把长任务和插件这两块短板补上。下面逐个展开。2. AGENTS.md 被认了意味着什么2.1 从 CLAUDE.md 到 AGENTS.md 的迁移逻辑先解释这两个文件的关系因为很多人第一次看到 AGENTS.md 会懵那我原来的 CLAUDE.md 还要不要简单说AGENTS.md 是一个更通用的约定。它的思路是与其每个 AI 编码工具都搞一套自己的上下文文件格式不如大家认一个公共名字。这样你在项目里维护一份 AGENTS.md理论上多个工具都能读。Claude Code 这次“认了”AGENTS.md意思是它会主动去读这个文件把它当作项目级指令的来源之一。那 CLAUDE.md 呢它没被废弃仍然有效。实际行为上我的观察是 Claude Code 会同时关注这两个文件优先级和合并逻辑官方没给特别细的说明但从实测看CLAUDE.md 更像是 Claude Code 的专属补充AGENTS.md 更像是跨工具的公共约定。你可以两个都放也可以只放一个。我自己的做法是这样的把跨工具通用的项目规范技术栈、目录结构、命名约定、禁止事项写进 AGENTS.md把只跟 Claude Code 相关的偏好比如它执行命令时的习惯、特定工具的调用方式留在 CLAUDE.md。这样即使以后换工具通用那部分不用重写。2.2 一份能真正生效的 AGENTS.md 长什么样这里要泼一盆冷水很多人写的 AGENTS.md 是无效的。不是文件没被读到而是写的内容模型根本没法执行。我见过最典型的无效写法是这样的# 项目说明 这是一个 React 项目请写高质量的代码注意代码规范。这种写法的问题在于“高质量”“注意规范”对模型来说等于没说。它不知道你的“高质量”具体指什么。有效的写法应该是可判定、可执行的指令。我实际在用的 AGENTS.md 结构大概是这样几块技术栈声明框架版本、包管理器、Node 版本。这个很重要因为模型默认可能用 npm但你项目用 pnpm不写清楚它就会跑错命令。目录职责哪个目录放组件、哪个放工具函数、哪个是生成代码不要手改。最后这条尤其关键我踩过坑——模型把我自动生成的 API 客户端文件给改了下次生成又覆盖回去白改。命令清单测试怎么跑、lint 怎么跑、构建怎么跑。写清楚命令模型就不会瞎猜。禁区哪些文件不要动、哪些依赖不要升。比如我有个项目锁死了某个库的大版本就在禁区里写明。举个我真实在用的片段## 技术栈 - 包管理器pnpm不要用 npm 或 yarn - Node20.x - 测试vitest命令 pnpm test ## 目录职责 - src/components手写组件 - src/generated自动生成禁止手动修改 - src/api接口封装改这里要同步更新 types ## 禁区 - 不要升级 react 到 19当前锁定 18.3 - 不要修改 .env 和任何 *.lock 文件这份东西写下来不到二十行但模型的行为会稳定很多。关键原则是每一条都要能被验证。“不要用 npm”能被验证“写高质量代码”不能。2.3 多文件场景下的优先级实战真实项目往往不是单文件。monorepo 里根目录一个 AGENTS.md每个子包可能还想有自己的约定。这时候谁覆盖谁我的实测经验是越靠近当前工作目录的文件优先级越高。也就是说你在packages/web目录下工作时packages/web/AGENTS.md会覆盖根目录的同名约定。这个逻辑跟.gitignore、.eslintrc的层级查找是一致的符合直觉。但这里有个坑要提醒如果子目录的文件写得太简略可能会把根目录的重要约定“冲掉”。比如根目录写了“禁止修改 lock 文件”子目录只写了“用 pnpm”那在子目录工作时那条禁区可能就不生效了。我的做法是子目录文件只写差异部分并且显式声明“其余遵循根目录约定”。提示改完 AGENTS.md 之后建议开一个新会话验证一下因为上下文文件通常在会话启动时加载。老会话里改文件不一定立刻生效。3. 长任务暂停与续接终于不用一口气跑完了3.1 长任务为什么会“断”断在哪在讲新功能之前得先说清楚长任务为什么容易出问题。Claude Code 处理一个复杂任务时比如“把这个模块从 class 组件重构成 hooks”它可能要读十几个文件、改七八个文件、跑几次测试。这个过程里任何一环出问题都会导致任务中断。常见的断点有几类上下文窗口满了、某条命令执行失败、你自己想中途插一句话、网络或会话超时。以前遇到这些情况基本就是从零开始或者手动把已经改了一半的代码回滚。这是最让人抓狂的地方——明明已经改了六个文件就差最后两个结果全废。九月的“长任务能暂停接上”针对的就是这个痛点。它允许你在任务执行到一半时暂停保留当前进度和上下文之后再从断点继续。3.2 暂停续接的实际操作与边界具体怎么用我的操作路径是这样的任务跑到一半我意识到有个前提没交代清楚或者想先看看它改了什么再决定要不要继续这时候触发暂停。暂停后当前已经完成的改动是保留的会话的上下文也还在。我可以先检查改动、补充说明然后让它接着干。这里有几个边界必须说清楚不然容易踩坑暂停不是“存档”。它保留的是当前会话的状态不是把整个任务冻结成一个文件。如果你关掉终端、重启机器这个暂停状态大概率就没了。所以别把它当成可以跨天续接的存档功能。暂停期间不要大改项目文件。因为续接时模型依赖的是暂停那一刻的文件状态认知你在外面手动改了文件它续接时可能基于旧认知操作导致冲突。我踩过一次暂停后我手动改了个配置文件续接时它又按老样子改了一遍把我的改动覆盖了。续接后的第一句话很关键。别直接说“继续”最好带上“刚才改到哪了、接下来做什么”。比如“刚才已经把 A 和 B 改完了现在继续处理 C注意 C 依赖 B 的新接口”。这样能显著降低它跑偏的概率。3.3 把大任务拆成可暂停的段落其实比起“暂停续接”这个功能本身我更想聊的是怎么设计任务让它天然适合暂停。我的经验是别把一个大任务一次性丢进去而是拆成几个有明确边界的阶段。比如重构一个模块我会拆成先让它读代码、输出改造方案这一步不写代码我确认方案后让它改核心逻辑改完我验证再让它改调用方最后跑测试。每个阶段之间就是一个天然的暂停点。这样做的好处是即使没有暂停功能我也能控制节奏。有了暂停功能只是让这个节奏更顺滑。工具是辅助任务拆解才是根本。我见过太多人指望一个功能解决所有问题结果发现工具再好任务描述一塌糊涂照样跑不通。注意长任务续接时如果中间涉及数据库迁移、依赖安装这类有副作用的操作务必确认它没有重复执行。我遇到过一次续接后它把已经跑过的迁移又跑了一遍虽然那次没出事但吓出一身冷汗。4. 插件从“能装”到“能管”的进化4.1 插件管理到底管的是什么“插件从能装到能管”这句话外行看可能觉得没啥。但用过早期版本的人知道那时候装插件基本是“装完就忘”——你不知道装了哪些、哪个在生效、版本是多少、怎么卸载。项目一多插件状态就乱成一锅粥。“能管”意味着有了清单、状态、启停、版本这几个维度的管理能力。你可以看到当前装了哪些插件、每个插件是启用还是禁用、版本号是多少。这听起来是基础功能但对日常使用体验的提升是巨大的。我举个真实场景。我有几个项目一个用某插件做特定格式的检查另一个项目不需要。以前我没法精细控制只能全局装或者全局不装。现在可以按项目维度管理A 项目启用、B 项目禁用互不干扰。4.2 插件冲突与排查思路插件一多冲突就来了。这是所有插件化系统的通病Claude Code 也不例外。我遇到过两类典型冲突第一类是功能重叠。两个插件都想在文件保存时做格式化结果互相打架格式化结果来回横跳。排查方法是先禁用所有插件确认基础功能正常然后逐个启用看哪个启用后出问题。这是最笨但最有效的方法二分法也行但插件数量不多时逐个试更快。第二类是版本不兼容。某个插件依赖的接口在新版本里变了插件没跟上就会报错或者静默失效。这种问题的特征是功能时好时坏或者报一些看不懂的错。排查时先看插件版本再看它最近有没有更新。我整理了一个简单的排查表实际用下来挺顺手现象可能原因排查动作格式化结果来回变两个插件功能重叠禁用其中一个观察是否恢复插件静默失效版本不兼容检查插件版本与主程序版本启动变慢插件过多或某插件卡住逐个禁用定位耗时插件报错但功能正常插件内部警告看日志判断是否影响使用4.3 我给自己定的插件使用纪律用得久了我给自己定了几条纪律分享出来供参考能不装就不装。每多一个插件就多一个变量出问题时排查成本翻倍。只装真正高频使用的。装之前先想清楚卸载路径。如果一个插件我不知道怎么干净卸载我就不装。有些插件装的时候很爽卸载时留一堆残留配置很烦。按项目隔离。全局插件只留最通用的项目特定的插件放在项目维度管理。定期清理。每个月过一遍插件清单把一个月没用过的禁掉或卸掉。这几条听起来像废话但真正做到的人不多。我见过太多人插件装了几十个最后自己都不知道哪个在起作用出了问题只能全部重装。5. 把这些更新串起来看一个更稳的工作流5.1 从“单次对话”到“可持续项目协作”单独看这三个更新都是功能点。但串起来看它们指向同一个方向Claude Code 正在从“单次对话工具”变成“可持续的项目协作伙伴”。AGENTS.md 解决的是“它懂不懂我的项目”长任务暂停续接解决的是“它能不能陪我干完一件大事”插件管理解决的是“我能不能稳定地定制它的行为”。这三件事合起来就是一个可持续工作流的基础。我现在的日常流程大概是这样项目根目录放好 AGENTS.md把项目规范固化下来遇到大任务拆成阶段用暂停续接控制节奏插件按项目隔离保持环境干净。这套流程跑下来最大的感受是可预测性变强了。以前用 AI 编码工具最怕的就是“这次能跑通下次不知道行不行”。现在至少环境是稳定的行为是可预期的。5.2 几个我反复踩到的坑和对应做法最后集中说几个坑都是我在实际使用中反复遇到的文档里基本不会写坑一AGENTS.md 写了但没生效。最常见的原因是文件位置不对或者会话是在文件创建之前启动的。做法确认文件在项目根目录或当前工作目录改完后开新会话。坑二长任务续接后跑偏。原因是续接时上下文有损耗模型对“刚才干了啥”的记忆不完整。做法续接时用一句话复述进度和下一步别只说“继续”。坑三插件装了但行为没变。可能是插件没启用也可能是插件和当前项目不匹配。做法先确认启用状态再看插件是否支持当前场景。坑四多个上下文文件打架。根目录和子目录的约定冲突时行为可能不符合预期。做法子目录文件只写差异并显式声明继承根目录。坑五把暂停当存档。关掉终端后暂停状态丢失白等一场。做法重要节点手动记录进度别完全依赖暂停功能。这些坑的共同点是都不是功能本身的 bug而是使用方式的问题。工具越强大使用方式对结果的影响就越大。这也是为什么我一直觉得与其追新功能不如先把基础用法吃透。5.3 关于要不要迁移到 AGENTS.md 的建议最后回答一个高频问题我现在的 CLAUDE.md 要不要改成 AGENTS.md我的建议是如果你只用 Claude Code 一个工具不急CLAUDE.md 继续用没问题。但如果你同时用多个 AI 编码工具或者预计未来会换工具那值得把通用部分迁到 AGENTS.md。迁移成本不高就是把项目规范那部分复制过去专属部分留在 CLAUDE.md。我自己的做法是渐进式的新项目直接用 AGENTS.md老项目保持 CLAUDE.md 不动等哪天有空了再迁。没必要为了迁而迁工具是为人服务的不是反过来。这套东西我用了几个月最大的体会是AI 编码工具的上限很大程度上取决于你给它的上下文质量。AGENTS.md 也好插件管理也好本质都是在提升上下文的质量和稳定性。功能会不断更新但这个底层逻辑不会变。把项目规范写清楚、把任务拆明白、把环境管干净这三件事做到位工具换哪个都能用得顺。