编写 Hookify 规则¶

概述¶

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

规则文件格式¶

基本结构¶

---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---

Message to show Claude when this rule triggers.
Can include markdown formatting, warnings, suggestions, etc.

Frontmatter 字段¶

高级格式（多条件）¶

---
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
---

You're adding an API key to a .env file. Ensure this file is in .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 事件¶

匹配 Edit/Write/MultiEdit 操作： - 调试代码：console\.log\(, debugger - 安全风险：eval\(, innerHTML\s*= - 敏感文件：\.env$, credentials, \.pem$

stop 事件¶

完成检查与提醒。模式 .* 始终匹配。

prompt 事件¶

匹配用户 prompt 内容，用于强制执行工作流。

模式编写技巧¶

正则表达式基础¶

• 转义特殊字符：. 转义为 \.，( 转义为 \(
• \s 空白字符，\d 数字，\w 单词字符
• + 一个或多个，* 零个或多个，? 可选
• | 或运算符

常见陷阱¶

• 过于宽泛：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.{descriptive-name}.local.md
• Gitignore：将 .claude/*.local.md 添加到 .gitignore

命令¶

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

快速参考¶

最小可用规则：

---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
Warning message here