编写 Hookify 规则

概述

Hookify 规则是带有 YAML 前置元数据的 Markdown 文件，用于定义要监控的模式以及匹配时显示的消息。规则存储在 .claude/hookify.{rule-name}.local.md 文件中。

规则文件格式

基本结构

markdown
---
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 实现复杂规则） |

高级格式（多条件）

markdown
---
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 单词字符
• + 一个或多个，* 零个或多个，? 可选
• | 或运算符

常见陷阱

• 过于宽泛：log 会匹配 "login"、"dialog"——请使用 console\.log\(
• 过于具体：rm -rf /tmp——请使用 rm\s+-rf
• YAML 转义：使用无引号模式；带引号的字符串需要 \\s

测试

bash
python3 -c "import re; print(re.search(r'your_pattern', 'test text'))"

文件组织

• 位置：项目根目录下的 .claude/ 目录
• 命名：.claude/hookify.{descriptive-name}.local.md
• Gitignore：将 .claude/*.local.md 添加到 .gitignore

命令

• /hookify [description] - 创建新规则（无参数时自动分析对话）
• /hookify-list - 以表格形式查看所有规则
• /hookify-configure - 交互式切换规则开关
• /hookify-help - 完整文档

快速参考

最小可行规则：

markdown
---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
此处显示警告信息