name: writing-hookify-rules description: 当用户要求“创建hookify规则”、“编写hook规则”、“配置hookify”、“添加hookify规则”或需要关于hookify规则语法和模式的指导时，应使用此技能。 version: 0.1.0

编写Hookify规则

概述

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

规则文件格式

基本结构

---
name: 规则标识符
enabled: true
event: bash|file|stop|prompt|all
pattern: 正则表达式模式
---

当此规则触发时显示给Claude的消息。
可以包含Markdown格式、警告、建议等。

前置元数据字段

name (必需): 规则的唯一标识符

使用kebab-case: warn-dangerous-rm, block-console-log
具有描述性且面向操作
以动词开头: warn, prevent, block, require, check

enabled (必需): 激活/停用的布尔值

true: 规则激活
false: 规则禁用（不会触发）
无需删除规则即可切换

event (必需): 触发哪个钩子事件

bash: Bash工具命令
file: 编辑、写入、MultiEdit工具
stop: 当代理想要停止时
prompt: 当用户提交提示时
all: 所有事件

action (可选): 规则匹配时要执行的操作

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

pattern (简单格式): 要匹配的正则表达式模式

用于简单的单条件规则
匹配命令（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
---

您正在向.env文件添加API密钥。确保此文件在.gitignore中！

条件字段:

field: 要检查的字段
- 对于bash: command
- 对于file: file_path, new_text, old_text, content
operator: 匹配方式
- regex_match: 正则表达式模式匹配
- contains: 子字符串检查
- equals: 精确匹配
- not_contains: 子字符串必须不存在
- starts_with: 前缀检查
- ends_with: 后缀检查
pattern: 要匹配的模式或字符串

所有条件必须匹配才能触发规则。

消息正文

前置元数据之后的Markdown内容在规则触发时显示给Claude。

好的消息:

解释检测到了什么
解释为什么有问题
建议替代方案或最佳实践
使用格式提高清晰度（粗体、列表等）

示例:

⚠️ **检测到Console.log！**

您正在向生产代码添加console.log。

**为什么重要:**
- 调试日志不应发布到生产环境
- Console.log可能暴露敏感数据
- 影响浏览器性能

**替代方案:**
- 使用适当的日志库
- 提交前删除
- 使用条件调试构建

事件类型指南

bash事件

匹配Bash命令模式：

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

检测到危险命令！

常见模式:

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

file事件

匹配编辑/写入/MultiEdit操作：

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

检测到潜在有问题的代码模式！

在不同字段上匹配:

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

TypeScript文件中的Console.log！

常见模式:

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

stop事件

匹配当代理想要停止时（完成检查）：

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

停止前，请验证：
- [ ] 测试已运行
- [ ] 构建成功
- [ ] 文档已更新

用于:

关于必要步骤的提醒
完成检查清单
流程执行

prompt事件

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

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

生产部署检查清单：
- [ ] 测试通过？
- [ ] 团队已审核？
- [ ] 监控就绪？

模式编写技巧

正则表达式基础

字面字符: 大多数字符匹配自身

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

特殊字符需要转义:

. (任意字符) → \. (字面点)
( ) → $ $ (字面括号)
[ ] → \[ \] (字面方括号)

常见元字符:

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

示例:

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

测试模式

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

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

或使用在线正则表达式测试器（regex101.com，选择Python风格）。

常见陷阱

太宽泛:

pattern: log    # 匹配 "log", "login", "dialog", "catalog"

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

太具体:

pattern: rm -rf /tmp  # 仅匹配确切路径

更好: rm\s+-rf

转义问题:

YAML引号字符串: "pattern" 需要双反斜杠 \\s
YAML未加引号: pattern: \s 按原样工作
推荐: 在YAML中使用未加引号的模式

文件组织

位置: 所有规则在.claude/目录中 命名: .claude/hookify.{描述性名称}.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前缀)

工作流程

创建规则

识别不需要的行为
确定涉及哪个工具（Bash、Edit等）
选择事件类型（bash、file、stop等）
编写正则表达式模式
在项目根目录创建.claude/hookify.{名称}.local.md文件
立即测试 - 规则在下一次工具使用时动态读取

优化规则

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

禁用规则

临时: 在前置元数据中设置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
---

警告消息在此

带条件的规则:

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

警告消息

事件类型:

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