Claude Code Mods: Custom Hooks to Fix My Biggest AI Coding Frustrations
TL;DR · AI 摘要
Claude Code Mods: Custom Hooks to Fix My Biggest AI Coding Frustrations Towards Data Science Agentic AI Claude Code Mods...
核心要点
- 主题聚焦：Claude Code Mods: Custom Hooks to Fix My Biggest
- 来源：Towards Data Science，建议结合原文判断细节。
- AI 分析暂不可用，本条为保底评分与摘要。
Claude Code Mods：自定义钩子解决我最大的AI编码烦恼 | Towards Data Science
智能代理AI
Claude Code Mods：自定义钩子解决我最大的AI编码烦恼
我如何构建了四个Claude Code模组来保护API密钥、跟踪计划进度、捕获未测试代码并监控上下文使用情况——这些模组通过135个通过测试，且开销比传统钩子少达100倍，并解释为什么它们可以超越传统钩子。
Chien Vu Minh
2026年10月30日
24分钟阅读
更喜欢我们在Google上的版本
分享
照片由Glen Carrie在Unsplash上提供
1. 你不断重复的提醒
我认为你们中的大多数人和我一样，多次遇到这个问题：我们不断告诉Claude Code或任何LLM，“不要打印密钥”。场景是：我在笔记本电脑上的工作区撰写这些文章。其.env文件包含API密钥和密码，我不希望它们出现在屏幕上、日志中或Claude的输出中。
我检查了会话历史记录，查看自己重复提醒的频率。2026年8月9日至10月7日之间，我开启了60次会话。其中20次明确告诉Claude不要打印敏感值。我还扫描了所有60次会话，发现没有与.env文件中的密钥完全匹配的内容。这令人安心，但仍然需要手动重复提醒。我真正想要的是Claude Code能自动遵循这个规则，而无需每次手动输入。
当我回顾66次会话时，另外两个模式尤为突出：
- 计划：Claude在27次会话中编辑了408次Markdown计划文件，并在21次会话中读取了119次。虽然有用，但需要不断打开文件才能查看进度。
- 任务完成：在两次会话中，Claude标记了13个任务完成。其中12个在最新代码更改运行或测试前就被标记为完成。
我之前尝试过几种方法。当记得时，聊天提醒有效。我的CLAUDE.md文件明确警告不要打印密钥，但发现自己仍然需要重复指令。设置钩子可以阻止工具调用，但每次检查都会启动新进程，在我的笔记本电脑上耗时55-99毫秒。
直到2026年10月1日，Anthropic在Claude Code 2.1.287版本中引入了模组功能。
模组是运行在Claude Code进程内部的小型函数。这种部署方式使其与众不同。聊天中的规则只有在模型记住时才有效。模组作为代码存在，因此每次都会运行。设置钩子为每次检查启动新进程。模组已经在运行，因此可以低成本检查并实时更新界面。如果你读过《每个任务的支架》，请将模组视为一次调整一个规则的支架调整方式。
我构建了四个模组来优化自己的工作流程并进行测试。构建这些模组时，我从会话历史中提取了重复内容，然后询问哪些部分可以通过代码可靠处理：
- secret-guard 提醒Claude如何处理密钥，并在工具输出中隐藏敏感信息。
- plan-meter 在提示上方显示计划进度。
- done-gate 在Claude未测试最新更改时标记任务完成时发出警告。
- context-meter 显示填充上下文窗口的内容，而无需运行/context命令。
在第三部分中，我将逐一讲解每个模组及其背后的API，包括模组在你的设备上可以访问的内容。你可以通过/<mod> on 和 /<mod> off 逐个启用或禁用它们。
2. 从外部到内部
2.1 什么是模组？
自发布以来，Claude Code 主要通过 MCP、钩子、自定义子代理、状态行、插件、技能等功能在模型外部运行。这一情况随着 Claude Mods 的出现发生了改变。2026 年 9 月 3 日，Anthropic 工程师 Alice Poteat 提出了一套在 Claude Code 内部运行的 TypeScript 函数系统，灵感来源于 Express 和 Koa 的中间件。这个想法在六天后演变为 Claude Mods，并于 10 月 1 日发布。
Poteat 的架构文档《Function Hooks: Core Architecture》捕捉到了关键差异：外壳钩子依赖于其环境，而“函数钩子是与引擎的契约”。我利用这份文档理解设计原理，并将其主张与发布的版本进行核对。Mods 可以直接响应 Claude Code 事件并调用其接口。正如 Boris Cherny 在发布当天所说：“每个人的工作方式都不同。”我的前三个 Mods 来自我工作区中的重复性任务，这使它们成为自然而然的自建对象。
图 1：钩子、指令和 MCP 服务器从 Claude Code 外部运行。Mods 在其内部运行，基于自己的事件。蓝色表示 Claude Code，绿色表示你的 Mods，本图中均如此。图片由作者提供
2.2 如何创建一个 Mod
你无需亲自编写 Mods。但构建一个小型 Mods 是理解其工作原理的好方法。让我们创建一个简单的 secret-guard 实现，用于阻止执行 cat .env 命令。在开始之前，你需要 Claude Code 2.1.287 或更高版本。
#### 2.2.1 简单方式：让 Claude 自动构建
打开 Claude Code 并提问：
创建一个阻止执行
cat .env的 Mod。
Claude 可以利用内置的插件开发技能来创建它。在提示时批准热重载。然而，该 Mod 仅在当前会话中有效。要保留它，请将文件夹从 ~/.claude/dev-mods/ 复制到你自己的目录中。
#### 2.2.2 手动方式：六步构建
一个 Mod 是包含三个文件的插件：
text
env-guard/
├── .claude-plugin/plugin.json
└── hooks/
├── hooks.json
└── register.js步骤 1：创建文件夹
bash
mkdir -p env-guard/.claude-plugin env-guard/hooks步骤 2：添加插件清单
创建 env-guard/.claude-plugin/plugin.json：
json
{
"name": "env-guard",
"version": "0.1.0",
"description": "拒绝打印 .env 文件的命令",
"author": { "name": "你的名字" }
}步骤 3：注册 Mod
创建 env-guard/hooks/hooks.json：
{
"description": "env-guard 钩子模块",
"modules": ["./register.js"]
}modules 键告诉 Claude Code 将你的 JavaScript 代码加载为 Mod。
步骤 4：编写钩子
创建 env-guard/hooks/register.js：
javascript
const READS_ENV = /\bcat\s+\.env\b/
export function register(on) {
on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
if (READS_ENV.test(e.command)) {
return { deny: '不要打印 .env。改用 source .env 和 $NAME。' }
}
return next(e)
}).catch(async ($, e, next) => {
return { deny: 'env-guard 失败，因此此命令未执行：' + next.error.kind }
})
}以下是发生的情况：
on('tool.call', { tool: 'Bash' })监听 Bash 命令。
e.command包含 Claude 想要执行的命令。
return { deny: ... }阻止命令执行。
next(e)允许其他命令正常运行。
.catch如果钩子本身失败，会阻止执行。
每个钩子接收 ($, e, next)：API、事件和传递事件的函数。你可以允许、修改或阻止事件。.catch 使此防护默认处于关闭状态，如第 3.1 节所述。
步骤 5：验证它
claude plugin validate ./env-guard在输出中查找带有 Bash 过滤器的 tool.call。如果未找到，请检查事件名称是否存在拼写错误。
步骤 6：测试
按以下方式打开 Claude
claude --plugin-dir ./env-guard现在向 Claude 提问：
请展示我的 .env 文件内容。
如果 Claude 尝试执行 cat .env 命令，该模块会阻止并返回拒绝信息。在会话期间，你也可以编辑 register.js。Claude Code 会自动重新加载模块。
下一步方向
这是一个有意设计的简单示例。它阻止了 cat .env 命令，但其他命令仍可能暴露敏感信息。为了更全面的防护，可以像 secret-guard 那样检测更多命令或对工具结果中的敏感值进行遮蔽。当模块正常工作后，请添加测试用例并通过 claude plugin test 命令运行测试。
此处使用 JavaScript 是为了简化设置流程，但 Claude Code 也支持 TypeScript（register.ts）。
3. 模块的工作原理
secret-guard 展示了模块如何在 Claude 查看结果前修改工具输出。done-gate 使用相同方法添加警告，plan-meter 在屏幕上绘制内容，context-meter 跟踪会话使用情况。我将分别解释每个模块的工作方式、成本以及我执行的验证测试。Anthropic 提醒该 API 在版本迭代中可能发生变更。因此我在 Claude Code 2.1.296 版本上测试了开关功能，并在 2.1.295 版本上测量了 secret-guard 的表现。
3.1 思路 1：secret-guard，从 Claude 隐藏敏感信息
secret-guard 的作用是将 .env 文件中的值从 Claude 的视野中隐藏，同时展示如何安全使用这些值。这替代了我之前在 60 次会话中的 20 次手动输入的提醒。
Claude Code 使用事件来通知当前发生的情况。例如，按下回车键时触发 prompt.submit 事件，工具运行前触发 tool.call 事件，屏幕更新时触发 ui.render 事件。钩子是模块附加到事件上的函数。例如，on('tool.call', { tool: 'Bash' }, hook) 会在 Claude 即将执行 shell 命令时运行。{ tool: 'Bash' } 部分用于过滤处理的事件。
每个钩子接收 ($, e, next) 参数：$ 提供对 Claude Code 功能的访问，e 描述事件，next 用于传递事件。钩子可以：
- 允许：调用 next(e) 继续执行。
- 修改：将修改后的事件传递给 next。
- 阻止：不调用 next 直接返回，例如 { deny: 'why' }。
钩子还可以在 next 返回后检查和修改结果。这让一个钩子能够完成设置钩子中 PreToolUse 和 PostToolUse 分别处理的工作。
secret-guard 综合使用这些选项。在会话开始时，它会从工作目录向上搜索到磁盘根目录，将 .env 文件中的值加载到内存。然后它会在 prompt.context 中添加注释，列出受保护的密钥名称，解释 ‹hidden: NAME› 标记的含义，并指示 Claude 在命令中使用 $NAME 而非打印值。
cat .env 或单独的 env 命令会被阻止，并建议改用 source .env 和 $NAME。其他命令正常执行，但 secret-guard 会在 Claude 查看结果前检查输出。它通过 DB_PASSWORD 等名称或私钥、数据库密码等模式识别敏感信息。例如，在执行 grep -r KEY . 后，Claude 会看到 .env:DEMO_API_KEY=‹hidden: DEMO_API_KEY› 。
还有一个编辑保护机制。如果 Claude 将隐藏标记复制到文件中，secret-guard 仅在文件已包含该标记时恢复原始值，否则会阻止更改。当多个插件处理相同事件时，它们会形成类似 Express Web 服务器的中间件链。公司钩子优先执行，其次是用户插件、内置钩子和 Claude 代码本身。每个钩子可以选择传递事件或中止事件，结果会按相反顺序返回。这使得插件可以在不相互了解的情况下协同工作。
图 2：调用会依次经过每个插件，结果按相反顺序返回。没有 .catch 的守卫在钩子崩溃时会开放失败；带有拒绝 .catch 的守卫会封闭失败。图片由作者提供
如果钩子在调用 next 之前抛出错误或超时，Claude 代码仍会继续执行。换句话说，它会开放失败。要使守卫封闭失败，其 .catch 必须拒绝无法检查的步骤。claude plugin validate 会标记缺少此保护机制的阻塞钩子。设置钩子存在类似问题：以代码 1 退出不会阻止操作。
钩子在不使用模型的情况下运行，因此不消耗任何 token，即使在长时间对话中也能保持一致。在第 4 部分中，每个检查耗时约 0.25 毫秒。Claude 仍需遵循备忘录，但钩子强制执行规则。
我使用 58 个测试用例、第 4 部分的回放和包含 11 个 env 文件的项目对 secret-guard 进行了测试。它阻止了 Get-Content .env 操作，遮蔽了假数据库密码，并允许部署脚本完成。遮蔽结果来自 Claude Code 2.1.295 上的 v0.3.1；测试和开关功能在 2.1.296 上的 v0.4.0 中验证。
secret-guard 并不是安全边界。其黑名单故意设计得非常狭窄。阻止所有 .env 提及会破坏无害命令，但仍可能遗漏类似 grep -r KEY . . 的内容。其遮蔽功能也会遗漏未识别格式，例如 base64 值、短前缀或独立的 AWS 密钥。甚至因为变量名包含 PRIVATE 或 SECRET 而遮蔽了 IP 地址，直到我添加了例外规则。
对于 Claude 绝对不能读取的文件，请使用权限拒绝规则、沙箱、文件权限或密钥管理器。我也不能声称 secret-guard 防止了泄露：我最初的提醒功能已经在所有 60 次会话中生效。优势在于拥有自动检查，而不是依赖那个提醒。
图 3：secret-guard 的钩子分为六个部分。每个部分只执行一项任务，在本例中值永远不会到达 Claude 或屏幕。图片由作者提供
### 3.2 思路 2：done-gate，用警告替代阻断
done-gate 跟踪修改的代码文件和测试运行。如果 Claude 在最新更改后未通过测试就标记任务完成，它会在工具结果和屏幕上添加警告：
> done-gate："Add double()" 被标记为完成，但有 1 个代码文件被修改且本次会话中未运行任何测试：calc.py。在您将此任务标记为完成之前，请运行测试...
我开发它是因为 Claude 在两次会话中未重新测试修改代码的情况下，将 13 个任务中的 12 个标记为完成。done-gate 通过 tool.call 监控编辑、shell 命令和任务列表更新。与 secret-guard 不同，它从不阻止任何操作。那 12 个任务是无测试套件的实验脚本，因此缺少测试不一定是问题。警告比硬性规则更有意义。
如果 done-gate 崩溃，其 .catch 方法会允许原始工具结果继续执行。一个损坏的警告不应该中断工作。它还可以在没有模型的情况下运行，因此不会消耗任何 token。回放会话显示，它本应在 13 次完成中有 12 次发出警告。早期版本错误地将 echo pytest 计为一次测试运行，我在审查期间修复了这个问题。当前版本在 Claude Code 2.1.296 上通过了 23 个测试，并在套件的安装测试中产生了预期的警告。
图 4：done-gate 允许步骤执行，并在 Claude 的阅读内容中添加备注。没有内容被拒绝；Claude 自行决定。图片由作者提供
### 3.3 思路 3：plan-meter，在屏幕上绘制进度
plan-meter 在提示上方显示计划进度，显示类似 plan ▸ Demo plan · phases 0/2 · steps 1/4 (25%) · now: Build . 的进度条。侧边栏列出步骤，这样我可以在不打开计划文件的情况下查看进度。
在 66 次会话中，Claude 编辑了计划文件 408 次并读取了 119 次。这些文件帮助 Claude 跟踪工作，但我希望有一个更易于我跟踪的方案。该模块使用渲染站点在界面特定区域（如提示上方或侧边栏）绘制内容。它监视 tool.call 以获取计划编辑，读取更新后的文件，并将最新进度存储在会话状态中。Claude Code 随后会自动重新绘制显示。由于渲染在模型外部进行，因此不会消耗任何 token。该模块在终端和桌面应用中均能正常工作。在非交互模式（claude -p）下，它会返回单行文本。
我用 21 个计划文件进行了测试。它在 10 个文件中找到了步骤计数，在另外 10 个文件中找到了状态行。它还在 Claude Code 2.1.296 上通过了 28 个测试，包括一个测试用例：勾选步骤后，显示从 steps 1/4 更新为 steps 2/4。
图 5：模块绘制到提示上方的区域和侧边栏等渲染站点，并通过一次调用设置状态行。绘制操作不消耗 token。图表由作者提供
### 3.4 思路 4：context-meter，读取会话
context-meter 显示每次对话后上下文窗口的使用情况，同时显示提示缓存倒计时和一个“Compact”按钮。我开发它是为了在不运行命令的情况下始终显示 /context 提供的信息。
它从 $.session.usage 获取使用数据，与 /context 显示的分析结果相同。提示缓存有助于减少重复对话内容的成本。订阅用户缓存持续 1 小时，API 密钥用户缓存持续 5 分钟，重用时会重置。由于模块无法检测适用情况，它会显示其假设，例如 cache ▸ 40:00 left (1h TTL, assumed: subscription)。
“Compact”按钮是这四个模块中唯一需要调用模型的功能。它要求 Claude 总结对话以释放上下文空间，但节省效果因情况而异。在一次会话中，压缩使使用量从 211k 降至 132k token，因为 Claude Code 恢复了摘要并读取了最近的文件。早期版本过早检查使用情况，错过了变化。版本 0.1.5 通过压缩后再次检查解决了这个问题。在实际测试中，显示立即从 178k 降至 98k token。该模块在 Claude Code 2.1.296 上通过了 26 个测试。
图 6：context-meter 显示填充上下文窗口的内容和缓存持续时间，不消耗任何 token。只有“Compact”功能会调用模型。图表由作者提供
### 3.5 模块可以访问的内容
插件不会直接访问文件、网络或程序。它们使用 $ 调用，例如通过 $.fs.read 读取文件或通过 $.process.run 启动程序。由于这些调用在代码中声明，Claude 插件验证工具可以在不运行任何内容的情况下列出它们。例如，secret-guard 声明了十个调用，包括使用 $.fs.list 和 $.fs.read 检查 env 文件、使用 $.store 保存其开关状态，以及使用 $.env.get 定位主文件夹。它不会进行网络调用或启动任何程序。组织也可以通过防护机制阻止特定的 $ 调用。
但插件并非运行在沙盒环境中。它们以你的权限运行，其文件操作不会触发工具权限提示。我在测试时确认了这一点，当测试插件在未提示的情况下写入我的主文件夹时，Claude Code 的 bash 沙盒也不会覆盖插件启动的程序。与我在 SkillSpector 文章中分析的基于 Markdown 的威胁不同，插件会运行可执行代码。因此要检查调用：在安装前查看调用列表。Anthropic 还可以远程禁用已安装的插件。
图7：Claude 插件验证工具在 secret-guard 运行前列出其可访问范围。插件仍然以你的权限运行。图片由作者提供
### 3.6 构建和测试插件
我通过用普通英语描述需求并要求 Claude Code 使用其内置的插件开发技能来实现插件，从而构建每个插件。我无需先学习 API。我的工作流程如下：
- 描述规则，例如“从我的 .env 文件中隐藏秘密。”
- 要求 Claude Code 构建插件。
- 运行 claude plugin validate 并审查其调用：列出调用列表。
- 生成测试并运行 claude plugin test，该工具使用 Claude Code 的引擎而无需会话或模型调用。
- 使用 --plugin-dir 加载插件并在真实会话中进行测试。
验证和测试发现了大多数问题。Codex 审查发现了另外33个问题，而实际测试暴露了测试未发现的问题。例如，Claude Code 2.1.294 引入了内置的 /plan 命令，与 plan-meter 冲突，尽管所有测试都通过了。截至 Claude Code 2.1.296，所有四个插件都能成功验证并通过135项测试。
每个插件只需三个文件：
secret-guard/ ├── .claude-plugin/plugin.json 名称、版本、用户可设置的选项 ├── hooks/hooks.json { "modules": ["./register.ts"] } └── hooks/register.ts export const register = (on, options) => { … }
### 3.7 启用和禁用插件
我并不需要所有四个插件始终运行。每个插件都支持 /<mod> on、/<mod> off 和 /<mod> status 命令。当禁用时，插件会无任何模型调用、文件写入或消息传递给 Claude 地通过事件。每个插件都有一个测试来验证这一点。
设置会在会话和项目之间持久化。Secret-guard 默认启用，显示为 secret-guard OFF：禁用时秘密不会隐藏。其他三个默认禁用，因此你可以根据需要启用它们。
我在开源项目 claude-code-mods-kit 中发布了这些插件，这是一个 MIT 许可的 Claude Code 插件市场。发布前，我移除了本地路径和个人信息，检查了密钥泄露情况，并在带有假秘密的临时文件夹中测试了安装。我还验证了 secret-guard 阻止了 cat .env 命令，plan-meter 更新了显示，done-gate 发送了提示信息。该工具包包含参考文献中列出的另外四个插件。
若要在不安装的情况下尝试某个插件：
claude --plugin-dir claude-code-mods-kit/plugins/plan-meter
对于永久安装，请添加市场并选择您的模组：
claude plugin marketplace add vumichien/claude-code-mods-kit claude plugin install secret-guard@chien-mods claude plugin install done-gate@chien-mods claude plugin install plan-meter@chien-mods claude plugin install context-meter@chien-mods
然后输入 /<mod> 以启用所需的模组。
## 4. 两项测试：防护与开销
### 4.1 命令 vs. 值：哪种效果更好？
我想测试 Idea 1 的权衡：每种方法会阻止多少无害操作，又有多少泄露会漏网？
secret-guard 支持两种模式。命令模式会阻止引用受保护 .env 文件的调用（加载文件时除外），但不检查值。值模式（默认）使用 Idea 1 的规则来拒绝危险调用，并在工具结果中隐藏秘密。
我通过 claude plugin test 进行测试，使用记录的工具输出重放相同调用：
- 从我 60 次会话中提取的 369 个提及 .env 的真实调用。没有暴露密钥，因此阻止它们会被视为误报。
- 12 个使用假密钥精心构造的泄露，包括 cat .env、printenv、Python、base64 和部分密钥输出。我添加了 grep -r LLM_API_KEY . 来观察当命令完全不提及 .env 时会发生什么。
无害真实调用被拒绝（共 369 个）
构造泄露被阻止（共 12 个）
命令模式
157
7（漏掉了递归 grep 和四个先加载 .env 的命令）
值模式
2
10（漏掉了 base64 复制和孤立的 8 字符前缀）
图 8：命令模式拒绝了 157 个无害调用并阻止了 7 个泄露。值模式拒绝了 2 个，每个都引用了受保护密钥的标记，并阻止了 10 个泄露。作者图片
命令模式阻止了 157 个无害调用，包括其推荐的安全名称-only 命令中 14 次使用中的 6 次。它阻止了 12 个泄露中的 7 个，但漏掉了递归 grep 和四个先加载 .env 再输出值的命令。加载是允许的，以便脚本正常运行，但这留下了漏洞。另一方面，值模式仅阻止了 2 个无害调用，都是尝试将占位符 ‹hidden: LLM_API_KEY› 写入文件的尝试。它还删除了 4 个包含假密钥的工具结果。它阻止了 12 个泄露中的 10 个，捕获了完整值和密钥名称旁的 20 字符摘录。base64 复制和孤立的 8 字符前缀通过了检查，因为它们看起来不像秘密。
对于我的目标“不要打印值”，值模式是更好的权衡。它在捕获更多泄露的同时几乎保留了所有无害操作。但两种模式都不是安全边界。如果编码秘密是严重风险，我会使用显式拒绝规则或秘密管理器，而不是依赖命令模式。
### 4.2 检查会增加多少开销？
我还测量了简单检查的成本：“这个命令是否提到了 .env？”
在我的 Ryzen 9 5900X 笔记本电脑（Windows 11 家庭版，Claude Code 2.1.291）上，我测试了五种运行相同逻辑的方式。设置钩子会启动一个新的 Python 或 Node.js 进程，直接或通过 Git Bash 运行，各有 200 次运行。模组钩子通过 claude plugin test 运行了 2,000 次。
检查运行方式
每项检查中位数
95 百分位
直接启动的 Python 程序
68.6 毫秒
73.2 毫秒
直接启动的 Node.js 程序
55.5 毫秒
59.1 毫秒
通过 Git Bash 启动的 Python 程序
98.5 毫秒
105.8 毫秒
通过 Git Bash 启动的 Node.js 程序
87.6 毫秒
92.1 毫秒
通过测试框架运行的模组钩子
0.27 毫秒
0.38 毫秒
图9：每次新程序检查耗时均超过终端每秒30次重绘所分配的33毫秒。模块钩子耗时0.27毫秒。图片由作者提供
新进程检查耗时55-99毫秒。在测试环境中，模块钩子耗时0.27毫秒。
我也检查了实时会话。在五次调用中，Claude Code的调试日志显示模块钩子的中位耗时为0.6毫秒（包含与模块进程的通信）。这大约是新进程方案的100倍速度提升。作为参考，以每秒30帧刷新的终端，每帧约有33毫秒可用时间。所有新进程检查都超过了这个时间限制；模块检查仅使用了其中极小的一部分。
这对每个工具调用都需要运行的防护机制尤为重要，尤其是在Claude进行交互式工作时。这些数据仅衡量检查开销而非整体会话速度，且来自单一Windows机器。在不同环境中，进程启动成本会有差异。
## 5. 结论
### 5.1 你真的需要模块吗？
并非所有重复指令都需要模块。合适工具的选择取决于你想要实现的目标。
图10：根据规则需要执行的操作，选择放置规则的位置。图片由作者提供
如果Claude需要做决策，应将指令放在CLAUDE.md文件或技能中。像"先写测试"或"保持答案简洁"这类指令不需要模块或额外模型调用。如果你已有运行简单检查的脚本，设置钩子可能就足够了。当需要在每个步骤执行操作、改变Claude的视野或在工作时显示信息时，才需要使用模块。这就是想法1-3所展示的场景。
在安全方面，应使用权限拒绝规则、沙盒技术、文件权限或密钥管理器。钩子不是安全边界。对于一次性任务，直接向Claude提问即可。
### 5.2 从阻碍你的瓶颈开始
我创建这些模块是因为自己不断重复相同检查：在60次会话中有20次需要提醒，408次需要打开编辑计划，以及在未经测试的修改后手动检查13个任务中的12个。因此，我只是想停止在重复检查上浪费时间。你也可以在自己的工作中发现类似模式。Claude Code会将会话记录本地存储，因此可以查看几个记录或跟踪一周内重复的指令。寻找你反复询问的内容，如"运行测试"、"我们处于哪个阶段？"或"还剩多少上下文？"。
Ben Newton提出了另一种方法：他让Claude审查30次会话并建议了10个模块。他的文章包含相关提示。
一旦获得列表，使用第5节来判断哪些内容真正需要模块。从最困扰你的问题开始，按照"我是如何构建它们"中的五步流程操作，并先尝试只读模块如plan-meter。显示错误不会造成危害；没有.catch的防护失效时也不会静默失败。
## 6. 术语表
- CLAUDE.md：Claude Code在每次会话开始时读取的指令文本文件。
- 设置钩子：Claude Code在固定时刻启动的小程序，可以阻止某个步骤。
- 模块：Claude Code在每个步骤中从自身进程内部调用的小函数。
- MCP：模型上下文协议，一种将外部程序插入AI应用的标准方式。
- 事件：Claude Code工作中的命名时刻，包含即将发生事项的描述。
- 钩子：模块为事件注册的函数。
- 匹配器：用于筛选哪些事件能到达钩子的过滤器。
- $：钩子用于访问外部内容的对象；所有对其的操作都是事件。
- 站立备注：模在每次回合中向模型读取内容添加的几行文本，每次压缩后会重建。
- 中间件链：一系列小型函数，每个函数处理请求或将其传递下去。
- 开放失败/封闭失败：当检查失败时，允许步骤通过/拒绝步骤。
- 渲染站点：Claude Code 屏幕上模可以绘制的命名位置，例如乐队或面板。
- 状态：Claude Code 在会话期间存储模值的内存；写入状态会重新绘制读取它的内容。
- 上下文窗口：模型在每次回合中读取的所有内容，从系统提示到最新消息。
- 提示缓存：对话的开头部分，由Anthropic暂时保存，因此不会在每次消息中以全额发送。
- 压缩：用模型编写的摘要替换到目前为止的对话，以释放上下文窗口的空间。
- 存储（$.store）：模自己的一个小文件，会话结束后仍然存在。
- 市场：Claude Code 可以安装的插件目录。
- 开关：/<mod> 的开启、关闭和状态；关闭时所有事件都会原样通过。
- 输出样式：Claude 编写回复方式的保存指令。
## 7. 参考文献和资源
### Claude Code 文档（Anthropic）
- 模概述：code.claude.com/docs/en/plugins/mods/overview。模可以执行而设置钩子、技能和MCP无法做到的功能，以及Anthropic官方描述的信任模型。
- 创建模：code.claude.com/docs/en/plugins/mods/create。三个文件、--plugin-dir 以及 claude plugin validate 的输出内容。
- 响应事件：code.claude.com/docs/en/plugins/mods/events。($, e, next) 钩子、三种操作、模的执行顺序以及 .catch。
- 使用模API：code.claude.com/docs/en/plugins/mods/api。用于命令、计时器、文件和状态行的 $ 接口。
- 在界面中绘制：code.claude.com/docs/en/plugins/mods/interface。屏幕地图、面板、乐队和状态。
- 测试模：code.claude.com/docs/en/plugins/mods/test。claude plugin test，无需会话、登录或网络即可运行。
- 模参考：code.claude.com/docs/en/plugins/mods/reference。截至v2.1.290版本的所有事件、渲染站点和限制（截至2026年10月10日仍有效）。
- 钩子参考：code.claude.com/docs/en/hooks。设置钩子，包括阻止和不阻止的退出代码。
- 更新日志：code.claude.com/docs/en/changelog。第二部分中所有日期的来源。
- Claude Code 如何使用提示缓存：code.claude.com/docs/en/prompt-caching。一小时和五分钟的生命周期，各自的适用时机以及更改它们的设置（检查时间：2026年10月8日）。
### Anthropic 博客文章
- Anthropic，"使用TypeScript用模自定义Claude Code"，2026年10月1日。claude.com/blog/claude-code-mods。发布文章，简短易读。
- Addy Osmani，"开始使用Claude Code模"，claude.dev，2026年10月1日。claude.dev/blog/getting-started-with-claude-code-mods。如果更喜欢跟随示例而不是阅读参考，这是一个逐步的模示例。
- Alice Poteat（Anthropic），“函数钩子：核心架构”，2026年8月，附于GitHub问题#91870。github.com/user-attachments/files/31802150/EXTERNAL.Function.Hooks.Core.Architecture.pdf。模背后的设计文档：钩子作为嵌套中间件，五个位置，每个表面上的绘制方式，$的构建方式以及组织如何控制它。（检查时间：2026年10月8日；它描述了提案，因此请与已发布的文档核对细节）
- poteat (Anthropic), "Mods - make Claude 10x more extensible", GitHub issue #91870, opened 3 September 2026. github.com/anthropics/claude-code/issues/91870 . The original proposal and its design reasoning.
- Boris Cherny, post on X, 1 October 2026. View this Tweet on X Why mods exist, in one line.
- Anthropic, "Claude 3.7 Sonnet and Claude Code", 24 February 2025. anthropic.com/news/claude-3-7-sonnet . Where Claude Code began.
- Anthropic, "Customize Claude Code with plugins", 9 October 2025. anthropic.com/news/claude-code-plugins . The plugin format that mods are packaged in.
### Code
- claude-code-mods-kit: github.com/vumichien/claude-code-mods-kit · License MIT. The four mods from this article, with their tests, plus four more built from ideas in AI LABS' video (below): prompt-enhancer, assumption-check, idea-shelf and session-monitor. Worked examples to read, fork and change, or install as they are. The README lists every plan format plan-meter reads.
- anthropics/claude-code-playground: github.com/anthropics/claude-code-playground · License Apache-2.0. Anthropic's sample mods: a context-window band (token-weather, which context-meter builds on as an idea), a guard that holds risky shell commands for a yes, and a replay of the last turn's edits. token-weather's README includes the prompt that built it.
- anthropics/claude-code: github.com/anthropics/claude-code · All rights reserved. The mods/ folder holds the built-in mods and the types file. Read it there; it isn't licensed for reuse.
### Further reading
- Ben Newton, "I asked Claude to read 30 of my Claude Code sessions and build the mods I needed", 4 October 2026. benenewton.com/blog/five-claude-code-mods-session-visibility . He independently arrived at a similar approach: Claude read 30 of his sessions, suggested ten mods and built five. The post includes his prompt and the bugs caught in a real run.
- AI LABS, "Claude Mods Are Insane... You Need To Try These Right Now", YouTube, 9 October 2026. youtube.com/watch?v=ERNqRK6sMJY . A 13-minute walk through seven mods built with the plugin-authoring skill. The kit's prompt-enhancer, assumption-check, idea-shelf and session-monitor are my own versions of four of them, adjusted for daily use; the plain-answers mod in part 5 is theirs too.
### Earlier articles on TDS
- "A Harness for Every Task: Putting a Team of Claudes on One Job", Towards Data Science, 12 June 2026. towardsdatascience.com/a-harness-for-every-task-putting-a-team-of-claudes-on-one-job . The harness idea from part 1, "the scaffolding around the model", put to work with a team of Claudes on one job.
- "Detecting Vulnerabilities in Agent Skills with SkillSpector: From Green Checkmark to Real Security Judgment", Towards Data Science, 22 July 2026. towardsdatascience.com/from-green-checkmark-to-real-judgment-auditing-ai-agent-skills-with-skillspector . How to judge an add-on before you trust it, as discussed in "What a mod can reach".