Hookify 完全使用指南：用对话生成 Claude Code 钩子，告别手写 JSON

📖 内容来源说明

本文内容整理自 @affaanmustafa 的 Claude Code 实战推文、Anthropic 官方 GitHub 文档、claude-plugins-official 仓库以及社区实战文章，经整理归纳，附有真实配置示例。

标签： Claude Code Hookify Hooks AI 编程 自动化 效率工具

为什么需要 Hookify？

Claude Code 有一套强大的 Hooks（钩子）系统，可以在工具执行前后、用户发消息时、Claude 完成回复后自动触发脚本------用来做格式检查、阻止危险命令、发送通知等。

问题是，原生配置方式需要手写嵌套 JSON ，格式复杂、容易出错、每次改完还得重启。很多人知道钩子有用，却因为摩擦成本太高一直没用上。

Hookify 插件就是来解决这个问题的。它把钩子创建变成一次对话：

bash 复制代码

/hookify Warn me when I use rm -rf commands

一句话，自动生成规则文件，立即生效，无需重启。

[01 · 安装 Hookify](#01 · 安装 Hookify)
[02 · 三种使用方式](#02 · 三种使用方式)
[03 · 规则文件格式详解](#03 · 规则文件格式详解)
[04 · 实战配置：10 个立刻能用的规则](#04 · 实战配置：10 个立刻能用的规则)
[05 · 多条件组合规则](#05 · 多条件组合规则)
[06 · 管理与调试](#06 · 管理与调试)
[07 · 性能优化建议](#07 · 性能优化建议)
[08 · 核心要点总结](#08 · 核心要点总结)

01 · 安装 Hookify

方式一：通过插件市场安装（推荐）

在 Claude Code 终端里运行：

bash 复制代码

/plugin install hookify

如果找不到，运行 /plugin，切换到 Discover 标签，搜索 hookify 手动安装。

方式二：通过 npm 安装

bash 复制代码

npx claudepluginhub anthropics/claude-plugins-official --plugin hookify

环境要求

Python 3.7+（无需其他依赖，使用标准库）
Claude Code 已安装并正常运行

验证是否安装成功：

bash 复制代码

/hookify:list

如果返回规则列表（空列表也算），说明安装成功。

02 · 三种使用方式

Hookify 有三个核心命令，适合不同场景。

方式一：直接描述 → 自动生成规则

最常用的方式。用自然语言告诉 Hookify 你想阻止或监控什么行为，它会自动分析并在 .claude/ 目录下创建规则文件。

bash 复制代码

# 基本语法
/hookify <你想要的行为描述>

# 示例：安全类
/hookify Warn me when I use rm -rf commands
/hookify Block any command that touches the home directory
/hookify Warn before executing anything with "production" or "prod"

# 示例：代码质量类
/hookify Don't use console.log in TypeScript files
/hookify Warn when adding hardcoded API keys or secrets to any file
/hookify Require tests to be run before stopping

# 示例：工作流类
/hookify Remind me to update the changelog before committing
/hookify Warn if I'm editing more than 5 files at once

生成后的提示：

复制代码

Created: .claude/hookify.warn-dangerous-rm.local.md
Rules are active immediately --- no restart needed!

方式二：自动分析对话 → 智能推荐规则

当你不确定要设置什么规则时，直接运行不带参数的 /hookify，它会启动一个子代理分析当前对话历史，自动找出你曾经：

明确说过"不要这样做"的地方
纠正过 Claude 操作的地方
表达过沮丧或重复修改的地方

然后自动生成对应规则。

bash 复制代码

/hookify

适合用法：在一个项目工作了一段时间后运行，让它帮你把已经踩过的坑都固化成规则。

方式三：交互式管理现有规则

bash 复制代码

# 查看所有已加载的规则
/hookify:list

# 交互式开启 / 关闭某条规则
/hookify:configure

# 查看帮助
/hookify:help

/hookify:list 示例输出：

复制代码

Active rules (3):
  ✓ warn-dangerous-rm       [bash]  pattern: rm\s+-rf
  ✓ no-console-log-ts       [file]  pattern: console\.log\(
  ✗ require-tests-before-stop [stop]  disabled

03 · 规则文件格式详解

Hookify 生成的是 Markdown 文件，而非 JSON------YAML 头部负责逻辑配置，Markdown 正文是触发时展示给 Claude 的消息内容。

文件路径格式：.claude/hookify.{规则名}.local.md

基础结构

yaml 复制代码

---
name: warn-dangerous-rm       # 规则唯一标识符
enabled: true                 # true = 启用 / false = 禁用
event: bash                   # 监听的事件类型
pattern: rm\s+-rf             # 正则匹配模式
action: warn                  # warn = 警告但继续 / block = 直接拦截
---
⚠️ **检测到危险的 rm 命令！**

请在执行前确认：
- 路径是否正确？
- 是否有备份？
- 是否有更安全的替代方案？

event 事件类型说明

事件类型	触发时机	适用场景
`bash`	执行 bash 命令前	阻止危险命令、提醒风险操作
`file`	写入或修改文件时	检测敏感内容、代码规范
`stop`	Claude 完成回复时	强制检查清单、确认测试已跑
`all`	所有事件	全局监控（慎用，影响性能）

action 动作说明

动作	效果
`warn`	显示警告消息，Claude 可以选择继续或停止
`block`	直接拦截操作，Claude 无法继续执行

04 · 实战配置：10 个立刻能用的规则

以下规则全部来自真实事故案例或高频使用场景，直接复制文件内容即可使用。

规则 1：拦截危险删除命令

真实案例：有用户因 rm -rf ~/ 清空了整个 Mac 主目录。

yaml 复制代码

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf\s+.*(/|~)
action: block
---
🛑 **检测到包含根目录或主目录的 rm -rf 命令，已自动拦截！**

这个命令可能会造成不可逆的数据丢失。
请改用更安全的方式，或手动确认后在终端直接执行。

规则 2：防止硬编码 API 密钥

真实案例：某开发者因 Claude 把 Azure API Key 写进了 Markdown 文件并推送到公开仓库，损失 3 万美元。

yaml 复制代码

---
name: block-hardcoded-secrets
enabled: true
event: file
pattern: (API_KEY|SECRET|TOKEN|PASSWORD)\s*[=:]\s*["'][A-Za-z0-9_\-]{16,}
action: block
---
🔐 **检测到疑似硬编码的密钥或令牌！**

请改用环境变量：
- 将密钥存入 `.env` 文件
- 通过 `process.env.YOUR_KEY` 引用
- 确保 `.env` 已加入 `.gitignore`

规则 3：禁止在 TypeScript 中使用 console.log

yaml 复制代码

---
name: no-console-log-typescript
enabled: true
event: file
pattern: console\.log\(|console\.error\(|console\.warn\(
action: warn
---
🐛 **检测到 console 调试语句！**

提交前请移除所有 console 调用。
建议使用项目统一的日志工具替代。

规则 4：生产环境操作二次确认

yaml 复制代码

---
name: warn-production-commands
enabled: true
event: bash
pattern: (production|prod|--prod|PROD)
action: warn
---
⚡ **即将执行涉及生产环境的命令！**

执行前请确认：
1. 当前是否在正确的分支？
2. 是否已通知相关团队成员？
3. 是否有回滚方案？

规则 5：强制测试通过后才能停止

yaml 复制代码

---
name: require-tests-before-stop
enabled: false
event: stop
action: block
conditions:
  - field: transcript
    operator: not_contains
    pattern: npm test|pytest|cargo test|go test|jest
---
🧪 **未检测到测试执行记录！**

在本次会话中没有发现测试命令的运行记录。
请先运行测试确认代码正确后再结束。

注：此规则默认 enabled: false，在需要严格执行时手动开启。

规则 6：防止修改 .env 文件

yaml 复制代码

---
name: warn-env-file-edit
enabled: true
event: file
pattern: \.env$|\.env\.local$|\.env\.production$
action: warn
---
🔒 **你正在修改环境变量文件！**

请确认：
- 不要将真实密钥提交到版本库
- 修改后是否需要同步更新 .env.example？

规则 7：大范围文件删除预警

yaml 复制代码

---
name: warn-bulk-delete
enabled: true
event: bash
pattern: rm\s+.*\*|\bfind\b.*-delete|\brimraf\b
action: warn
---
⚠️ **检测到批量删除操作！**

即将删除多个文件，请确认操作范围是否正确。
建议先用 `ls` 或 `find` 预览将要删除的文件列表。

规则 8：阻止直接 force push

yaml 复制代码

---
name: block-force-push
enabled: true
event: bash
pattern: git\s+push.*--force|git\s+push.*-f\b
action: block
---
🚫 **Force push 已被拦截！**

直接 force push 可能覆盖其他人的提交。
请改用 `--force-with-lease` 替代，它更安全。

规则 9：tmux 长任务完成通知

yaml 复制代码

---
name: notify-on-stop
enabled: true
event: stop
action: warn
---
✅ Claude 已完成当前任务，等待你的下一步指令。

规则 10：禁止提交 console.log 到 Git

yaml 复制代码

---
name: warn-console-in-commit
enabled: true
event: bash
pattern: git\s+(commit|add)
action: warn
---
📝 **提交前检查提醒**

请确认以下事项后再提交：
- [ ] 已移除所有 console.log / debugger 语句
- [ ] 代码已通过 lint 检查
- [ ] 相关测试已更新并通过

05 · 多条件组合规则

当单一正则不够用时，可以使用 conditions 字段组合多个判断条件，实现更精准的匹配。

示例：只在 TypeScript 文件中检测 API 密钥

yaml 复制代码

---
name: api-key-in-typescript
enabled: true
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.tsx?$
  - field: new_text
    operator: regex_match
    pattern: (API_KEY|SECRET|TOKEN)\s*=\s*["']
action: block
---
🔐 **在 TypeScript 文件中检测到硬编码密钥！**
请改用 `process.env.YOUR_KEY` 环境变量方式引用。

conditions 字段说明

field	含义
`file_path`	文件路径
`new_text`	写入的新内容
`command`	执行的命令
`transcript`	当前会话的完整记录

operator	含义
`regex_match`	正则匹配
`contains`	包含字符串
`not_contains`	不包含字符串

06 · 管理与调试

查看规则是否生效

bash 复制代码

/hookify:list

规则文件位置

所有规则文件存放在项目根目录 的 .claude/ 文件夹下：

复制代码

your-project/
  .claude/
    hookify.warn-dangerous-rm.local.md
    hookify.no-console-log-ts.local.md
    hookify.block-hardcoded-secrets.local.md

注意：规则文件必须在项目的 .claude/ 目录下，而不是插件目录里。

手动调试正则

如果规则不触发，单独测试正则是否正确：

bash 复制代码

python3 -c "import re; print(re.search(r'rm\s+-rf', 'rm -rf /tmp/test'))"

输出不为 None 说明匹配成功。

常见问题排查

问题	解决方式
规则不触发	检查 `enabled: true` 是否设置；检查规则文件是否在项目的 `.claude/` 目录
正则不匹配	用 `python3 -c` 单独测试正则；YAML 中的 pattern 值尽量不加引号以避免转义问题
安装失败	运行 `python3 --version` 确认 Python 3 可用；重新运行 `/plugin install hookify`
响应变慢	避免使用 `event: all`；减少激活中的规则数量；简化正则表达式

07 · 性能优化建议

钩子本质上是在每次工具调用时运行的脚本，规则越多、正则越复杂，响应就越慢。

最佳实践：

使用具体的事件类型（bash 或 file），而不是 all
正则表达式从简单开始，按需增加复杂度
同时激活的规则不超过 10--15 条
对高频操作（如文件保存）的规则要特别注意正则效率
不常用的规则设为 enabled: false，需要时再开启

08 · 核心要点总结

使用场景	推荐命令
快速创建新规则	`/hookify <描述>`
让 AI 分析历史对话生成规则	`/hookify`（不带参数）
查看当前所有规则	`/hookify:list`
开启 / 关闭某条规则	`/hookify:configure`

关键认知：

钩子是确定性护栏 ，不是建议------block 动作无论 Claude 怎么想都会执行
规则文件是 Markdown 不是 JSON------人类可读，可以手动编辑，可以纳入版本控制
无需重启------新建或修改规则文件后，下一次工具调用就会生效
从一条开始------先配置你最想防范的那条规则，看它触发一周，再逐步增加

一句话总结：Hookify 把钩子配置的摩擦成本降到接近零------你早就知道应该设置这些护栏，只是之前太麻烦了没做。现在没有借口了。

参考资源

Hookify 官方文档：github.com/anthropics/claude-code/tree/main/plugins/hookify
Claude Code Hooks 完整参考：code.claude.com/docs/en/hooks-guide
claude-plugins-official 仓库：github.com/anthropics/claude-plugins-official
Hookify 插件页面：claude.com/plugins/hookify

本文为实战整理，如有错误欢迎在评论区指正。