1. 这次九月更新到底改了什么从“能用”到“好用”的分水岭九月份这波 Claude Code 的更新我第一时间在自己的主力开发机上跑了一遍。说实话之前我对它的定位一直是“终端里能聊两句的编码助手”但这次更新之后它开始有点“正经工程工具”的样子了。核心变化就三件事认了 AGENTS.md、长任务能暂停接上、插件从能装变成能管。这三个点单看都不算炸裂但凑在一起意味着 Claude Code 正在从“玩具”往“工作流基础设施”靠。先给不太熟悉的朋友补个背景。Claude Code 是 Anthropic 推出的命令行编码代理工具你可以理解成一个住在终端里的 AI 搭档能读你的项目文件、执行命令、改代码、跑测试。它跟那种网页里复制粘贴的聊天机器人不一样它是直接操作你本地仓库的。之前大家用它的痛点很集中项目级的规则文件到底该叫什么、长任务跑到一半断了怎么办、插件装了一堆但根本管不过来。这次九月更新基本就是冲着这三个痛点来的。我为什么这么关注这次更新因为我自己的工作流里Claude Code 已经承担了相当一部分重复性编码和重构任务。之前每次开新项目我都要手动把规则文件复制来复制去长任务跑到一半网络抖一下就得重来插件装完就忘了自己装过啥。这些问题看着小但累积起来特别消耗耐心。这次更新之后我实测下来至少前两个问题基本被解决了第三个问题也有了明确的管理入口。这篇文章我会按“为什么这么设计、具体怎么用、我踩过哪些坑”这个顺序来拆。不管你是刚听说 Claude Code 想入门还是已经用了一阵子但没系统梳理过应该都能从里面找到能直接抄作业的东西。我会尽量把每个配置项、每个命令都写清楚让你看完就能在自己机器上复现。2. AGENTS.md 被正式认下项目规则文件终于有了统一入口2.1 为什么是 AGENTS.md 而不是继续用 CLAUDE.md这次更新里我觉得最有意思的一个变化就是 Claude Code 开始正式识别AGENTS.md这个文件。之前社区里其实一直有个混乱有人用 CLAUDE.md有人用 .claude/ 目录下的配置还有人干脆把规则写在 README 里。每个工具都有自己的偏好导致同一个项目里可能躺着三四个不同名字的规则文件维护起来特别烦。AGENTS.md 这个命名其实不是 Anthropic 独创的它是社区里逐渐形成的一个约定。你可以把它理解成“给 AI 代理看的 README”。它的核心价值在于跨工具通用——不管你是用 Claude Code、还是别的编码代理工具只要大家都认这个文件名项目规则就只需要维护一份。这次 Claude Code 认下 AGENTS.md等于官方表态支持这个约定这对整个生态是好事。那 CLAUDE.md 怎么办我实测下来Claude Code 目前是两者都认的。它会优先读 AGENTS.md如果没有再去找 CLAUDE.md。所以如果你之前已经写了一堆 CLAUDE.md不用急着改它还能用。但如果你是新项目我建议直接上 AGENTS.md理由很简单以后换工具不用重写。提示AGENTS.md 和 CLAUDE.md 同时存在时AGENTS.md 优先级更高。如果你发现规则没生效先检查是不是两个文件冲突了。2.2 AGENTS.md 里到底该写什么我的实战模板很多人第一次写 AGENTS.md 会犯一个错把它当成项目文档来写恨不得把整个架构都塞进去。这是不对的。AGENTS.md 的核心受众是 AI 代理它需要的是可执行的约束和上下文不是给人看的说明书。我自己的 AGENTS.md 一般包含这几块项目一句话定位让代理知道这是个什么项目比如“这是一个基于 FastAPI 的后端服务数据库用 PostgreSQL”。代码风格硬约束比如“所有函数必须带类型注解”“禁止使用 print统一用 logging”“缩进用 4 空格”。目录结构说明告诉它哪些目录是源码、哪些是测试、哪些是生成产物不要动。常用命令测试怎么跑、lint 怎么跑、本地怎么启动。禁区哪些文件绝对不能改比如迁移脚本、生产配置。我举个实际的例子。我有个项目用的是 monorepo 结构之前 Claude Code 老是跑去改 node_modules 里的东西后来我在 AGENTS.md 里加了一行“禁止修改 node_modules、dist、.next 目录下的任何文件”这个问题就再没出现过。这就是 AGENTS.md 的价值——把口头约定变成硬规则。# AGENTS.md 示例 ## 项目定位 这是一个 Next.js 14 的前端项目使用 App Router样式用 Tailwind。 ## 代码规范 - 组件一律用函数式禁止 class 组件 - 所有 props 必须定义 TypeScript 类型 - 禁止在组件里直接写 fetch统一走 lib/api.ts 封装 ## 目录说明 - app/ 路由和页面 - components/ 可复用组件 - lib/ 工具函数和 API 封装 - public/ 静态资源 ## 常用命令 - 开发npm run dev - 测试npm run test - 类型检查npm run typecheck ## 禁区 - 不要修改 next.config.js - 不要动 .env 文件 - 不要改 package-lock.json这个模板我用了大概两个月实测下来 Claude Code 的“跑偏率”明显下降。以前它经常自作主张改配置现在基本会老老实实待在业务代码里。2.3 多层级 AGENTS.md 的加载逻辑与优先级这次更新还有一个细节值得说Claude Code 支持多层级 AGENTS.md。什么意思呢你可以在项目根目录放一个在子目录里再放一个它会按层级叠加。这个设计其实很符合 monorepo 的需求。我实测的加载顺序是这样的从当前工作目录往上找先找到最近的 AGENTS.md然后继续往上直到根目录。子目录的规则会覆盖父目录的同名规则。举个例子根目录的 AGENTS.md 说“缩进用 4 空格”但 frontend/ 子目录的 AGENTS.md 说“缩进用 2 空格”那在 frontend 里操作时就会用 2 空格。这个机制特别适合那种前后端混在一个仓库的项目。后端用 Python 要 4 空格前端用 JS 要 2 空格以前只能写一个含糊的规则现在可以分层写清楚。我踩过的一个坑是子目录的 AGENTS.md 如果写得太细会覆盖掉父目录的一些通用规则导致代理在子目录里“忘了”全局约束。所以我的建议是子目录的 AGENTS.md 只写差异部分通用规则还是放根目录。层级文件位置作用范围建议内容根级/AGENTS.md全仓库通用规范、禁区、常用命令模块级/frontend/AGENTS.md前端模块前端特有规范、框架约定子模块级/frontend/admin/AGENTS.md管理后台该子模块的专属约束3. 长任务暂停与恢复终于不用从头再来了3.1 长任务为什么会断先搞清楚问题根源在讲怎么用之前我得先说清楚长任务为什么会断。Claude Code 执行一个复杂任务时比如“重构整个认证模块”它需要多轮对话、多次工具调用、多次文件读写。这个过程可能持续十几分钟甚至更久。断的原因主要有三类第一类是网络波动。这个最常见尤其是你在网络环境不太稳定的时候请求超时就直接中断了。第二类是上下文超限。任务跑太久对话历史越来越长超过模型的上下文窗口就得截断截断之后代理就“失忆”了。第三类是人为中断。比如你临时要改个紧急 bug或者下班了想明天接着跑。之前这三种情况处理方式都一样重来。这就很崩溃尤其是那种跑了半小时的任务重来一次成本太高。这次更新引入的暂停恢复机制本质上是把任务的中间状态持久化下来让你能从断点接着跑。3.2 暂停恢复的实际操作怎么存、怎么接我实测下来Claude Code 的暂停恢复是通过会话状态保存实现的。当你中断一个任务时它会把当前的对话上下文、已完成的步骤、待办事项都存到一个本地状态文件里。下次你回来可以用恢复命令接着跑。具体操作上我一般这么用任务跑到一半需要中断时不要直接 CtrlC 硬杀而是用它的暂停指令通常是输入特定命令或按特定快捷键让它优雅地保存状态。确认状态保存成功后再退出。下次回来用恢复命令加载上次的会话它会告诉你“上次跑到哪了、还剩什么没做”。你可以选择继续也可以先调整一下方向再继续。这里有个关键点恢复的不只是对话还有任务进度。它会记住“已经改了哪几个文件、跑了哪些测试、哪些还没做”。这个比单纯的对话历史恢复有用得多因为长任务的核心价值就是进度不是聊天记录。注意暂停恢复依赖本地状态文件如果你换了机器或者清了缓存目录状态就没了。所以重要任务建议在固定机器上跑。3.3 长任务拆解策略让暂停恢复真正发挥作用光有暂停恢复还不够你得配合任务拆解才能发挥最大价值。我的经验是一个长任务最好拆成若干个“可独立验证”的阶段。每个阶段结束后即使中断了恢复起来也清晰。举个例子我要重构一个用户模块我会这么拆阶段一梳理现有代码输出重构方案不写代码阶段二改数据模型和迁移脚本阶段三改业务逻辑层阶段四改 API 层阶段五补测试阶段六跑全量测试并修复每个阶段都是一个自然的暂停点。我可以在阶段二结束后暂停第二天从阶段三接着跑。这样即使状态文件丢了我也知道该从哪继续不至于完全抓瞎。我踩过的一个坑是把任务拆得太粗一个阶段里塞了太多东西结果中断后恢复代理自己也搞不清跑到哪了。后来我学乖了每个阶段控制在“能在 10 分钟内完成”的粒度这样暂停恢复的体验最顺。任务粒度恢复体验推荐度整个大任务不拆恢复后容易迷失方向不推荐拆成 3-5 个大阶段恢复后基本清晰推荐拆成 10 小步骤恢复精准但管理成本高视情况4. 插件管理从“装完就忘”到“心里有数”4.1 插件系统这次到底管了什么之前 Claude Code 的插件系统说实话有点“野生”。你能装插件但装完之后呢列表在哪看怎么禁用怎么更新怎么知道某个插件到底干了啥这些都不太清楚。这次更新把插件管理补上了核心是给了你一个统一的查看和控制入口。我实测下来现在你能做的事包括列出已安装插件、查看每个插件的状态和来源、启用/禁用某个插件、移除不用的插件。这些操作看着基础但之前就是缺。没有这些插件装多了就是一团乱麻你甚至不知道哪个插件在拖慢启动速度。插件这个东西的价值在于扩展能力边界。比如有的插件能让 Claude Code 接入特定的代码检查工具有的能对接项目管理系统的 API有的能加自定义命令。但前提是你得管得住它们不然就是给自己挖坑。4.2 插件的安装、启用与禁用实操我拿一个实际场景来说。假设我想让 Claude Code 在提交代码前自动跑一遍 lint这可以通过一个插件来实现。安装流程大概是找到插件的来源通常是一个仓库地址或包名。用安装命令装上。装完后用列表命令确认它出现在已安装列表里。检查它的状态是不是“启用”。如果暂时不想用可以禁用它而不是卸载这样配置还在。这里我要强调一个经验插件不要一次装太多。我一开始图新鲜装了七八个插件结果启动变慢而且有些插件之间还会冲突。后来我精简到三个核心插件体验立刻好了。插件管理的意义不只是“能管”更是让你有意识地去做减法。提示禁用和卸载是两回事。禁用保留配置随时能开卸载会清掉配置。不确定要不要长期用的先禁用。4.3 插件冲突与性能问题的排查思路插件装多了最容易出的问题就是冲突。表现通常是某个功能突然不工作了、启动报错、或者代理行为变得奇怪。我遇到过一次装了两个都声称能增强文件搜索的插件结果搜索功能直接挂了。排查过程是这样的第一步禁用所有插件确认基础功能正常。如果禁用后正常说明问题出在插件。第二步逐个启用每启用一个测一次定位到具体是哪个插件的问题。第三步如果两个插件单独用都正常、一起用就冲突那就是它们之间有重叠功能二选一即可。性能问题也类似。如果你感觉 Claude Code 变慢了可以先看插件列表把不常用的禁用掉再测启动速度。我实测下来每多一个插件启动大概多几百毫秒装十个就是好几秒这个体感还是很明显的。问题表现可能原因排查动作功能突然失效插件冲突禁用全部后逐个启用启动变慢插件过多精简到核心插件报错信息奇怪插件版本不兼容检查插件更新或移除代理行为异常插件注入的规则冲突查看插件文档确认行为5. 把这些更新串起来我的一天工作流实录5.1 早上开工用 AGENTS.md 快速进入状态我现在的习惯是早上到工位第一件事打开终端进项目目录让 Claude Code 先读一遍 AGENTS.md然后问它“今天这个项目有什么待办”。因为 AGENTS.md 里写了项目定位和常用命令它能很快给出一个有上下文的回答而不是泛泛而谈。这个流程的好处是省去了重复交代背景的时间。以前我每次都要跟它说“这是个什么项目、用什么技术栈、注意什么”现在这些都在 AGENTS.md 里它自己读就行。我实测下来每天至少省 5 到 10 分钟的“热身对话”。5.2 白天干活长任务暂停恢复的真实使用白天我一般会安排一到两个长任务比如“把这个模块的测试覆盖率提到 80%”。这种任务跑起来可能要一两个小时。中间我可能要开会、要处理别的事这时候暂停恢复就派上用场了。我的做法是开会前暂停开完会恢复接着跑。恢复后它会告诉我“已经补了 12 个测试还剩 5 个函数没覆盖”我就能接着往下推。这个体验比之前“要么跑完要么重来”好太多了。尤其是那种需要反复调试的任务暂停恢复几乎是刚需。5.3 收尾复盘插件帮我做了哪些自动化下班前我会花几分钟看看今天插件帮我做了哪些事。比如 lint 插件自动拦了几次格式问题、搜索插件帮我快速定位了几处代码。这个复盘不是为了炫耀而是为了判断哪些插件值得留、哪些可以砍。用不上的插件就是负担该禁就禁。我个人的体会是工具的价值不在于功能多而在于跟你工作流的契合度。Claude Code 这次更新三个点都踩在了“让工具更贴合真实工作流”上。AGENTS.md 解决了上下文传递暂停恢复解决了长任务连续性插件管理解决了能力扩展的可控性。这三件事凑齐了它才算真正能进我的日常工具箱。6. 常见问题速查我踩过的坑和对应的解法6.1 AGENTS.md 不生效怎么办这是问得最多的。我总结了几种情况一是文件名拼错了必须是全大写 AGENTS.md不能是 agents.md 或 Agents.md。二是位置不对它得在项目根目录或者你当前工作目录的上级链路上。三是和 CLAUDE.md 冲突了两个文件同时存在时以 AGENTS.md 为准如果你改的是 CLAUDE.md 但没生效就是这个原因。四是格式问题AGENTS.md 是 Markdown但不要用太复杂的嵌套简单的标题加列表最稳。6.2 长任务恢复后“失忆”了恢复后如果发现它不记得之前干了啥通常是状态文件没存全。可能的原因中断方式太粗暴直接杀进程、状态文件被清理了、或者任务本身超出了上下文限制。我的建议是中断时用优雅暂停别硬杀重要任务别频繁换机器任务拆细一点别让它一口气跑太久。6.3 插件装了但功能没出现先确认插件状态是“启用”而不是“禁用”。然后看插件是不是需要额外配置有些插件装完还要填 API key 或者指定路径。再就是看插件是不是跟当前项目类型匹配比如一个专门给 Python 用的插件在 JS 项目里自然不生效。最后重启一下 Claude Code有些插件需要重启才加载。问题最可能的原因快速解法AGENTS.md 不生效文件名或位置错误检查全大写和根目录恢复后失忆状态未完整保存用优雅暂停拆细任务插件功能不出现未启用或未配置检查状态和配置项启动变慢插件过多禁用非核心插件规则冲突多层级文件覆盖子目录只写差异6.4 关于 CLAUDE.md 还要不要留我的建议是新项目直接上 AGENTS.md老项目如果 CLAUDE.md 写得好好的不用急着迁移它还能用。但如果你打算长期用多个工具早点迁到 AGENTS.md 更省心。迁移也简单改个文件名再检查一下内容里有没有工具特定的写法就行。7. 我对这次更新的一点个人看法用了一个月下来我最大的感受是Claude Code 这次更新没有堆花哨的功能而是老老实实补基础。AGENTS.md 是补“上下文标准化”暂停恢复是补“任务连续性”插件管理是补“扩展可控性”。这三样都是工程工具该有的基本功之前缺了现在补上了。如果你还没升级我建议尽快升。如果你刚入门我建议先从 AGENTS.md 写起把项目规则理清楚再慢慢试长任务和插件。工具这东西用顺了是助力用不顺是负担关键还是找到跟自己工作流契合的那个点。我目前的状态是Claude Code 已经成了我终端里的常驻搭档这次更新之后这个搭档明显更靠谱了。