1. 九月这波更新到底更新了什么Claude Code 在九月的这波更新说实话没有那种“憋个大招”的震撼感但如果你一直在用会发现每个改动都踩在痛点上。我把三个核心变化先摆出来项目级指令文件 AGENTS.md 从社区提议转正成为官方标准、长任务支持暂停后无缝接续、插件系统从“能装”进化到“能管”。这三个变化分别对应了三个不同层面的问题。AGENTS.md 解决的是“模型怎么理解你的项目”的问题以前你只能依赖 CLAUDE.md 里写的那点东西模型对项目结构的感知非常有限长任务暂停恢复解决的是“跑了几小时的任务不敢中断”的问题尤其是那种要跑上下文压缩、批量重构或者长链路 Agent 调用的场景插件系统则是把原来“装上去能跑就行”的状态变成了有目录、有配置、有版本管理的正式体系。如果你还没升级直接在终端跑一下claude --version确认版本号。九月这批能力对应的版本基本都集中在 1.0.x 系列建议拉到当前最新版再往下看。旧版本会有功能缺失尤其插件管理那块老版本连入口都没有。这篇文章不会逐行翻译官方 changelog我只会挑我认为真正影响日常使用的改动结合我自己在真实项目里跑过的场景来聊。适合谁看已经装了 Claude Code 但没吃透新特性的用户以及正在纠结要不要从 Cursor 或者其他 Agent 工具迁移过来的人。2. AGENTS.md 转正项目指令文件终于有了官方标准2.1 先搞清楚它和 CLAUDE.md 的分工很多人的第一反应是又来一个配置文件和 CLAUDE.md 什么关系这里有个很容易误解的点。CLAUDE.md 可以理解成“给 Claude 的全局备忘录”你可以在里面写通用的偏好、语气、输出格式这些内容。而 AGENTS.md 是“给所有 Agent 看的项目说明书”它更多关注的是代码仓库本身的结构、构建命令、测试方式、代码规范这类项目级信息。我实测下来的建议是全局习惯放 CLAUDE.md项目事实放 AGENTS.md。比如你习惯让 Claude 输出中文注释、遵守某种提交信息格式这是你的个人偏好放全局配置而“这个仓库是 monorepo前端在 packages/web后端在 services/api测试用 vitest 跑”这类客观事实放 AGENTS.md。为什么这么分因为 AGENTS.md 的设计初衷就是让不同的 AI 编码工具都能读同一份项目说明。官方在更新说明里也明确了一点这文件不是 Claude Code 独有的它是为了兼容更多 Agent 工具而定的规范。你以后切换到别的工具这份文件照样能用不会浪费你写的内容。2.2 目录层级继承规则每个目录都可以有 AGENTS.md这次更新最重要的一个机制是嵌套继承。Claude Code 在加载项目上下文时会从项目根目录开始向下逐级读取每个目录下的 AGENTS.md然后把它们拼接起来。这就意味着你可以把通用的项目规范放在根目录把某个子模块的特殊规则放在对应子目录里。举个例子一个 monorepo 仓库根目录 AGENTS.md 写“整体架构说明、根级构建脚本怎么跑”而packages/ui下如果放一个 AGENTS.md里面只写“UI 组件库的开发规范、样式约定、Storybook 的启动方式”。当你在packages/ui里让 Claude 改代码它就会同时读到根目录和子目录两份 AGENTS.md自动合并上下文。这个继承机制的价值在于“就近原则”。以前所有东西都堆在 CLAUDE.md 里写到后面文件越来越长模型处理时还要过滤无关信息。嵌套之后Claude 读到的内容更精准指令冲突的概率也大大降低。子目录的规则如果和根目录冲突以更靠近当前工作目录的那份为准规则很简单不需要纠结。2.3 落盘实测一份可以直接抄的 AGENTS.md 模板写 AGENTS.md 的时候要注意别把它当成散文集模型是按“指令”来解析的不是按“阅读理解”来消化的。我自己的习惯是用短句、列表和明确的动词开头比如“运行”“不要”“必须”这类。下面这个模板是我目前在几个仓库里使用的你可以直接拿来改# 项目说明 这是一个基于 Next.js 14 tRPC Prisma 的全栈应用。 - 前端代码在 src/app服务端代码在 src/server共享类型在 src/shared。 - 数据库 Schema 由 Prisma 管理修改后必须执行 npx prisma generate。 - 所有 API 接口必须通过 tRPC Router 暴露禁止直接写 REST 路由。 ## 常用命令 - 开发环境pnpm dev - 跑测试pnpm test单元测试 / pnpm test:e2e端到端 - 构建pnpm build ## 代码规范 - 组件使用函数式写法 Hooks禁止使用 Class 组件。 - 状态管理只用 zustand不要新引入 redux。 - 样式方案是 Tailwind CSS Modules禁止写全局样式覆盖。 - 所有涉及数据库查询的代码必须经过 src/server 下的 service 层禁止直接在组件里调用 Prisma。 ## 注意事项 - 修改 Prisma Schema 后除了生成客户端还要同步更新 src/shared 里的 DB 类型定义。 - 测试环境数据库与开发环境隔离跑 e2e 前先确认本地环境变量指向的是测试库。 - 这个仓库没有 ESLint 配置不要运行 lint 相关的修复指令有问题直接问。这样写的好处是每一行都是可执行的指令模型拿到之后能直接映射到操作上而不是要在散文里自己抽取出“应该怎么做”。还有一个小细节命令类的说明尽量给出完整命令不要只写“安装依赖”四个字要写pnpm install模型才能真正执行对你想要的操作。3. 长任务暂停与恢复再也不用守着终端不敢动了3.1 暂停关键路径CtrlC 和 Esc 的双层语义长任务暂停恢复是我这一个月用得最频繁的新功能。以前跑一个多步骤重构中间想停下来看看中间产物基本只能硬跑完或者直接终止然后从头再来。现在不一样了中断任务变成了一种可控的操作。先说语义。终端里按一次 CtrlCClaude Code 不是直接杀死进程而是给你弹出一个中断菜单上面有“暂停任务”和“终止任务”两个选项。选暂停当前的任务状态会被保留下来包括已经执行的步骤、当前的工作目录、上下文窗口里加载的消息历史全部记录下来。选终止那就是彻底停掉。Esc 键的行为稍微不同它走的是另一个逻辑把当前正在执行的工具调用打断但保留对话历史。这个区别很重要如果你只是发现模型的某个工具调用卡住了比如一个 grep 扫了太久按 Esc 打断这个动作就好如果你是整段任务要中场休息那按 CtrlC 再选暂停才是正确路径。我实测过一个场景一个跨 20 多个文件的类型重构任务跑到第 14 个文件时我发现中间有个类型定义想先确认一下。按 CtrlC 暂停然后我去翻代码、确认类型设计大概过了十分钟回到终端输入继续指令它从第 15 个文件接着跑之前已经改完的 14 个文件没有重复操作。3.2 恢复任务的三种姿势continue、resume 和 --from恢复任务这块有三个入口分别对应不同场景我把它们理清楚。第一个是直接claude --continue。这个命令会加载最近一次会话的完整上下文然后继续执行。适合你刚暂停完马上就想接着跑的官方推荐路径。执行后会重新进入交互模式但上下文已经恢复。第二个是claude --resume后面可以跟会话 ID也可以不跟进入列表选择。这个适合你关掉终端之后隔了一段时间回来或者同时挂了多个会话想精确选择某一个。它会列出历史会话你选一个恢复上下文完整加载。第三个是--from参数这是我最看好的一个能力。它允许你指定从某一个特定的历史消息节点继续而不是一定从最后一条消息开始。比如你跑一个长任务中间第 30 轮消息产生了某个关键决策你后来发现决策错了直接claude --from定位到那一轮重新从这个节点开始往外走。这就相当于给任务增加了“分支回溯”能力不用把整个任务推倒重来。3.3 长任务调优参数会话恢复 ID 和压缩阈值除了交互层面的操作这次更新还补了几个和长任务强相关的参数藏在启动配置里。一个是会话恢复 ID 机制现在每个会话都有稳定的标识符配合脚本使用很方便。我自己有个脚本会在任务结束后自动把会话 ID 写入一个日志文件需要追溯的时候直接用--resume id拉起来不用在列表里翻。另一个是上下文压缩阈值调整。默认情况下上下文窗口快满时模型会自动做摘要压缩但压缩策略可以配置。参数在~/.claude/settings.json里调相关键是contextCompression你可以控制触发压缩的消息量阈值以及压缩时保留原始消息的轮数。这个参数调整的实际价值在于长任务跑到后期模型对早期步骤的“记忆”会逐渐模糊。如果你跑的任务前后依赖很强比如前面定义的类型后面要用可以把保留轮数调大牺牲一点 token 占用来换取记忆完整性。反过来如果任务步骤相对独立那默认配置就够用不需要额外调整。4. 插件系统升级从手工装包到目录化管理4.1 老方案的痛点手工 clone 和 symlink 的尴尬九月的插件更新对用过老方案的人来说简直是一种解放。老方案怎么装插件先git clone插件仓库然后手动在配置文件里加路径或者做 symlink 把插件目录链接到 Claude Code 的插件目录。这套流程第一次跑没问题但当你装了四五个插件之后管理就是一团乱麻不知道哪个插件在哪、版本是什么、Enable 状态是什么全靠人脑记。现在的插件管理走的是正式目录体系。插件市场有统一的目录索引claude plugin命令下加了add、remove、list、update这几个子命令。装插件变成一条命令的事它在市场目录里搜索、解析依赖、写入配置然后list能直接看到已安装的插件列表和版本状态。我比较喜欢的一个细节是 dry-run 模式执行claude plugin add之前可以先跑一轮检查命令会告诉你“这个插件要写哪些配置、会依赖哪些其他插件、版本是否兼容”确认没问题再真正执行安装。避免装完插件才发现冲突或者版本不对然后又要去手动清理。4.2 目录结构和配置文件插件化开发的骨架插件管理最重要的是目录结构理顺了。现在配置关系大概是这样的~/.claude/ ├── plugins/ │ ├── market.json # 插件市场配置 │ ├── installed/ │ │ ├── plugin-a/ # 已安装插件 A │ │ └── plugin-b/ # 已安装插件 B │ └── plugin-config.json # 插件启停和版本锁定配置 └── settings.json # 全局设置plugin-config.json是核心它记录每个插件的版本、启用状态、配置项。你要禁用某个插件直接改这个文件的enabled字段就行不需要去移动任何目录。版本锁定也在这里如果你担心自动更新会破坏现有工作流可以把版本号固定住和 npm 的锁文件思路一致。有一点要注意插件市场里的东西质量参差不齐装第三方插件之前最好先看一眼它声明需要的权限。老手可能不会觉得这是个事但新手很容易踩坑装了个看起来人畜无害的插件结果它要求“读取所有文件内容”的权限这就要谨慎考虑了。4.3 插件配置的完整流程从搜索到锁版本我做一次完整的插件安装大概是这么操作的。先在交互模式里输入/plugin这里会直接进入插件管理界面列表展示当前已安装的插件以及可操作的选项。如果要搜索市场里的新插件走claude plugin的子命令claude plugin search --query 数据库搜索结果会列出插件名、简介、版本号、下载量这些元信息。筛选之后执行安装claude plugin add vendor/plugin-name安装过程会显示每一步动作下载、解析依赖、写入配置。装完之后再执行claude plugin list确认状态已安装插件 vendor/plugin-name v1.2.3 enabled community/plugin-x v0.9.1 enabled如果你要在团队里统一插件版本锁版本的操作是这样的先看一下当前插件目录里实际的版本然后在配置里手动更新版本号并设置locked: true。这样即使插件市场推送了新版本你的环境也不会跟着变。4.4 插件开发起步编写自己的第一个插件如果你不满足于只是装别人的插件官方这次也把开发入口理顺了。插件就是一个包含了plugin.json清单文件的目录里面声明插件名、版本、入口文件、声明的权限以及暴露给 Claude 的工具列表。开发调试的流程是在项目里建好插件目录通过claude plugin add /path/to/your/plugin以本地路径方式安装然后直接在会话里调用插件暴露的工具测试效果。这个本地调试模式不会把你的插件发布到市场纯粹是自用。我建议有动手能力的人可以尝试把日常重复的小动作插件化。比如我团队里有个插件自动在每次代码变更后生成变更摘要并写入指定的文档文件。原来这个是靠 prompt 手写一遍描述现在变成插件工具可靠性稳定了很多。插件化真正的价值不是省一次打字而是把流程固定下来不依赖每次对话的状态。5. 常见问题排查实录这五类坑我基本都踩过5.1 “your organization has disabled Claude subscription access” 报错这个报错最近碰到的人不少字面上的意思是“你的组织已禁用 Claude 订阅访问”。遇到这个先别慌绝大多数情况下不是你的账号被封了。先检查是不是自己开了多个工作区或者通过特殊渠道导入的订阅配置然后查看~/.claude/settings.json里是否残留了旧的组织标识配置。清理掉旧的配置退出重新登录账号这个问题通常就能解决。另外如果是团队环境让管理员确认一下组织策略里是否允许成员使用 Claude Code 接入这个权限在后台控制台是可以单独开关的。5.2 AGENTS.md 写了但没生效这个问题的经典原因是你把文件放在了错误的位置或者文件命名不对。注意文件名是AGENTS.md全大写开头。放在根目录是全局生效放进子目录是只在该目录范围生效。如果你不确定当前作用域在会话里直接问 Claude “你读到了哪些 AGENTS.md 文件”它会列出实际加载的内容。还有一种情况是大小写混用了在 Windows 或 macOS 默认文件系统下大小写不敏感可能看不出来但一旦 git 仓库在 Linux 环境下检出agents.md和AGENTS.md会被当作两个文件。保持全大写命名省事。5.3 暂停恢复之后上下文错乱恢复任务之后发现模型“失忆”了或者是上下文顺序不对这个大概率是压缩阈值设置过小导致的。任务跑得长上下文被压缩早期细节被摘要替代恢复之后模型自然只能依靠摘要来“回忆”。如果任务对细节敏感在启动任务之前就把contextCompression的保留轮数调大。另外恢复时指定--from节点也会影响记忆范围从更靠后的消息节点恢复会保留更多上下文。5.4 插件安装成功但调用报 Not Found插件装了但调用时报工具不存在先确认插件是否处于 enabled 状态claude plugin list如果状态是 disabled执行启用命令。还有一种可能是你开了多个 Claude Code 会话旧会话没有重新加载插件配置。退出所有会话重新进入插件工具才会被加载到这次会话里。5.5 第三方模型接入后的行为差异很多人在用 cc-switch 这类工具接入 DeepSeek、Qwen、GLM 等第三方模型时发现插件系统的行为表现和官方模型不一致。这个现象是正常的插件工具调用依赖模型对 function calling 的支持程度不同模型的基础能力不一样尤其是复杂的多工具编排场景开源模型表现会弱一些。建议在切换模型之后先跑一个最小化的工具调用测试确认基础链路通了再上复杂任务。6. 一点个人实战体会用了这一整个月的更新回想起来最大的感受是Claude Code 这个工具的定位在悄然变化。它不再是一个单纯“帮你写代码”的命令行助手而是慢慢变成一个可编排、可恢复、可扩展的 Agent 运行环境。AGENTS.md 让项目知识的传递变得标准化暂停恢复让长任务变得可管理插件系统让能力边界可以按需扩展。我个人最常用的是这组组合项目根目录放一份覆盖全仓库的 AGENTS.md在每个关键子模块里再放一份局部规则然后跑任务之前先确认长任务的参数配置没问题任务中需要中断就大胆暂停不需要像以前一样守着终端不敢动。插件只装真正用得上的少装多调保持环境干净排查问题也容易。最后再分享一个小技巧每次任务结束之后把会话 ID 记下来配合下次--resume使用你会发现“上次那个改动当时是怎么想的”这个问题的答案变得非常好查。这算是这波更新里最不起眼但最实用的一个细节了。
Claude Code九月更新：AGENTS.md转正、长任务恢复与插件系统实战
1. 九月这波更新到底更新了什么Claude Code 在九月的这波更新说实话没有那种“憋个大招”的震撼感但如果你一直在用会发现每个改动都踩在痛点上。我把三个核心变化先摆出来项目级指令文件 AGENTS.md 从社区提议转正成为官方标准、长任务支持暂停后无缝接续、插件系统从“能装”进化到“能管”。这三个变化分别对应了三个不同层面的问题。AGENTS.md 解决的是“模型怎么理解你的项目”的问题以前你只能依赖 CLAUDE.md 里写的那点东西模型对项目结构的感知非常有限长任务暂停恢复解决的是“跑了几小时的任务不敢中断”的问题尤其是那种要跑上下文压缩、批量重构或者长链路 Agent 调用的场景插件系统则是把原来“装上去能跑就行”的状态变成了有目录、有配置、有版本管理的正式体系。如果你还没升级直接在终端跑一下claude --version确认版本号。九月这批能力对应的版本基本都集中在 1.0.x 系列建议拉到当前最新版再往下看。旧版本会有功能缺失尤其插件管理那块老版本连入口都没有。这篇文章不会逐行翻译官方 changelog我只会挑我认为真正影响日常使用的改动结合我自己在真实项目里跑过的场景来聊。适合谁看已经装了 Claude Code 但没吃透新特性的用户以及正在纠结要不要从 Cursor 或者其他 Agent 工具迁移过来的人。2. AGENTS.md 转正项目指令文件终于有了官方标准2.1 先搞清楚它和 CLAUDE.md 的分工很多人的第一反应是又来一个配置文件和 CLAUDE.md 什么关系这里有个很容易误解的点。CLAUDE.md 可以理解成“给 Claude 的全局备忘录”你可以在里面写通用的偏好、语气、输出格式这些内容。而 AGENTS.md 是“给所有 Agent 看的项目说明书”它更多关注的是代码仓库本身的结构、构建命令、测试方式、代码规范这类项目级信息。我实测下来的建议是全局习惯放 CLAUDE.md项目事实放 AGENTS.md。比如你习惯让 Claude 输出中文注释、遵守某种提交信息格式这是你的个人偏好放全局配置而“这个仓库是 monorepo前端在 packages/web后端在 services/api测试用 vitest 跑”这类客观事实放 AGENTS.md。为什么这么分因为 AGENTS.md 的设计初衷就是让不同的 AI 编码工具都能读同一份项目说明。官方在更新说明里也明确了一点这文件不是 Claude Code 独有的它是为了兼容更多 Agent 工具而定的规范。你以后切换到别的工具这份文件照样能用不会浪费你写的内容。2.2 目录层级继承规则每个目录都可以有 AGENTS.md这次更新最重要的一个机制是嵌套继承。Claude Code 在加载项目上下文时会从项目根目录开始向下逐级读取每个目录下的 AGENTS.md然后把它们拼接起来。这就意味着你可以把通用的项目规范放在根目录把某个子模块的特殊规则放在对应子目录里。举个例子一个 monorepo 仓库根目录 AGENTS.md 写“整体架构说明、根级构建脚本怎么跑”而packages/ui下如果放一个 AGENTS.md里面只写“UI 组件库的开发规范、样式约定、Storybook 的启动方式”。当你在packages/ui里让 Claude 改代码它就会同时读到根目录和子目录两份 AGENTS.md自动合并上下文。这个继承机制的价值在于“就近原则”。以前所有东西都堆在 CLAUDE.md 里写到后面文件越来越长模型处理时还要过滤无关信息。嵌套之后Claude 读到的内容更精准指令冲突的概率也大大降低。子目录的规则如果和根目录冲突以更靠近当前工作目录的那份为准规则很简单不需要纠结。2.3 落盘实测一份可以直接抄的 AGENTS.md 模板写 AGENTS.md 的时候要注意别把它当成散文集模型是按“指令”来解析的不是按“阅读理解”来消化的。我自己的习惯是用短句、列表和明确的动词开头比如“运行”“不要”“必须”这类。下面这个模板是我目前在几个仓库里使用的你可以直接拿来改# 项目说明 这是一个基于 Next.js 14 tRPC Prisma 的全栈应用。 - 前端代码在 src/app服务端代码在 src/server共享类型在 src/shared。 - 数据库 Schema 由 Prisma 管理修改后必须执行 npx prisma generate。 - 所有 API 接口必须通过 tRPC Router 暴露禁止直接写 REST 路由。 ## 常用命令 - 开发环境pnpm dev - 跑测试pnpm test单元测试 / pnpm test:e2e端到端 - 构建pnpm build ## 代码规范 - 组件使用函数式写法 Hooks禁止使用 Class 组件。 - 状态管理只用 zustand不要新引入 redux。 - 样式方案是 Tailwind CSS Modules禁止写全局样式覆盖。 - 所有涉及数据库查询的代码必须经过 src/server 下的 service 层禁止直接在组件里调用 Prisma。 ## 注意事项 - 修改 Prisma Schema 后除了生成客户端还要同步更新 src/shared 里的 DB 类型定义。 - 测试环境数据库与开发环境隔离跑 e2e 前先确认本地环境变量指向的是测试库。 - 这个仓库没有 ESLint 配置不要运行 lint 相关的修复指令有问题直接问。这样写的好处是每一行都是可执行的指令模型拿到之后能直接映射到操作上而不是要在散文里自己抽取出“应该怎么做”。还有一个小细节命令类的说明尽量给出完整命令不要只写“安装依赖”四个字要写pnpm install模型才能真正执行对你想要的操作。3. 长任务暂停与恢复再也不用守着终端不敢动了3.1 暂停关键路径CtrlC 和 Esc 的双层语义长任务暂停恢复是我这一个月用得最频繁的新功能。以前跑一个多步骤重构中间想停下来看看中间产物基本只能硬跑完或者直接终止然后从头再来。现在不一样了中断任务变成了一种可控的操作。先说语义。终端里按一次 CtrlCClaude Code 不是直接杀死进程而是给你弹出一个中断菜单上面有“暂停任务”和“终止任务”两个选项。选暂停当前的任务状态会被保留下来包括已经执行的步骤、当前的工作目录、上下文窗口里加载的消息历史全部记录下来。选终止那就是彻底停掉。Esc 键的行为稍微不同它走的是另一个逻辑把当前正在执行的工具调用打断但保留对话历史。这个区别很重要如果你只是发现模型的某个工具调用卡住了比如一个 grep 扫了太久按 Esc 打断这个动作就好如果你是整段任务要中场休息那按 CtrlC 再选暂停才是正确路径。我实测过一个场景一个跨 20 多个文件的类型重构任务跑到第 14 个文件时我发现中间有个类型定义想先确认一下。按 CtrlC 暂停然后我去翻代码、确认类型设计大概过了十分钟回到终端输入继续指令它从第 15 个文件接着跑之前已经改完的 14 个文件没有重复操作。3.2 恢复任务的三种姿势continue、resume 和 --from恢复任务这块有三个入口分别对应不同场景我把它们理清楚。第一个是直接claude --continue。这个命令会加载最近一次会话的完整上下文然后继续执行。适合你刚暂停完马上就想接着跑的官方推荐路径。执行后会重新进入交互模式但上下文已经恢复。第二个是claude --resume后面可以跟会话 ID也可以不跟进入列表选择。这个适合你关掉终端之后隔了一段时间回来或者同时挂了多个会话想精确选择某一个。它会列出历史会话你选一个恢复上下文完整加载。第三个是--from参数这是我最看好的一个能力。它允许你指定从某一个特定的历史消息节点继续而不是一定从最后一条消息开始。比如你跑一个长任务中间第 30 轮消息产生了某个关键决策你后来发现决策错了直接claude --from定位到那一轮重新从这个节点开始往外走。这就相当于给任务增加了“分支回溯”能力不用把整个任务推倒重来。3.3 长任务调优参数会话恢复 ID 和压缩阈值除了交互层面的操作这次更新还补了几个和长任务强相关的参数藏在启动配置里。一个是会话恢复 ID 机制现在每个会话都有稳定的标识符配合脚本使用很方便。我自己有个脚本会在任务结束后自动把会话 ID 写入一个日志文件需要追溯的时候直接用--resume id拉起来不用在列表里翻。另一个是上下文压缩阈值调整。默认情况下上下文窗口快满时模型会自动做摘要压缩但压缩策略可以配置。参数在~/.claude/settings.json里调相关键是contextCompression你可以控制触发压缩的消息量阈值以及压缩时保留原始消息的轮数。这个参数调整的实际价值在于长任务跑到后期模型对早期步骤的“记忆”会逐渐模糊。如果你跑的任务前后依赖很强比如前面定义的类型后面要用可以把保留轮数调大牺牲一点 token 占用来换取记忆完整性。反过来如果任务步骤相对独立那默认配置就够用不需要额外调整。4. 插件系统升级从手工装包到目录化管理4.1 老方案的痛点手工 clone 和 symlink 的尴尬九月的插件更新对用过老方案的人来说简直是一种解放。老方案怎么装插件先git clone插件仓库然后手动在配置文件里加路径或者做 symlink 把插件目录链接到 Claude Code 的插件目录。这套流程第一次跑没问题但当你装了四五个插件之后管理就是一团乱麻不知道哪个插件在哪、版本是什么、Enable 状态是什么全靠人脑记。现在的插件管理走的是正式目录体系。插件市场有统一的目录索引claude plugin命令下加了add、remove、list、update这几个子命令。装插件变成一条命令的事它在市场目录里搜索、解析依赖、写入配置然后list能直接看到已安装的插件列表和版本状态。我比较喜欢的一个细节是 dry-run 模式执行claude plugin add之前可以先跑一轮检查命令会告诉你“这个插件要写哪些配置、会依赖哪些其他插件、版本是否兼容”确认没问题再真正执行安装。避免装完插件才发现冲突或者版本不对然后又要去手动清理。4.2 目录结构和配置文件插件化开发的骨架插件管理最重要的是目录结构理顺了。现在配置关系大概是这样的~/.claude/ ├── plugins/ │ ├── market.json # 插件市场配置 │ ├── installed/ │ │ ├── plugin-a/ # 已安装插件 A │ │ └── plugin-b/ # 已安装插件 B │ └── plugin-config.json # 插件启停和版本锁定配置 └── settings.json # 全局设置plugin-config.json是核心它记录每个插件的版本、启用状态、配置项。你要禁用某个插件直接改这个文件的enabled字段就行不需要去移动任何目录。版本锁定也在这里如果你担心自动更新会破坏现有工作流可以把版本号固定住和 npm 的锁文件思路一致。有一点要注意插件市场里的东西质量参差不齐装第三方插件之前最好先看一眼它声明需要的权限。老手可能不会觉得这是个事但新手很容易踩坑装了个看起来人畜无害的插件结果它要求“读取所有文件内容”的权限这就要谨慎考虑了。4.3 插件配置的完整流程从搜索到锁版本我做一次完整的插件安装大概是这么操作的。先在交互模式里输入/plugin这里会直接进入插件管理界面列表展示当前已安装的插件以及可操作的选项。如果要搜索市场里的新插件走claude plugin的子命令claude plugin search --query 数据库搜索结果会列出插件名、简介、版本号、下载量这些元信息。筛选之后执行安装claude plugin add vendor/plugin-name安装过程会显示每一步动作下载、解析依赖、写入配置。装完之后再执行claude plugin list确认状态已安装插件 vendor/plugin-name v1.2.3 enabled community/plugin-x v0.9.1 enabled如果你要在团队里统一插件版本锁版本的操作是这样的先看一下当前插件目录里实际的版本然后在配置里手动更新版本号并设置locked: true。这样即使插件市场推送了新版本你的环境也不会跟着变。4.4 插件开发起步编写自己的第一个插件如果你不满足于只是装别人的插件官方这次也把开发入口理顺了。插件就是一个包含了plugin.json清单文件的目录里面声明插件名、版本、入口文件、声明的权限以及暴露给 Claude 的工具列表。开发调试的流程是在项目里建好插件目录通过claude plugin add /path/to/your/plugin以本地路径方式安装然后直接在会话里调用插件暴露的工具测试效果。这个本地调试模式不会把你的插件发布到市场纯粹是自用。我建议有动手能力的人可以尝试把日常重复的小动作插件化。比如我团队里有个插件自动在每次代码变更后生成变更摘要并写入指定的文档文件。原来这个是靠 prompt 手写一遍描述现在变成插件工具可靠性稳定了很多。插件化真正的价值不是省一次打字而是把流程固定下来不依赖每次对话的状态。5. 常见问题排查实录这五类坑我基本都踩过5.1 “your organization has disabled Claude subscription access” 报错这个报错最近碰到的人不少字面上的意思是“你的组织已禁用 Claude 订阅访问”。遇到这个先别慌绝大多数情况下不是你的账号被封了。先检查是不是自己开了多个工作区或者通过特殊渠道导入的订阅配置然后查看~/.claude/settings.json里是否残留了旧的组织标识配置。清理掉旧的配置退出重新登录账号这个问题通常就能解决。另外如果是团队环境让管理员确认一下组织策略里是否允许成员使用 Claude Code 接入这个权限在后台控制台是可以单独开关的。5.2 AGENTS.md 写了但没生效这个问题的经典原因是你把文件放在了错误的位置或者文件命名不对。注意文件名是AGENTS.md全大写开头。放在根目录是全局生效放进子目录是只在该目录范围生效。如果你不确定当前作用域在会话里直接问 Claude “你读到了哪些 AGENTS.md 文件”它会列出实际加载的内容。还有一种情况是大小写混用了在 Windows 或 macOS 默认文件系统下大小写不敏感可能看不出来但一旦 git 仓库在 Linux 环境下检出agents.md和AGENTS.md会被当作两个文件。保持全大写命名省事。5.3 暂停恢复之后上下文错乱恢复任务之后发现模型“失忆”了或者是上下文顺序不对这个大概率是压缩阈值设置过小导致的。任务跑得长上下文被压缩早期细节被摘要替代恢复之后模型自然只能依靠摘要来“回忆”。如果任务对细节敏感在启动任务之前就把contextCompression的保留轮数调大。另外恢复时指定--from节点也会影响记忆范围从更靠后的消息节点恢复会保留更多上下文。5.4 插件安装成功但调用报 Not Found插件装了但调用时报工具不存在先确认插件是否处于 enabled 状态claude plugin list如果状态是 disabled执行启用命令。还有一种可能是你开了多个 Claude Code 会话旧会话没有重新加载插件配置。退出所有会话重新进入插件工具才会被加载到这次会话里。5.5 第三方模型接入后的行为差异很多人在用 cc-switch 这类工具接入 DeepSeek、Qwen、GLM 等第三方模型时发现插件系统的行为表现和官方模型不一致。这个现象是正常的插件工具调用依赖模型对 function calling 的支持程度不同模型的基础能力不一样尤其是复杂的多工具编排场景开源模型表现会弱一些。建议在切换模型之后先跑一个最小化的工具调用测试确认基础链路通了再上复杂任务。6. 一点个人实战体会用了这一整个月的更新回想起来最大的感受是Claude Code 这个工具的定位在悄然变化。它不再是一个单纯“帮你写代码”的命令行助手而是慢慢变成一个可编排、可恢复、可扩展的 Agent 运行环境。AGENTS.md 让项目知识的传递变得标准化暂停恢复让长任务变得可管理插件系统让能力边界可以按需扩展。我个人最常用的是这组组合项目根目录放一份覆盖全仓库的 AGENTS.md在每个关键子模块里再放一份局部规则然后跑任务之前先确认长任务的参数配置没问题任务中需要中断就大胆暂停不需要像以前一样守着终端不敢动。插件只装真正用得上的少装多调保持环境干净排查问题也容易。最后再分享一个小技巧每次任务结束之后把会话 ID 记下来配合下次--resume使用你会发现“上次那个改动当时是怎么想的”这个问题的答案变得非常好查。这算是这波更新里最不起眼但最实用的一个细节了。
