第一次听说 Claude Code Mods 的时候我第一反应是Claude Code 不是已经能读写文件、跑命令了吗再加一个 Mods 概念是不是有点多余直到我把自己重复写了十几遍的代码审查说明固化成一个 Mod又让它在一个满是日志的终端窗口里渲染出带边框的仪表盘才意识到 Mods 补的是 Claude Code 最难受的短板每次都要重新交代的上下文和永远只能喷射纯文本的输出方式。Mods 说白了就是给 Claude Code 定义“插件包”。你可以往里面塞一组系统提示、几个自定义工具、一段终端渲染脚本让 Claude 在特定场景下自动装好“人设”和“工具箱”——你问它项目现状它不再甩给你一坨 Markdown 表格而是让终端里直接出现一个仪表盘你让它做代码审查它也不用你最后补一句“按这个模板输出”因为它已经在 Mod 里见过模板了。这篇文章我会从为什么要做 Mods 开始拆解一个可运行的 Mod 结构然后完整带你做一个能在终端画界面的仪表盘 Mod最后聊聊实际落地时踩过的坑。需要说明的是我这里讲的 Mods 更多是社区里围绕 Claude Code 沉淀出的一套扩展约定不是某个封闭的官方插件商店所以你的实现方式和我这里的结构会有差异但核心思路是一样的。1. 为什么 Claude Code 需要 Mods从内置能力到可扩展边界1.1 默认的 Claude Code 到底强在哪、弱在哪先复盘一下 Claude Code 本身。打开终端敲 claude 命令它能基于当前目录的上下文和你对话能读取源码、编辑文件、执行测试也能调用外部脚本。对于写代码、查 bug、重构这种工作开箱即用已经比来回复制粘贴强太多。但用久了你一定会有几个感觉。第一个感觉是同一套项目的套路每次都要重新说。比如“检查这个模块时先看测试再改代码”“输出的报告要包含风险等级和建议”这些话你在每个新会话里都得敲一遍甚至敲得比代码还多。第二个感觉是 Claude 能调用的能力虽然强但基本都是通用命令没有“组合拳”。它不会天然知道自己该用哪个脚本来生成报表除非你在每次对话里专门指路。第三个感觉最明显输出形态完全受限于文本流。遇到长列表、指标状态、多步骤流程纯文本就是一大坨扫一眼根本分不清优先级。这些痛点单靠“提示词技巧”能缓解但每次都要打一针不持久。Mods 的思路是把痛点变成安装包一次配置处处可用。1.2 Mods 到底封装了什么Mods 不是一个新运行时也不是要替代 Claude Code 的底层模型它更像一个配置层和能力层。你的 Mod 里主要能放四类东西系统提示或行为协议告诉 Claude 这个 Mod 服务的场景以及遇到什么情况调用哪个工具。自定义工具注册一段可执行命令、一个脚本入口注册给 Claude 后它能按名字调用。渲染脚本生成终端 UI 用的把结构化数据变成 ANSI 界面。元数据与触发规则描述 Mod 的能力、作用域以及哪些目录、哪些命令前缀下自动生效。组合起来是什么效果同样是“看一下项目现状”这句话没有 Mod 的 Claude 会返回一段文字然后你自己去翻 git log、看 TODO、数文件。有了 Mod它知道有一个工具叫 render_dashboard能搜集这些信息并画成界面于是自动调用把界面直接贴到你的终端里。你看到的不是“我建议你跑一下”而是结果已经躺在那里还是带颜色的。1.3 谁是最适合用 Mods 的人如果只是偶尔用 Claude Code 写个小脚本Mods 帮不了你多少。但如果你的工作流是这样的那一定值得投入你每天会在终端里反复进行同类型操作比如代码审查、依赖升级、发布检查你的项目有固定的输出模板和质量门槛希望 AI 每次都按同一种规范干活你在一支团队里想把 AI 的“最佳工作方式”分享给同事而不是让每个人在提示词里靠玄学复现。Mods 的价值在于把工作流从“个人经验”变成“可加载资产”。一个人手写的 prompt 可能换个环境就失效但一个封装好的 Mod 像工具一样装上就能用。2. 一个能跑的 Mod 长什么样目录结构与核心配置拆解2.1 目录结构不是魔法约定才是Mods 的目录结构没有一套全球统一标准但我建议你遵循一套社区里流传较广的约定所有 Mod 放在~/.claude/mods/下面每个 Mod 一个子目录子目录名就是 Mod 名如果只想对某个项目生效也可以用项目根目录的.claude/mods/效果类似但只在该目录加载。我自己的一个代码审查 Mod 长这样.claude/mods/code-review/ ├── mod.json ├── prompt.md ├── tools/ │ ├── run-lint.sh │ └── collect-diff.sh └── render/ └── review-report.pymod.json是入口告诉 Claude Code 这个 Mod 有什么能力prompt.md是行为协议是每次加载时会注入的上下文tools/放可执行脚本render/放终端渲染相关的脚本。名字不是死的但只要目录和文件在Claude 按mod.json的描述加载就不需要每次把整套逻辑写进对话。2.2 mod.json 怎么填能力描述要具体到能触发一个最小的mod.json可以长这样{ name: code-review, version: 0.1.0, description: 针对当前分支的代码审查工具包收集改动、运行静态检查并输出风险报告, commands: { load: echo loading code-review mod, unload: echo unloading code-review mod }, tools: [ { name: collect_diff, description: 收集当前分支相对主分支的改动文件列表和 diff 摘要供代码审查使用, execute: bash tools/collect-diff.sh }, { name: run_lint, description: 在项目根目录运行静态检查并返回检查结果摘要, execute: bash tools/run-lint.sh } ] }这里重点不是 JSON 本身而是description怎么填。Claude 是语言模型它看到工具名字和描述后会判断“什么时候该调用”。如果你的描述写得太泛比如“执行静态检查”它就可能在用户聊代码思路时误用。所以我习惯把描述写成“当用户要求对当前分支做代码审查、找出代码风险、或准备提交前检查时调用此工具”触发条件越具体被调用的时机越准。2.3 prompt.md真正的行为协议mod.json解决了“有哪些工具”的问题prompt.md解决的是“应该怎么干活、按什么顺序、输出长什么样”。我把它当成一个项目 runbook 来写。比如你是本仓库的代码审查助手。收到审查请求后按以下步骤执行 1. 先调用 collect_diff 获取改动文件清单 2. 对每个改动文件调用 run_lint 检查静态问题 3. 汇总成 markdown 报告包含风险等级表底部给出可执行建议 除非用户明确要求否则不要修改代码只输出报告。这段提示会在 Mod 加载时生效Claude 不会像读普通消息一样把它当成“一条用户消息”而是理解为长期约束。我踩过的一个坑是 prompt.md 里写了太多“要做什么”结果 Claude 每次都把步骤全部做一遍连不需要的工具也调用。后来我改成“优先按条件判断只有满足触发条件才执行”行为立刻稳定了很多。2.4 脚本的执行位置与相对路径tools里的命令在哪个目录执行这个很容易忽略。大多数实现中执行路径是 Mod 所在目录或项目根目录不同环境不一样。我的建议是在工具描述里写明“该命令需要在项目根目录执行”或者用$PROJECT_ROOT这样的变量传入。否则你在自己机器上跑得好好的换到同事的目录结构里相对路径一错Claude 调出来的就是一堆找不到文件的报错。这一条算是 Mods 翻车的第一源头。3. 动手做一个“终端仪表盘”Mod给 Claude 画界面的完整过程3.1 目标拆解让“看项目状态”变成一次工具调用我一开始想做个漂亮的终端 UI但折腾半天发现核心问题其实是Claude 只会输出文本怎么才能让它输出“界面”答案是通过工具调用——让 Claude 调一个我们写好的渲染脚本脚本把数据整理成 ANSI 转义序列终端负责解析这些序列于是画面就出来了。这个 Mod 的目标是用户对 Claude 说“看下项目状态”Claude 自动调用工具工具生成一个带边框、带颜色、带进度条的项目概览面板然后把这个面板原样输出到终端。面板上要有这些信息当前分支、最近若干条提交、源码文件数量、TODO/FIXME 数量、以及一个简单的“健康度”进度条。这些数据分别来自 git、grep 和文件统计完全可以用一段 Python 脚本收集。3.2 用 Python 和 Rich 库写渲染脚本渲染脚本我选了 Rich 库它把 ANSI 字符处理封装得像搭积木一样。先装依赖pip install rich接下来写一个dashboard.py核心逻辑分三部分收集数据、计算状态、渲染面板。收集数据这部分可以直接调用 subprocessimport subprocess, pathlib, re def git_info(): branch subprocess.run([git, branch, --show-current], capture_outputTrue, textTrue).stdout.strip() recent subprocess.run([git, log, --oneline, -5], capture_outputTrue, textTrue).stdout.strip().splitlines() return branch, recent def file_stats(): files list(pathlib.Path(.).rglob(*)) code_files [f for f in files if f.suffix in {.py, .ts, .js, .go}] return len(code_files), len(files)TODO 数量可以打开目录下所有文本文件统计含 TODO 或 FIXME 的行数。注意要跳过node_modules、.git这些目录否则数字会被依赖库污染。然后把这些数据喂给 Richfrom rich.console import Console from rich.panel import Panel from rich.table import Table from rich.progress import Bar def render(branch, recent, code_count, total_count, todo_count): table Table(titleRepository Dashboard) table.add_column(指标, stylecyan) table.add_column(数值, stylegreen) table.add_row(当前分支, branch) table.add_row(代码文件, f{code_count} / {total_count}) table.add_row(TODO/FIXME, str(todo_count)) table.add_row(最近提交, , .join(recent) if recent else 无提交) health max(0, 100 - todo_count * 2 - max(0, total_count - 2000) // 20) panel Panel( f{table}\n[bold]健康度:[/bold] {health}%\n f{Bar(width30, total100, completedhealth)}, titleProject Status, border_styleblue ) Console().print(panel)这里健康度是我随便定义的来自代码里 TODO 数量和文件总量的惩罚项。Bar在 Rich 里渲染出来就是一个带着颜色填充的进度条终端里比任何文字描述都直观。最后在脚本末尾加一个if __name__ __main__:入口直接运行脚本就能看到效果。3.3 把这个脚本注册成 Mod 工具光有一个脚本还不够Claude 得知道什么时候用它。我在mod.json里注册了这样一条工具{ name: render_dashboard, description: 渲染项目状态仪表盘。当用户要求查看项目现状、当前分支、代码健康度、文件统计或TODO情况时调用此工具并将它输出的内容直接展示给用户, execute: python3 render/dashboard.py }注意description里那句“将它输出的内容直接展示给用户”。这句话非常关键它告诉 Claude 这个工具的输出不是让它去解析加工成 Markdown而是应该把原始输出贴给用户。为什么因为渲染脚本输出的是一串 ANSI 转义序列如果 Claude 试图用自然语言描述“脚本展示了项目状态”你就看不到界面了只有让它把原始输出原样保留终端才会把颜色边框画出来。这是我在多次尝试后总结出来的血泪教训。3.4 在 prompt.md 里把调用时机说死prompt.md里我写了更细的行为协议- 当用户发出“看项目状态”“项目怎么样了”“给我来一张仪表盘”等请求时唯一要做的就是调用 render_dashboard并把脚本输出完整原样返回。 - 不要在调用前额外解释也不要在脚本输出后总结。 - 如果没有看到输出如实报告脚本执行错误。这里强调的是“唯一要做的就是调用”防止 Claude 自作聪明先收集一堆数据再编一份 Markdown 报告。由于工具输出的内容已经带 ANSI 界面Claude 再包一层文本反而会破坏渲染效果。跑通之后我在一个真实的报错环境里试了一下问 Claude“看下这个项目怎么了”它直接调用脚本终端里出现一个蓝色的 Project Status 面板当前分支是 main有 3 个 TODO健康度 94%——比从前的文字汇报直观太多了。3.5 终端画界面的底层原理一句话说透终端画界面没有魔法。现代终端模拟器支持 ANSI/VT100 转义序列比如\x1b[31m表示红色\x1b[1m表示加粗\x1b[2J清屏。Rich 库只是把这些序列拼成结构化组件。所以你的渲染脚本本质上是一个字符串生成器Claude Code 把它输出到 stdout终端识别并绘制。也正因如此Mod 能画的界面上限取决于终端模拟器的能力。常见的 TUI 效果——边框、表格、进度条、颜色分块、甚至动态刷新——都可以靠它实现至于更复杂的终端交互比如鼠标点击、区域响应则要看终端协议支持到哪一步。你现在应该理解了所谓“让 Claude 在终端画界面”本质是“让 Claude 调用一个会画界面的工具”。4. 我踩过的坑Mod 调试、作用域和权限边界4.1 改了 Mod 不生效先查加载缓存第一次写 Mod 时特别容易遇到这种情况mod.json改了、脚本改了、prompt.md也改了但 Claude 还是用旧行为。我一度以为是 Mod 机制有 bug后来发现是会话缓存。很多 Mod 加载器会缓存已加载的配置要重新加载才能生效。处理方式通常是在新会话里手动执行 Mod 的 load 命令或者干脆重启 claude 进程。我养成的习惯是改动prompt.md后先跑一个极短的测试指令“你当前加载了哪些 Mod”确认新内容进来再继续调。另外一个隐蔽点有些配置是按项目目录缓存的你在 A 项目里改了全局 Mod切到 B 项目它还是旧版本别急着骂先看作用域。4.2 作用域陷阱全局 Mod 和项目级 Mod 打架Mod 可以放在全局的~/.claude/mods/也可以放在项目根目录的.claude/mods/。默认情况下项目级 Mod 会覆盖或补充全局同名 Mod。听起来简单实际用起来很容易踩坑我在全局配了一个“基础代码审查” Mod团队项目又放了一个定制版“代码审查”结果 Claude 偶尔把两个 Mod 的规则混在一起一会用全局的模板一会用项目级的工具。后来我的处理原则是全局只放通用且无害的 Mod比如“代码提交规范”凡是和具体仓库强相关的 Mod一律放项目级并且起名时带上项目特征的区分。相同场景的 Mod 不要放两份最多一份全局一份项目级且项目级用完全不同的 name。这样可以避免 Claude 在判断上产生混淆。4.3 权限边界工具到底能不能随便跑Mod 里的工具本质上是让 Claude 代替你执行命令权限边界就成了大问题。默认情况下Claude Code 执行命令前会有确认提示但一个 Mod 如果包含很多工具频繁确认会打断交互流畅性。有的配置允许放行某些工具路径减少确认次数。但这里我非常不建议把“待审定的工具”全部无脑放行。尤其当 Mod 里有像rm -rf、git push --force这类危险命令或者网络请求类脚本时务必让 Claude 在每次执行前二次确认。我的折中方案是把无害的只读工具比如 git log、grep、文件统计放行把带副作用操作的工具写文件、安装依赖、远程调用留在确认侧宁可多点几次确认也不让 AI 在没有锚点的情况下干出不可逆操作。Mod 是放大效率的也是放大风险的这个边界要自己守住。4.4 终端渲染失败的三类现场渲染脚本在本地 shell 里跑得很好Claude 一调用就出事我遇到过三类问题各有各的解。现象可能原因处理办法窄终端里表格换行错位脚本未检测终端宽度读取os.get_terminal_size().columns动态调整表格宽度或者按默认 80 列做 fallbackANSI 颜色全部失效TERM环境不对或所在环境不支持彩色设置TERMxterm-256color脚本里做颜色降级降成纯文本表格中文标题乱码进程默认编码不是 UTF-8在脚本开头设置PYTHONIOENCODINGutf-8第一类常见于某些编辑器的集成终端和系统自带终端宽度不一致同一个脚本在不同窗口里效果天差地别。第二类常见于 CI 环境或者远程服务器运维场景那些地方会把颜色序列直接过滤掉。第三类在 Windows 和部分 Linux 服务器上比较容易触发。我的建议是渲染脚本不要假设环境自己先检测不行就退化成普通文本至少保证 Claude 能返回有用的信息。4.5 调试 Mod 的最终武器手动跑不要只靠日志遇到 Mod 行为异常我会先把工具命令手动执行一遍。比如直接跑python3 render/dashboard.py看输出是不是预期的 ANSI 字符串。如果手动跑正常那问题多半出在 Claude 调用时机或参数传递上如果手动跑都不正常那就纯粹是脚本 bug。这个策略听着简单却能省下一大半调试时间。Claude Code 的日志虽然能看到工具调用记录但信息密度远不如你手动执行一次。你可以在一个终端窗口里开claude --verbose另一个窗口改脚本和配置来回切效率比只看日志高很多。5. 用好 Mods 的进阶思路把日常流程沉淀为可复用资产5.1 值得做成 Mod 的四个高频场景我现在的工作流里Mods 不是玩具而是像 shell 别名一样沉淀经验。最常见的四类其实都有共性重复的提示、固定的流程、复杂的工具序列、特定的输出格式。代码审查是一个发布会前检查是另一个——写一个 preflight Mod封装分支对比、依赖安全扫描、测试执行、构建产物确认Claude 一次就跑完整个检查链日志排查也是封装一个日志过滤工具定义时间范围、关键词高亮、错误段提取新项目初始化更是把创建目录、装依赖、生成文件模板全部固化。每一个 Mod 的诞生过程都一样先在对话里把流程聊出最佳做法反复固化然后改成脚本最后封进 Mod。这样即使几个月不看再打开也能一键复现。5.2 团队共享把 Mods 放进 git 仓库Mods 很容易在个人机器上长得像一团乱麻。我的做法是单独建一个 mods 仓库目录组织按 团队级、个人级、实验级 分三块团队成员 clone 后通过脚本把它软链接到~/.claude/mods/。项目强相关的 Mod 直接放在仓库的.claude/mods/下跟着代码走这样新同事拉完代码就自动获得团队约定的 AI 工作流。这里还要注意两件事。第一不要在 Mod 的prompt.md或工具的description里写任何私有密钥、数据库地址、内部系统路径因为 Mod 一旦进仓库这些内容就永久留在历史记录里。第二Mod 更新要和项目版本文档同步版本号里写清楚改动点否则别人拉下仓库后根本猜不到你的 Mod 为什么突然多了一个工具。5.3 组合出更大的能力Mod 之间的数据交接单个 Mod 解决单点问题真正爽的是让多个 Mod 配合。我发现一个很实用的模式一个 Mod 负责“采集”输出结构化 JSON 或 Markdown另一个 Mod 负责“渲染”读取前者的输出变成终端 UI。这样采集和展示解耦任何场景都可以复用那套仪表盘。我的项目概览仪表盘就是这么和代码审查 Mod 配合的。代码审查 Mod 的 collect_diff 工具返回一份 JSON 报告仪表盘 Mod 的 render_dashboard 读 JSON 画面板。Claude 做的只是根据上下文选择合适的工具链不需要我硬编码每个细节。这让 Mods 从“单个流程复制机”变成了“可组合的能力积木”。最后说一点个人体会。刚开始搞 Mods 时我也一度沉迷做花哨的界面、加复杂的自动化后来发现真正持久的还是那些能让你“开会前五分钟把事情看清楚”和“提交代码前少操一遍心”的小工具。界面不是装饰它是在信息流里给你划出的焦点。如果你也在用 Claude Code 干正经活建议从最让你头疼的那一步开始把它变成一个 Mod——哪怕只是一个会画边框的脚本半年后回头看你会感谢当时的自己。