编写 Hookify 规则
概述
Hookify 规则是带有 YAML 前置元数据的 Markdown 文件，用于定义需要监视的模式以及在匹配时显示的消息。规则存储在 .claude/hookify.{规则名称}.local.md 文件中。
规则文件格式
基本结构
---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---
触发此规则时向 Claude 显示的消息。
可以包含 Markdown 格式、警告、建议等。
前置元数据字段
| 字段 | 必填 | 值 | 描述 |
|---|---|---|---|
| name | 是 | kebab-case 字符串 | 唯一标识符（动词优先：warn-、block-、require-*） |
| enabled | 是 | true/false | 无需删除即可切换开关 |
| event | 是 | bash/file/stop/prompt/all | 触发该规则的钩子事件 |
| action | 否 | warn/block | warn（默认）显示消息；block 阻止操作 |
| pattern | 是* | 正则表达式字符串 | 要匹配的模式（*或使用 conditions 处理复杂规则） |
高级格式（多条件）
---
name: warn-env-api-keys
enabled: true
event: file
conditions:
- field: file_path
operator: regex_match
pattern: \.env$
- field: new_text
operator: contains
pattern: API_KEY
---
您正在向 .env 文件中添加 API 密钥。请确保此文件已列入 .gitignore！
按事件区分的条件字段：
- bash：
command - file：
file_path、new_text、old_text、content - prompt：
user_prompt
运算符：regex_match、contains、equals、not_contains、starts_with、ends_with
所有条件必须同时满足才能触发规则。
事件类型指南
bash 事件
匹配 Bash 命令模式：
- 危险命令：
rm\s+-rf、dd\s+if=、mkfs - 权限提升：
sudo\s+、su\s+ - 权限问题：
chmod\s+777
file 事件
匹配编辑/写入/多编辑操作：
- 调试代码：
console\.log\(、debugger - 安全风险：
eval\(、innerHTML\s*= - 敏感文件：
\.env$、credentials、\.pem$
stop 事件
完成检查和提醒。模式 .* 始终匹配。
prompt 事件
匹配用户提示内容以强制执行工作流程。
模式编写技巧
正则表达式基础
- 转义特殊字符：
.转义为\.，(转义为\( \s空白符，\d数字，\w单词字符+一个或多个，*零个或多个，?可选|OR 运算符
常见陷阱
- 太宽泛：
log会匹配“login”、“dialog”——请使用console\.log\( - 太具体：
rm -rf /tmp——请使用rm\s+-rf - YAML 转义：使用未加引号的模式；引用字符串需要
\\s
测试
python3 -c "import re; print(re.search(r'your_pattern', 'test text'))"
文件组织
- 位置：项目根目录下的
.claude/目录 - 命名：
.claude/hookify.{描述性名称}.local.md - Gitignore：将
.claude/*.local.md添加到.gitignore
命令
/hookify [描述]- 创建新规则（无参数时自动分析对话）/hookify-list- 以表格形式查看所有规则/hookify-configure- 交互式开关规则/hookify-help- 完整文档
快速参考
最小可用规则：
---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
此处显示警告消息