Writing Hookify Rules

编写 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（必填）：规则的唯一标识符

• 使用 kebab-case：warn-dangerous-rm、block-console-log
• 名称应具有描述性，并以动作导向
• 以动词开头：warn、prevent、block、require、check

enabled（必填）：用于启用或停用规则的布尔值

• true：规则已启用
• false：规则已停用（不会触发）
• 可以切换此值，而不必删除规则

event（必填）：要触发的钩子事件

• bash：Bash 工具命令
• file：Edit、Write、MultiEdit 工具
• stop：Agent 想要停止时
• prompt：用户提交提示词时
• all：所有事件

action（可选）：规则匹配时要执行的操作

• warn：显示消息，但允许操作（默认值）
• block：阻止操作（PreToolUse）或停止会话（Stop 事件）
• 如果省略，默认为 warn

pattern（简单格式）：用于匹配的正则表达式

• 用于简单的单条件规则
• 与 command（bash）或 new_text（file）进行匹配
• 使用 Python 正则表达式语法

示例：

event: bash
pattern: rm\s+-rf

高级格式（多个条件）

适用于包含多个条件的复杂规则：

---
name: warn-env-file-edits
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!

条件字段：

• field：要检查的字段
  • 对于 bash：command
  • 对于 file：file_path、new_text、old_text、content
• operator：匹配方式
  • regex_match：正则表达式匹配
  • contains：检查子字符串
  • equals：精确匹配
  • not_contains：子字符串不得出现
  • starts_with：检查前缀
  • ends_with：检查后缀
• pattern：要匹配的模式或字符串

所有条件都必须匹配，规则才会触发。

消息正文

frontmatter 后面的 Markdown 内容会在规则触发时显示给 Claude。

优质消息应：

• 说明检测到了什么
• 说明存在的问题
• 提供替代方案或最佳实践建议
• 使用格式增强清晰度（粗体、列表等）

示例：

⚠️ **Console.log detected!**

You're adding console.log to production code.

**Why this matters:**
- Debug logs shouldn't ship to production
- Console.log can expose sensitive data
- Impacts browser performance

**Alternatives:**
- Use a proper logging library
- Remove before committing
- Use conditional debug builds

事件类型指南

bash 事件

匹配 Bash 命令模式：

---
event: bash
pattern: sudo\s+|rm\s+-rf|chmod\s+777
---

Dangerous command detected!

常见模式：

• 危险命令：rm\s+-rf、dd\s+if=、mkfs
• 权限提升：sudo\s+、su\s+
• 权限问题：chmod\s+777、chown\s+root

file 事件

匹配 Edit/Write/MultiEdit 操作：

---
event: file
pattern: console\.log\(|eval\(|innerHTML\s*=
---

Potentially problematic code pattern detected!

匹配不同字段：

---
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.tsx?$
  - field: new_text
    operator: regex_match
    pattern: console\.log\(
---

Console.log in TypeScript file!

常见模式：

• 调试代码：console\.log\(、debugger、print\(
• 安全风险：eval\(、innerHTML\s*=、dangerouslySetInnerHTML
• 敏感文件：\.env$、credentials、\.pem$
• 生成的文件：node_modules/、dist/、build/

stop 事件

匹配 Agent 想要停止时的情况（完成检查）：

---
event: stop
pattern: .*
---

Before stopping, verify:
- [ ] Tests were run
- [ ] Build succeeded
- [ ] Documentation updated

适用于：

• 提醒完成必需步骤
• 完成检查清单
• 强制执行流程

prompt 事件

匹配用户提示词内容（高级用法）：

---
event: prompt
conditions:
  - field: user_prompt
    operator: contains
    pattern: deploy to production
---

Production deployment checklist:
- [ ] Tests passing?
- [ ] Reviewed by team?
- [ ] Monitoring ready?

编写模式的技巧

正则表达式基础

**字面字符：**大多数字符都匹配自身

• rm 匹配“rm”
• console.log 匹配“console.log”

特殊字符需要转义：

• .（任意字符）→ \.（字面句点）
• ( ) → \( \)（字面括号）
• [ ] → \[ \]（字面方括号）

常见元字符：

• \s - 空白字符（空格、制表符、换行符）
• \d - 数字（0-9）
• \w - 单词字符（a-z、A-Z、0-9、_）
• . - 任意字符
• + - 一个或多个
• * - 零个或多个
• ? - 零个或一个
• | - 或

示例：

rm\s+-rf         Matches: rm -rf, rm  -rf
console\.log\(   Matches: console.log(
(eval|exec)\(    Matches: eval( or exec(
chmod\s+777      Matches: chmod 777, chmod  777
API_KEY\s*=      Matches: API_KEY=, API_KEY =

测试模式

使用前先测试正则表达式模式：

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

也可以使用在线正则表达式测试工具（regex101.com，选择 Python 风格）。

常见陷阱

范围过宽：

pattern: log    # Matches "log", "login", "dialog", "catalog"

更好：console\.log\(|logger\.

范围过窄：

pattern: rm -rf /tmp  # Only matches exact path

更好：rm\s+-rf

转义问题：

• YAML 引号字符串："pattern" 需要双反斜杠 \\s
• YAML 无引号字符串：pattern: \s 可直接使用
• 建议：在 YAML 中使用无引号模式

文件组织

位置： 所有规则都放在 .claude/ 目录中 命名： .claude/hookify.{descriptive-name}.local.md Gitignore： 将 .claude/*.local.md 添加到 .gitignore

好的名称：

• hookify.dangerous-rm.local.md
• hookify.console-log.local.md
• hookify.require-tests.local.md
• hookify.sensitive-files.local.md

不好的名称：

• hookify.rule1.local.md（描述性不足）
• hookify.md（缺少 .local）
• danger.local.md（缺少 hookify 前缀）

工作流

创建规则

1. 确定不希望出现的行为
2. 确定涉及的工具（Bash、Edit 等）
3. 选择事件类型（bash、file、stop 等）
4. 编写正则表达式模式
5. 在项目根目录中创建 .claude/hookify.{name}.local.md 文件
6. 立即测试——规则会在下次使用工具时动态读取

优化规则

1. 编辑 .local.md 文件
2. 调整模式或消息
3. 立即测试——更改会在下次使用工具时生效

禁用规则

临时禁用： 在 frontmatter 中设置 enabled: false 永久禁用： 删除 .local.md 文件

示例

完整示例请参阅 ${CLAUDE_PLUGIN_ROOT}/examples/：

• dangerous-rm.local.md - 阻止危险的 rm 命令
• console-log-warning.local.md - 对 console.log 发出警告
• sensitive-files-warning.local.md - 对编辑 .env 文件发出警告

快速参考

最简可用规则：

---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---

Warning message here

带条件的规则：

---
name: my-rule
enabled: true
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.ts$
  - field: new_text
    operator: contains
    pattern: any
---

Warning message

事件类型：

• bash - Bash 命令
• file - 文件编辑
• stop - 完成检查
• prompt - 用户输入
• all - 所有事件

字段选项：

• Bash：command
• File：file_path、new_text、old_text、content
• Prompt：user_prompt

运算符：

• regex_match、contains、equals、not_contains、starts_with、ends_with