1. 这次九月更新到底改了什么从“能用”到“好用”的分水岭九月份这波 Claude Code 的更新我第一时间在自己的主力开发机上跑了一遍。说实话之前我对它的定位一直是“终端里能聊两句的编码助手”但这次更新之后它开始有点“正经项目协作工具”的样子了。核心变化集中在三块AGENTS.md 被正式认了、长任务支持暂停和恢复、插件从“能装”进化到“能管”。这三个点单独看都不算炸裂但叠在一起意味着你可以把它塞进一个真实的、跨天甚至跨周的开发流程里而不是每次打开都从零开始。先给不太熟悉的朋友补个背景。Claude Code 是 Anthropic 推出的命令行编码代理工具跑在终端里能读写你本地的代码文件、执行命令、跑测试、提交 git。它和那种“在 IDE 里补全一行代码”的插件不是一回事更像是一个能自己动手干活的结对程序员。你给它一个任务它会自己规划步骤、翻文件、改代码、跑验证遇到问题还会自己调整。之前它的痛点很明显上下文一长就飘、任务中断就得重来、插件生态基本靠手动折腾。九月的更新基本就是冲着这三个痛点去的。这次更新最值得说的是它终于把AGENTS.md这个约定俗成的文件纳入了官方识别范围。在此之前社区里很多人已经在用 AGENTS.md 来给各种编码代理写“项目说明书”了但 Claude Code 官方只认 CLAUDE.md。现在两个都认而且有优先级规则。这意味着你团队里如果同时用多种编码工具可以共用一份 AGENTS.md不用再为每个工具维护一份重复的配置。对于我这种同时折腾好几个代理工具的人来说这一条直接省掉了一半的维护成本。长任务暂停恢复这个功能我愿称之为“跨天开发的救命稻草”。以前跑一个重构任务如果中途要开会或者下班只能让它跑完或者直接 CtrlC第二天重新描述一遍需求。现在可以主动暂停会话状态和任务进度都保留着回来接着干。这个改动看起来小但它把 Claude Code 的使用场景从“一次性会话”扩展到了“持续性项目协作”。插件管理这块之前装插件基本靠手动改配置文件、手动拉仓库装完了也不知道怎么禁用、怎么更新、怎么排查冲突。现在有了统一的插件管理命令能装、能列、能禁、能删还能看每个插件贡献了哪些命令和代理。这对于团队协作场景特别重要——你可以在项目文档里写清楚“本项目需要这几个插件”新人 clone 下来照着装就行不用再口口相传。提示这次更新后建议你先把 Claude Code 升级到最新版本然后检查一下项目根目录下有没有 AGENTS.md 或 CLAUDE.md。如果两个都有需要理解它们的优先级关系否则可能出现配置不生效的情况。适合谁来参考这篇梳理如果你是刚接触 Claude Code 的新手这篇会帮你理清这次更新后哪些旧教程已经过时、哪些新能力值得优先掌握。如果你已经在项目里用它干活那 AGENTS.md 的优先级规则、长任务恢复的边界条件、插件管理的实操细节都是你接下来一周内会用到的内容。下面我按“设计思路—核心细节—实操过程—问题排查”的顺序把这次更新拆开讲。2. AGENTS.md 被正式认了多工具共存的配置方案2.1 为什么是 AGENTS.md 而不是继续只用 CLAUDE.mdClaude Code 最早只认 CLAUDE.md这个文件相当于给代理看的“项目 README”——里面写项目结构、编码规范、常用命令、注意事项。代理每次启动时会读这个文件把它作为系统提示的一部分。但问题是现在编码代理工具不止一个每个工具都想要自己的配置文件。你项目里可能同时有 CLAUDE.md、.cursorrules、copilot-instructions.md内容大量重复改一处就得同步好几处。AGENTS.md 这个约定最早是社区推起来的目标是做一个“跨工具的代理说明书”。它的格式很简单就是 Markdown没有强制 schema工具自己决定怎么解析。Claude Code 这次认了 AGENTS.md等于承认了“项目里可能不止我一个代理工具”这个现实。对于团队来说你可以把通用的项目说明写在 AGENTS.md 里把 Claude Code 特有的配置写在 CLAUDE.md 里两者互补而不是互斥。我实测下来的优先级规则是这样的CLAUDE.md 优先于 AGENTS.md。如果两个文件都存在Claude Code 会先读 CLAUDE.md再读 AGENTS.md后者作为补充。如果同一个配置项在两个文件里都出现了CLAUDE.md 里的生效。这个规则很合理——通用配置放 AGENTS.md工具特有配置放 CLAUDE.md覆盖关系清晰。2.2 AGENTS.md 里到底该写什么一份可直接抄的模板很多人第一次写 AGENTS.md 会写成“项目介绍”这是不对的。代理不需要你告诉它“这是一个电商系统”它需要的是“改代码时要注意什么”。我总结了一个模板你可以直接拿去改# AGENTS.md ## 项目结构 - src/ 源码目录按功能模块划分 - tests/ 测试目录与 src 结构镜像 - scripts/ 构建和部署脚本 ## 编码规范 - 使用 TypeScript strict 模式 - 组件文件使用 PascalCase工具函数使用 camelCase - 禁止使用 any必要时用 unknown 加类型守卫 ## 常用命令 - 安装依赖pnpm install - 跑测试pnpm test -- --watchfalse - 类型检查pnpm typecheck - 本地启动pnpm dev ## 注意事项 - 修改数据库 schema 后必须跑 pnpm db:generate - 不要直接改 generated/ 目录下的文件那是自动生成的 - 提交前必须跑 pnpm lint 和 pnpm typecheck这份模板的核心逻辑是告诉代理“怎么在这个项目里干活”而不是“这个项目是干什么的”。项目背景可以写但要放在后面而且只写和编码决策相关的部分。比如“这是一个面向企业的 SaaS 产品”这种信息对代理改代码帮助不大“这个项目所有 API 调用都要走src/lib/api-client.ts里的封装”这种信息才是代理真正需要的。2.3 多工具共存时的配置分层策略如果你团队里同时用 Claude Code 和其他编码代理我建议这样分层文件内容范围维护者AGENTS.md项目结构、编码规范、常用命令、通用注意事项团队共同维护CLAUDE.mdClaude Code 特有的代理配置、插件依赖、权限设置使用 Claude Code 的成员维护.cursorrulesCursor 特有的规则使用 Cursor 的成员维护这样分层的好处是通用规范只写一遍工具特有配置各自维护不会互相污染。我见过有的团队把三个文件写成三份几乎一样的内容改一个规范要同步三个地方最后必然出现不一致。分层之后AGENTS.md 是唯一事实来源工具特有文件只写差异部分。注意AGENTS.md 的解析是大小写敏感的必须是全大写AGENTS.md。我踩过一次坑写成了agents.md结果代理完全没读到排查了半小时才发现是文件名问题。2.4 实操心得AGENTS.md 的更新时机和粒度AGENTS.md 不是写完就一劳永逸的。我的经验是每次代理犯了一个“本不该犯的错”就往 AGENTS.md 里加一条规则。比如它某次直接改了自动生成的文件我就在“注意事项”里加一条“不要改 generated/ 目录”。它某次用了错误的测试命令我就把正确的命令写进“常用命令”。粒度上规则要具体到可执行。写“注意代码质量”没用写“所有导出函数必须有 JSDoc 注释”才有用。写“小心数据库操作”没用写“数据库迁移必须通过pnpm db:migrate不要手动改 schema 文件”才有用。代理不像人它不会“领会精神”只会按字面执行。所以规则越具体效果越好。另外AGENTS.md 不要写太长。我见过有人写了 500 行结果代理每次启动都要读一遍既浪费上下文窗口又容易让关键规则被淹没。我的建议是控制在 100 行以内只写最高频、最关键的规则。低频规则可以放到 CLAUDE.md 或者项目文档里需要时再让代理去读。3. 长任务暂停与恢复跨天开发的正确姿势3.1 这个功能解决了什么真实痛点在讲怎么用之前先说清楚它解决的是什么问题。Claude Code 跑长任务时比如“把这个模块从 JavaScript 迁移到 TypeScript”它可能会跑十几分钟甚至更久。这期间你要么盯着它跑完要么中断了重来。中断的代价很大——你得重新描述需求它得重新读文件、重新规划步骤之前跑过的分析全白费。更麻烦的是跨天场景。比如你下午五点开始跑一个重构任务跑到六点还没完但你要下班了。以前只能让它继续跑万一跑出问题没人管或者中断了明天重来。现在可以暂停会话状态保留第二天接着跑。这个改动把 Claude Code 从“一次性工具”变成了“可持续协作的代理”。我实测下来暂停恢复的边界条件是这样的暂停时会保留对话历史、任务进度、已读文件列表但不会保留正在执行的命令的中间状态。也就是说如果它正在跑一个测试命令暂停时那个命令会被终止恢复后需要重新跑。但任务的整体规划、已经改过的文件、已经分析过的结论都会保留。3.2 暂停和恢复的具体操作步骤操作本身很简单但有几个细节要注意。暂停的触发方式是在对话中输入暂停指令Claude Code 会完成当前正在执行的原子操作比如正在写的一个文件然后保存状态并退出。恢复时重新启动 Claude Code它会提示你有一个未完成的任务问你是否继续。具体步骤在 Claude Code 对话中输入暂停指令等待它确认“任务已暂停”确认当前正在改的文件已经保存Claude Code 会自己处理但建议你 git status 看一眼正常退出终端第二天重新进入项目目录启动 Claude Code它会显示上次的任务摘要和进度输入继续指令即可恢复恢复后我建议先让它复述一下当前进度和下一步计划确认它没有“失忆”。我遇到过几次恢复后它把已经改过的文件又改了一遍的情况虽然不常见但检查一下更稳妥。3.3 什么任务适合暂停什么任务不适合不是所有任务都适合暂停恢复。我总结了一个判断标准任务类型是否适合暂停原因大规模重构适合任务周期长进度可保存恢复后能接着干批量文件修改适合已改文件列表会保留不会重复改长时间测试运行不适合命令中间状态不保留恢复后要重跑交互式调试不适合依赖实时反馈暂停后上下文断裂代码审查适合分析结论会保留恢复后继续审核心判断标准是任务的进度是否可以用“已完成的步骤列表”来描述。如果是就适合暂停如果任务的进度依赖于某个正在运行的进程的实时状态就不适合。3.4 实操心得暂停前的检查清单踩过几次坑之后我养成了一个习惯暂停前跑一遍检查清单。确认 git 工作区状态未提交的改动心里有数确认没有正在跑的数据库迁移或部署命令确认 AGENTS.md 和 CLAUDE.md 没有未保存的改动如果任务涉及多个仓库确认每个仓库的状态这个清单看起来啰嗦但能避免恢复后出现“文件状态不一致”的问题。我有一次暂停时没注意有个文件改了一半恢复后代理想接着改结果基于的是半成品状态改出来的东西是错的。后来我就在暂停前让它先“完成当前文件的修改”确保没有半成品。提示暂停恢复功能依赖于 Claude Code 的会话存储目录。如果你换了机器或者清了缓存目录恢复会失败。跨机器恢复目前不支持别指望在公司暂停、回家恢复。4. 插件管理从手动折腾到统一命令4.1 插件系统这次到底改了什么之前的插件系统说实话用起来像半成品。装插件要手动 clone 仓库到指定目录然后在配置文件里手写路径。装完了不知道装了什么想禁用得手动改配置想更新得手动 pull。团队协作时新人根本不知道项目依赖哪些插件全靠老人口头传授。这次更新后有了统一的插件管理命令。能装、能列、能禁、能删还能看每个插件的详情——它贡献了哪些命令、哪些代理、哪些钩子。这个改动看起来是“体验优化”实际上是“从玩具到工具”的质变。因为插件是 Claude Code 扩展能力的主要方式插件管理不成熟整个生态就起不来。我实测下来插件管理的核心命令有这么几个安装插件、列出已装插件、查看插件详情、禁用插件、卸载插件。每个命令都有明确的输出告诉你操作结果。安装时它会自动处理依赖卸载时会清理相关配置。这个体验比之前手动折腾强太多了。4.2 插件安装的完整流程和注意事项安装一个插件的标准流程是这样的先搜索或确认插件来源确保是可信的执行安装命令指定插件标识查看安装输出确认没有报错用列表命令确认插件已装查看插件详情了解它贡献了哪些能力在项目里实际用一下确认功能正常注意事项有几个。第一插件来源要可信。插件能执行命令、读写文件权限很大装来路不明的插件风险很高。第二装完要重启会话。有些插件的命令和代理是在会话启动时注册的装完不重启可能不生效。第三注意插件冲突。如果两个插件注册了同名的命令后装的会覆盖先装的或者直接报冲突。装完新插件后如果发现某个旧命令行为变了先查是不是插件冲突。我踩过的一个坑是装了一个插件后它注册了一个和内置命令同名的命令结果内置命令被覆盖了行为完全不对。排查了半天才发现是插件冲突。后来我养成了习惯装完插件先列一下它贡献的命令看看有没有和现有命令重名的。4.3 团队协作场景下的插件管理策略团队里用 Claude Code插件管理不能各装各的。我的建议是项目级插件依赖写进 CLAUDE.md个人级插件自己管。项目级插件是指“这个项目干活必须用的插件”比如某个框架专用的代码生成插件、某个内部工具的集成插件。这些插件的清单应该写进 CLAUDE.md新人 clone 项目后照着装。个人级插件是指“我自己习惯用的插件”比如某个快捷键增强、某个输出格式化插件这些不用写进项目文档自己装就行。CLAUDE.md 里的插件清单可以这样写## 插件依赖 本项目需要以下 Claude Code 插件 - plugin-name-a用于生成 API 客户端代码 - plugin-name-b用于跑集成测试 安装命令 \\\bash claude plugin install plugin-name-a claude plugin install plugin-name-b \\\这样新人进来照着文档装一遍就行不用再问“这个项目要装什么插件”。团队里如果有人装了额外的个人插件导致行为不一致排查时也有个基准——先确认项目级插件都装对了再看个人插件的影响。4.4 插件排查装完不生效怎么办插件装完不生效是最常见的问题。我整理了一个排查顺序现象可能原因排查方法命令找不到插件没装成功用列表命令确认插件在列命令行为不对插件冲突查看插件详情检查命令重名插件时灵时不灵会话没重启重启 Claude Code 会话插件报权限错误插件需要额外授权查看插件文档确认权限要求插件加载报错插件版本不兼容查看插件详情里的版本要求排查的核心思路是先确认插件装没装再确认插件加没加载最后确认插件功能有没有被覆盖。大部分问题出在第一步和第三步。装没装用列表命令一看便知加没加载看会话启动时的日志功能被覆盖看命令列表有没有重名。注意卸载插件时它注册的命令和代理会被移除但它改过的文件不会自动恢复。如果插件在项目里生成过文件卸载后那些文件还在需要手动清理。我建议卸载插件前先 git status 看一眼确认没有插件生成的文件需要处理。5. 常见问题与排查技巧实录5.1 AGENTS.md 不生效的几种情况和排查方法AGENTS.md 不生效我遇到过三种情况。第一种是文件名不对写成了agents.md或Agents.mdClaude Code 只认全大写。第二种是文件位置不对AGENTS.md 必须放在项目根目录放在子目录里不会被自动读取。第三种是优先级问题CLAUDE.md 里有一条冲突的配置覆盖了 AGENTS.md 里的配置。排查顺序先确认文件名全大写再确认在项目根目录最后检查 CLAUDE.md 有没有冲突配置。如果三个都没问题可以在会话里直接问 Claude Code“你读到了哪些项目配置文件”它会列出实际读取的文件列表一看便知。5.2 长任务恢复后“失忆”的应对策略恢复后“失忆”表现为不记得之前改过什么、重复改已经改过的文件、忘记之前的决策。这种情况不常见但一旦出现很浪费时间。我的应对策略是恢复后先让它复述进度如果发现失忆不要让它继续干而是手动把关键信息重新喂给它。具体做法是把上次的任务摘要、已改文件列表、关键决策点整理成一段话发给它让它基于这个重新规划。虽然麻烦但比让它基于错误状态继续干要强。预防措施是暂停前让它生成一份任务进度摘要保存到文件里恢复时先读这个文件。5.3 插件冲突的识别和解决插件冲突的典型表现是某个命令行为突然变了、某个功能时灵时不灵、会话启动时报错。识别方法是禁用最近装的插件看问题是否消失。如果消失就是新插件冲突如果不消失继续禁用其他插件直到定位到冲突源。解决冲突的方式有两种一是卸载冲突插件换一个功能类似但不冲突的二是如果冲突插件必须用联系插件作者看能不能改命令名。我一般优先选第一种因为改插件命令名涉及改插件源码维护成本高。5.4 版本升级后的配置迁移检查清单每次 Claude Code 大版本升级后我都会跑一遍配置迁移检查确认 AGENTS.md 和 CLAUDE.md 的优先级规则有没有变确认已装插件是否兼容新版本确认长任务的会话存储格式有没有变影响恢复确认常用命令有没有改名或改参数确认权限设置有没有新增默认限制这个清单能避免“升级完发现某个功能不能用了排查半天发现是配置格式变了”的情况。升级前跑一遍升级后跑一遍心里有数。5.5 我踩过的三个真实坑和解决过程第一个坑AGENTS.md 写太长代理启动变慢。我一开始把项目文档全塞进 AGENTS.md写了 400 多行结果每次启动都要读很久而且关键规则被淹没。后来精简到 80 行只留最高频的规则启动速度和规则遵守率都上去了。第二个坑长任务暂停后恢复时发现 git 工作区有未提交改动代理基于改动后的状态继续干结果改出了不一致的代码。后来我养成了暂停前先 commit 或 stash 的习惯确保恢复时工作区是干净的。第三个坑装了一个插件后内置的某个命令行为变了排查了两小时才发现是插件覆盖了同名命令。后来我装完插件第一件事就是列命令检查有没有重名。这三个坑的共同教训是Claude Code 的配置和插件都是有状态的状态不一致就会出问题。保持状态干净、可追溯比事后排查省时间得多。6. 把这次更新用起来的几个实操建议如果你刚升级完我建议按这个顺序把新能力用起来。第一步在项目根目录建一个 AGENTS.md把项目结构、编码规范、常用命令写进去控制在 100 行以内。第二步跑一个中等规模的重构任务中途暂停一次第二天恢复体验一下长任务恢复的流程确认你的使用场景适不适合。第三步整理项目级插件清单写进 CLAUDE.md让团队新人能照着装。这三步做完你对这次更新的核心能力就有体感了。剩下的细节比如插件冲突排查、AGENTS.md 粒度调整可以在实际使用中慢慢磨。我自己的体会是这次更新最大的价值不是某个单点功能而是把 Claude Code 从一个“会话式工具”变成了一个“有状态的项目协作代理”。状态能保存、配置能分层、插件能管理这三件事加起来才让它真正能进团队工作流。最后分享一个小技巧如果你同时用多个编码代理工具把通用规范写在 AGENTS.md 里然后给每个工具写一个薄薄的适配文件只写差异部分。这样改规范只改一处工具适配各自维护长期来看维护成本最低。我这么用了两个月切换工具时几乎无感项目规范始终一致。