writing-rules

Hookify 规则编写指南

适用场景

• 创建行为规则，防止不希望发生的操作
• 为 Claude Code 会话定义持久性防护规则

不适用场景

• 复杂的多步工作流——请改用 Agent
• 不需要持久性行为规则的一次性操作

概述

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

快速入门

创建 .claude/hookify.dangerous-rm.local.md：

---
name: dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

🛑 **Dangerous rm command detected!**

This command could delete important files.

**验证：**使用 --help 标志运行命令，以验证其是否可用。

规则会立即生效——无需重启！

规则文件格式

Frontmatter 字段

name（必填）：唯一标识符（kebab-case） enabled（必填）：true 或 false event（必填）：bash、file、stop、prompt 或 all action（可选）：warn（默认值）或 block pattern（简单）：要匹配的正则表达式模式

事件类型

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

高级条件

用于检查多个字段：

---
name: warn-env-edits
enabled: true
event: file
action: warn
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$
  - field: new_text
    operator: contains
    pattern: API_KEY
---

🔐 **API key in .env file!**
Ensure file is in .gitignore.

运算符

• regex_match：模式匹配
• contains：子字符串检查
• equals：完全匹配
• not_contains：不得包含
• starts_with：前缀检查
• ends_with：后缀检查

字段参考

bash 事件：command file 事件：file_path、new_text、old_text、content prompt 事件：user_prompt stop 事件：transcript

编写模式

正则表达式基础

• \s - 空白字符
• \d - 数字
• \w - 单词字符
• . - 任意字符（匹配字面句点请使用 \.）
• + - 一个或多个
• * - 零个或多个
• | - 或

示例

rm\s+-rf          → rm -rf
console\.log\(    → console.log(
chmod\s+777       → chmod 777

测试模式

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

规则示例

阻止破坏性命令

---
name: block-destructive
enabled: true
event: bash
pattern: rm\s+-rf|dd\s+if=|mkfs
action: block
---

🛑 **Destructive operation blocked!**
Can cause data loss.

警告调试代码

---
name: warn-debug
enabled: true
event: file
pattern: console\.log\(|debugger;
action: warn
---

🐛 **Debug code detected!**
Remove before committing.

要求编写测试

---
name: require-tests
enabled: true
event: stop
action: warn
conditions:
  - field: transcript
    operator: not_contains
    pattern: pytest|npm test
---

⚠️ **Tests not run!**
Please verify changes.

保护生产文件

---
name: protect-prod
enabled: true
event: file
action: block
conditions:
  - field: file_path
    operator: regex_match
    pattern: /production/|\.prod\.
---

🚨 **Production file!**
Requires review.

管理

启用/禁用： 编辑 .local.md 文件：enabled: false

删除：

rm .claude/hookify.my-rule.local.md

列出：

/hookify:list

相关技能

• abstract:hook-scope-guide - Hook 放置决策
• abstract:hook-authoring - SDK Hook 开发
• abstract:hooks-eval - Hook 评估

最佳实践

1. 从简单模式开始
2. 充分测试正则表达式
3. 使用清晰且有帮助的消息
4. 初期优先使用警告，而非阻止
5. 使用描述性名称命名规则
6. 在消息中说明规则意图

故障排除

常见问题

如果规则未触发，请确认 event 类型与所用工具匹配（例如，命令行工具应使用 bash）。检查正则表达式 pattern 是否有效，并通过运行简短的 Python 脚本测试其是否匹配目标文本。如果在 .claude/ 中创建规则文件时遇到权限错误，请确保该目录可由你的用户写入。

验收标准

• 规则文件位于 .claude/hookify.<rule-name>.local.md， 并包含所有必需的 frontmatter 字段：name（kebab-case）、 enabled、event，以及 pattern 或 conditions
• 保存规则前，使用 `python3 -c "import re; print(re.search(r'', ''))" 验证正则表达式；不得发布未经测试的模式
• 规则对匹配的输入正确触发：warn 操作 会显示消息正文，block 操作会阻止该操作
• 规则对不匹配的输入不会触发；至少使用一个已知安全示例 测试误报