1. 版本更新概览Mods 到底是个什么机制Claude Code 的版本号走到 2.1.287 之后圈子里讨论最多的话题从这周又更新了什么命令变成了Mods 真的能改行为。这次更新确实有点不一样——它不是简单地在原有的 Agent 循环里加几个开关而是正式引入了一套插件体系。你可以把 Mods 理解成 Claude Code 的外挂模块装上去之后工具本身的交互流程、输出格式、命令执行策略都能被改写而不是像以前那样只能被动地在官方留好的配置文件里填参数。先说清楚这个功能解决的是什么问题。Claude Code 本质是一个跑在终端里的 AI 编程代理你给它一个任务它会自己读代码、改文件、执行终端命令、分析报错然后不断迭代直到完成。在 2.1.287 之前想调整它的行为主流做法无非三条路改 CLAUDE.md 项目记忆文件、改 settings.json 里的配置项、或者用 hooks 挂外部脚本。这三条路分别管的是长期记忆运行参数事件回调但都有一个共同的天花板——它们本质上是配置不是扩展。你只能在官方预留的格子里填内容改不了工具自身的交互框架。Mods 的思路是把这个天花板捅破。它允许你以模块化的方式注入自定义逻辑让插件可以影响 Claude Code 在看到什么、决定做什么、怎么执行、怎么汇报这四个环节上的表现。换句话说以前你问怎么让 Claude Code 更听话答案往往是去 CLAUDE.md 里写清楚规则现在你可以直接问怎么给 Claude Code 装一个专门负责某类任务的 Mod然后真的装一个进去。这个版本值得谁关注如果你只是偶尔用 Claude Code 写点小脚本Mods 对你来说属于知道有这回事就行但如果你长期用 Agent 模式跑项目重构、批量改代码、自动化测试修复这类重复性高的活儿或者你维护着多个项目、希望不同项目有完全不同的 Agent 工作风格那 Mods 就是这轮更新里最值得花时间研究的东西。下面的内容我会从机制原理、安装配置、手写 Mod、踩坑实录几个角度完整拆一遍尽量让看完的人能直接上手。2. 行为改造机制解析Mods 为什么能做到改行为2.1 从配置到扩展旧方案的三种手段与天花板在进入 Mods 的细节之前值得先把为什么以前改行为那么费劲这件事讲透。Claude Code 早期版本的行为控制主要依赖下面三样东西CLAUDE.md这是项目级的记忆文件。Claude Code 每次启动会话时都会读取它把它当作最重要的上下文。你可以在里面写项目结构说明、代码规范、禁止事项甚至直接规定改完代码必须跑测试。它管的是Agent 的价值观和长期记忆。settings.json用户级或项目级的配置文件控制模型参数、权限开关、默认行为。比如是否允许自动执行终端命令、超时时间、输出是否带详细日志。它管的是运行参数。Hooks事件回调机制。Claude Code 在执行某些关键动作比如读取文件、执行命令、生成回复前后可以调用外部脚本根据脚本返回值决定是否放行。它管的是流程拦截。这三者的共同问题是它们都是声明式的格子。CLAUDE.md 是给模型读的自然语言文本能不能执行到位取决于模型理解settings.json 是固定字段的 JSON没有的功能就是没有hooks 虽然灵活但它是夹在官方流程里的小程序只负责在特定节点返回允许/禁止/改文本你很难让一个 hook 完整接管某一段对话逻辑。这就导致了一个很实际的痛点你想让 Claude Code 在一些复杂场景下做出结构性改变——比如在生成代码时自动套用某个团队的模板、在回答前先检索项目里的某些文档、或者把多轮任务的结果按特定格式汇总——旧方案要么靠反复写提示词碰运气要么写一堆文件系统和流程相关的胶水代码。Mods 的出现本质上是把填格子升级成装零件。2.2 Mods 的挂载点设计四层注入模型Mods 的核心设计是挂载点Mount Point。你可以把 Claude Code 的 Agent 循环拆成四个阶段上下文收集、意图规划、动作执行、结果呈现。每个阶段都有对应的挂载点Mod 可以指定自己挂在哪一层从而精确地干预行为。以官方文档和社区实践里常见的设计来归纳挂载点大致分四类挂载点干预阶段典型用途context上下文收集自动注入项目信息、读取额外文档、过滤无关文件plan意图规划改写任务拆解策略、调整工具选择优先级action动作执行拦截或改写终端命令、文件编辑、审批流程respond结果呈现定制输出格式、追加摘要、格式化 diff这个设计的妙处在于它跟 hooks 是互补而不是替代。Hooks 是事件触发的外部钩子偏底层、偏拦截Mods 是业务逻辑包可以把多个小行为打包成一个可开关、可卸载的单元。你甚至可以在一个 Mod 内部同时挂到 plan 和 respond 两层让思考和汇报保持一致风格。2.3 Mods 与子代理、hooks 的关系很多人第一次接触 Mods 会把它和 Subagents子代理搞混。这里有个简单的区分方式子代理是另一个独立的 Agent 实体Claude Code 会把一部分任务委派给子代理执行Mods 是寄生在主 Agent 上的行为插件它不作为一个独立实体存在而是直接修改主 Agent 的运行逻辑。两者的关系有点像操作系统的进程和内核模块——子代理像是一个新进程Mods 则像加载进内核的驱动直接影响系统调用行为。至于和 hooks 的关系我在实际使用中的理解是hooks 适合做结构化回调比如命令执行后的验证、文件变更前的安全检查这类逻辑用脚本写更可靠Mods 适合做经验化定制比如让 Agent 在遇到测试失败时先看最近三个 commit 再决定怎么修这种规则用 Mod 写会更贴近自然语言的表达方式。从 2.1.287 开始Claude Code 的插件能力从被动响应变成了主动参与。这也是社区把这次更新称为Claude Code 的插件元年的原因——虽然版本号只是小版本递增但架构层面的意义不小。3. 实操升级到 2.1.287 并装好第一个 Mod3.1 升级与安装两种主路径不管你是新装还是旧版本升级先确认一件事Mods 功能在 2.1.287 版本里才完整可用版本太低连目录都不会生成。如果你之前装过 Claude Code直接在终端里跑一下升级命令就行。官方推荐的安装方式是 npm 包anthropic-ai/claude-code所以在大多数环境里# 升级到最新版本 npm update -g anthropic-ai/claude-code # 确认版本号 claude --version如果你是在 VS Code 里用的 Claude Code 扩展记得把扩展也更新到配套版本。插件市场里的扩展版本和 CLI 版本是绑定的只升级一边可能出现扩展连不上 CLI的问题。我自己在 VS Code 里遇到过几次这种版本错位的问题排查到最后都是两边版本不一致导致的所以升级时尽量同步操作。Ubuntu 这类 Linux 环境下的配置也不复杂需要注意的点主要是 npm 的全局安装路径权限。如果你之前是用 root 装的升级时碰到 EACCES 权限错误大概率是 npm 全局目录的归属问题用npm config get prefix确认目录后把权限处理好再升级。这个坑在 macOS 和 Ubuntu 上我都踩过后面排查实录里会详细说。3.2 初始化 Mods 目录结构装好 2.1.287 之后第一次启动 Claude Code 时会在用户配置目录下生成 Mods 的默认结构。以常见路径来说项目级的 Mods 目录是项目根目录下的.claude/mods/用户级的是~/.claude/mods/。如果你启动后没看到这两个目录可以手动建Claude Code 会自动识别。# 项目级 Mods 目录 mkdir -p .claude/mods # 用户级 Mods 目录所有项目共享 mkdir -p ~/.claude/mods每个 Mod 就是一个独立的子目录目录名建议用 kebab-case 命名比如code-reviewer、commit-message-formatter。Mod 内部需要有一个入口文件通常是mod.md用 Markdown 写行为描述和规则加一个可选的mod.json声明挂载点、版本、依赖。第一次上手我建议先从一个纯 Markdown 描述的 Mod 开始不写任何脚本先感受一下规则注入和以前写 CLAUDE.md 有什么不同。3.3 启停与状态查看Mods 设计了一个很实用的特性按项目开关。CLAUDE.md 是一份全局生效的记忆文件你没法只对某一个项目禁用某段内容Mods 则可以精确到这个项目只启用这几个 Mod。常用操作命令大概是这样的# 查看当前启用的 Mods 列表 claude mods list # 为当前项目启用某个 Mod claude mods enable code-reviewer # 禁用某个 Mod claude mods disable code-reviewer如果是在交互式会话里也可以直接敲斜杠命令比如/mods查看列表/mods enable 名称启用。新版 Claude Code 的命令基本都支持斜杠补全输入一半按 Tab 就能看到候选。这里有一个关键概念要提前说明Mods 的启用和安装是分开的。你把一个 Mod 目录放进.claude/mods/只是安装它默认可能是停用的必须执行 enable 之后才会被加载进 Agent 的上下文。这个设计避免了装了一堆插件结果互相冲突的尴尬也给排查问题留了干净的开关。4. 写一个真正能改行为的 Mod4.1 最小可用 Mod从改输出风格开始我建议任何人第一次写 Mod都从一个改输出风格的小目标入手不要一上来就做复杂拦截。原因很简单输出风格是肉眼可见的变化成功了会有直观正反馈失败了也容易排查。拿我自己写的第一个 Mod 举例目标很简单——让 Claude Code 在每次完成代码修改后用固定的三段式结构汇报改了什么、为什么改、怎么验证。这个 Mod 的入口文件mod.md内容大致如下# 行为规则代码修改汇报 当一次任务涉及修改代码文件时在最终回复中强制使用以下结构 ## 变更摘要 用三到五条要点列出本次改动的文件与改动内容 ## 决策原因 解释每个关键改动的理由引用相关文件作为依据 ## 验证建议 给出具体的测试命令或人工检查步骤 如果任务没有涉及代码修改则忽略本规则。就这么十几行文字放进.claude/mods/report-formatter/mod.md然后执行claude mods enable report-formatter下一次会话里 Claude Code 的输出结构就会改变。你可能会问这和直接在 CLAUDE.md 里写规则有什么区别区别在于作用域和替换方式。CLAUDE.md 里的规则是叠加在系统提示词里的写多了会膨胀而且全项目处处生效Mods 的规则是模块化的可以独立开关也可以被更高优先级的 Mod 替换。4.2 用挂载点声明做执行拦截纯规则类 Mod 适合改输出风格但如果你想改的是执行行为就需要用到挂载点声明了。比如我曾经写过一个 Mod目标是禁止 Claude Code 在未确认的情况下直接执行git push这类有副作用的风险命令。这个 Mod 不能只靠文字规则因为模型可能在长任务推进过程中忽略末尾的约束必须让它在执行动作前被机械地检查一次。这就是挂载点action的用武之地。声明文件mod.json大致长这样{ name: safe-git, version: 1.0.0, mounts: { action: { filter: command, policy: blocklist } } }然后在行为规则文件里把需要确认的命令清单写清楚比如包含git push、git push --force、rm -rf、DROP TABLE之类的模式。当 Claude Code 准备执行终端命令时挂载在 action 层的 Mod 会先检查命令内容命中黑名单就阻止执行并返回一条提示让 Agent 先向用户确认。这个流程本质上和 hooks 的PreToolUse很像差别在于 Mods 把规则描述和执行逻辑分开了——规则用自然语言写挂在哪个环节用配置声明。对不擅长写脚本的人来说这比直接写 hook 脚本友好得多对熟悉 hooks 的人来说Mods 提供了更语义化的封装。4.3 多 Mod 之间的优先级与冲突处理当你的 Mods 数量超过三五个之后一定会遇到冲突问题。我在实际使用中遇到过最典型的场景是一个 Mod 要求所有回复必须简洁另一个 Mod 要求代码修改必须有详细的三段式汇报两条规则打架Claude Code 的输出变得忽长忽短。Mods 机制里对这个问题提供了两种处理手段。第一种是优先级声明通过mod.json里的priority字段设置{ name: report-formatter, priority: 20 }优先级数值越高规则越靠后注入理论上越接近最终决定的位置。默认情况下所有 Mod 的优先级相同按字母序加载。第二种是命名空间隔离。在 mod.md 里用!-- namespace: xxx --注释声明命名空间后Agent 会把不同命名空间的规则当作独立体系来理解减少互相污染。比如代码风格类Mod 和提交流程类Mod 放在不同命名空间就不会在上下文里纠缠不清。说句实在话优先级和命名空间并不能 100% 解决冲突模型面对互斥规则时还是会摇摆。我的经验是宁可少装几个 Mod让每个 Mod 的职责单一明确也不要堆一堆小而全的 Mod。Mods 数量越多上下文越拥挤Agent 的注意力反而会被稀释。4.4 把 Mod 变成真正的插件加脚本逻辑前面讲的 Mod 都偏规则注入。但既然叫插件免不了有人想在里面跑真实逻辑。2.1.287 的 Mods 设计里mod.md 和 mod.json 只是入口Mod 目录里还可以放可执行脚本在挂载点被触发时调用。比如我想写一个提交信息生成器Mod它会在git commit之前运行一个脚本读取暂存区的 diff生成符合 conventional commits 规范的提交信息。这时候我们就要手写一个脚本文件放在 Mod 目录下mods/ └── commit-helper/ ├── mod.md ├── mod.json └── scripts/ └── generate-commit-msg.py脚本本身接收 Claude Code 传过来的 JSON 参数包括原始命令、当前目录、变更文件列表处理完把结果写到输出文件里Claude Code 会读取输出决定是否替换默认行为。这个模式使 Mods 具备了完整的工具链能力——它不再是纯提示词插件而是真正能参与执行流程的插件。5. 常见问题与排查实录5.1 问题速查表这一轮更新带来的新问题主要集中在版本兼容、目录识别和规则生效几个方面。我把实际遇到过的、以及社区里高频出现的问题整理成了一张速查表方便按图索骥。现象可能原因解决方式升级后没有生成 mods 目录版本没升成功或启动时未触发初始化先确认claude --version为 2.1.287再手动mkdir -p .claude/modsenable 提示 Mod 不存在目录层级不对Mod 套娃了检查是否在.claude/mods/下直接放了嘡而不是又包了一层同名目录Mod 规则时灵时不灵多 Mod 优先级冲突或上下文太长被截断查看/mods列表临时禁用其他 Mod 做对照测试自定义脚本没有被调用mod.json 挂载点写错或脚本没有可执行权限核对挂载点名称chmod x后重试升级后 VS Code 扩展报错CLI 和扩展版本不匹配扩展和 npm 包一起升级到最新命令被误拦截action 挂载点黑名单太宽检查匹配规则把模式改精确避免用宽泛后缀匹配5.2 一个典型的排查实录我在 Ubuntu 上配置 Claude Code 并启用第一个 Mod 时遇到过一个很迷惑的问题Mod 文件放在项目.claude/mods/下claude mods list能看到它但怎么 enable 都失败提示Mod not found。目录明明存在内容也完整为什么找不到后来一步步排查发现问题是文件权限。那个项目是从同事的仓库里 clone 下来的.claude目录被 Git 追踪了部分文件的 owner 不是一个用户npm 全局安装的 Claude Code 以另一个用户身份运行时读取目录被拒导致它把整个 Mod 判定为无效。处理方式是给 Mod 目录统一设置权限并顺手在.gitignore里把.claude/排除掉。这个经验提醒我两件事第一Mods 目录默认不该进版本库除非是团队刻意要共享的标准化 Mod第二排查问题先看文件权限和路径别看规则写法——大部分规则没生效都轮不到规则本身出错。还有一个高频问题值得单独说Mod 规则被截断。Claude Code 的上下文窗口有限当项目很大、CLAUDE.md 很长、同时开了七八个 Mod 的时候后面的 Mod 规则很可能根本进不了活跃上下文。这是纯规则型 Mod 的天然短板。我的应对方式是少即是多项目级 Mod 不超过三个超过的部分合并成一个职责更广的 ModCLAUDE.md 里本来就有的内容不要重复写进 Mod减少上下文膨胀。6. 实操心得与几个建议6.1 我踩过的几个坑第一个坑是过度依赖规则而忽视验证。刚上手 Mods 那两天我写了不少必须禁止永远开头的规则以为写进 mod.md 就万事大吉。实际测试发现模型对绝对化词汇的服从度并没有想象的那么高尤其在长任务场景中后置规则很容易被任务上下文挤掉。后来我把关键规则尽量收敛到挂载点上比如必须执行验证这类要求直接挂在 action 层做机械拦截而不是寄希望于模型记到最后。第二个坑是Mod 目录被 Git 追踪。前面已经提过这里再强调一次团队协作项目里每个人本地的 Mod 配置很可能是私有的。把.claude/加进.gitignore是稳妥做法除非你明确要共享某个标准化 Mod那时候应该单独把该 Mod 目录加入例外并配一份使用文档。第三个坑是升级时机。Claude Code 的版本迭代速度很快2.1.287 加了 Mods后面的小版本也在不停修 Mods 的边角问题。我遇到过某个小版本里 Mods 的挂载点不生效升级到下一个 patch 又好了的情况。如果你在排查 Mods 问题时实在找不到逻辑错误可以看看是不是版本本身的 bug先去官方 changelog 确认一下。6.2 推荐的 Mod 管理习惯我个人现在管理 Mods 的方式很简单用户级放通用 Mod项目级放专用 Mod。用户级~/.claude/mods/里常驻两三个——一个统一代码风格一个规范提交信息一个强制测试验证项目级只在需要特定流程时才加用完就禁用不长期挂着。另外我养成了一个习惯每个 Mod 内部写好 README记录这个 Mod 解决的问题、适用的挂载点、以及和哪些 Mod 有冲突。之前没做这件事的时候两个月后回头看自己写的 Mod经常要想半天这个规则当时是为了解决什么场景。加了 README 之后维护成本直线下降。最后分享一个使用上的小技巧当你发现 Claude Code 的行为变得奇怪第一步不是去改规则而是先/mods看看当前启用了哪些 Mod然后逐个禁用排查。Mods 的模块化设计本来就该配合二分禁用来用——一次禁用一半很快就能定位到问题出自哪个插件。这个排查方式我在前面提到的冲突场景里反复用到比反复调整优先级声明高效得多。从 2.1.287 开始Claude Code 的扩展性确实上了一个台阶。Mods 把改行为从玄学般的提示词调教变成了可安装、可卸载、可版本管理的工程化操作。工具本身还在快速迭代但用模块化插件来定制 AI 代理行为这个思路大概率会是后面很长一段时间的演进方向。趁早把 Mods 玩明白后面不管工具怎么升级你都能比别人更快地搭出顺手的工作流。