hookify-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Hookify Rules

编写Hookify规则

Overview

概述

Hookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in

.claude/hookify.{rule-name}.local.md

files.

Hookify规则是带有YAML前置元数据的Markdown文件，定义了需要监控的匹配模式以及模式匹配时要展示的消息。规则存储在

.claude/hookify.{rule-name}.local.md

文件中。

Rule File Format

规则文件格式

Basic Structure

基础结构

markdown

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

markdown

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

前置元数据字段

Field	Required	Values	Description
name	Yes	kebab-case string	Unique identifier (verb-first: warn-, block-, require-*)
enabled	Yes	true/false	Toggle without deleting
event	Yes	bash/file/stop/prompt/all	Which hook event triggers this
action	No	warn/block	warn (default) shows message; block prevents operation
pattern	Yes*	regex string	Pattern to match (*or use conditions for complex rules)

字段	必填	取值	描述
name	是	kebab-case格式字符串	唯一标识符（动词优先：warn-, block-, require-*）
enabled	是	true/false	无需删除即可切换规则启用状态
event	是	bash/file/stop/prompt/all	触发此规则的钩子事件类型
action	否	warn/block	warn（默认）展示消息；block阻止对应操作
pattern	是*	正则表达式字符串	匹配模式（*复杂规则可使用conditions字段）

Advanced Format (Multiple 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
---

You're adding an API key to a .env file. Ensure this file is in .gitignore!

Condition fields by event:

bash:
```
command
```
file:
```
file_path
```
,
```
new_text
```
,
```
old_text
```
,
```
content
```
prompt:
```
user_prompt
```

Operators:

regex_match

contains

equals

not_contains

starts_with

ends_with

All conditions must match for rule to trigger.

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

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

所有条件都匹配时规则才会触发。

Event Type Guide

事件类型指南

bash Events

bash事件

Match Bash command patterns:

Dangerous commands:
```
rm\s+-rf
```
,
```
dd\s+if=
```
,
```
mkfs
```
Privilege escalation:
```
sudo\s+
```
,
```
su\s+
```
Permission issues:
```
chmod\s+777
```

匹配Bash命令模式：

危险命令：
```
rm\s+-rf
```
,
```
dd\s+if=
```
,
```
mkfs
```
提权操作：
```
sudo\s+
```
,
```
su\s+
```
权限问题：
```
chmod\s+777
```

file Events

file事件

Match Edit/Write/MultiEdit operations:

Debug code:
```
console\.log\(
```
,
```
debugger
```
Security risks:
```
eval\(
```
,
```
innerHTML\s*=
```
Sensitive files:
```
\.env$
```
,
```
credentials
```
,
```
\.pem$
```

匹配编辑/写入/批量编辑操作：

调试代码：
```
console\.log\(
```
,
```
debugger
```
安全风险：
```
eval\(
```
,
```
innerHTML\s*=
```
敏感文件：
```
\.env$
```
,
```
credentials
```
,
```
\.pem$
```

stop Events

stop事件

Completion checks and reminders. Pattern

.*

matches always.

完成检查和提醒。

.*

模式会始终匹配。

prompt Events

prompt事件

Match user prompt content for workflow enforcement.

匹配用户提示词内容，用于执行工作流强制规范。

Pattern Writing Tips

模式编写技巧

Regex Basics

正则表达式基础

Escape special chars:
```
.
```
to
```
\.
```
,
```
(
```
to
```
\(
```
```
\s
```
whitespace,
```
\d
```
digit,
```
\w
```
word char
```
+
```
one or more,
```
*
```
zero or more,
```
?
```
optional
```
|
```
OR operator

转义特殊字符：
```
.
```
转义为
```
\.
```
，
```
(
```
转义为
```
\(
```
```
\s
```
匹配空白符，
```
\d
```
匹配数字，
```
\w
```
匹配单词字符
```
+
```
匹配1次及以上，
```
*
```
匹配0次及以上，
```
?
```
表示可选
```
|
```
表示或运算符

Common Pitfalls

常见误区

Too broad:
```
log
```
matches "login", "dialog" — use
```
console\.log\(
```
Too specific:
```
rm -rf /tmp
```
— use
```
rm\s+-rf
```
YAML escaping: Use unquoted patterns; quoted strings need
```
\\s
```

匹配范围过宽：
```
log
```
会匹配"login"、"dialog" —— 建议使用
```
console\.log\(
```
匹配范围过窄：
```
rm -rf /tmp
```
—— 建议使用
```
rm\s+-rf
```
YAML转义问题：建议使用未加引号的模式；加引号的字符串需要用
```
\\s
```
表示空白符

Testing

测试

bash

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

bash

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

File Organization

文件组织

Location:
```
.claude/
```
directory in project root

Naming:

.claude/hookify.{descriptive-name}.local.md

Gitignore: Add
```
.claude/*.local.md
```
to
```
.gitignore
```

存储位置：项目根目录的
```
.claude/
```
文件夹下

命名规范：

.claude/hookify.{描述性名称}.local.md

Gitignore配置：将
```
.claude/*.local.md
```
添加到
```
.gitignore
```
中

Commands

命令

```
/hookify [description]
```
- Create new rules (auto-analyzes conversation if no args)
```
/hookify-list
```
- View all rules in table format
```
/hookify-configure
```
- Toggle rules on/off interactively
```
/hookify-help
```
- Full documentation

```
/hookify [描述]
```
- 创建新规则（无参数时自动分析会话内容）
```
/hookify-list
```
- 以表格形式查看所有规则
```
/hookify-configure
```
- 交互式切换规则启用/禁用状态
```
/hookify-help
```
- 查看完整文档

Quick Reference

快速参考

Minimum viable rule:

markdown

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

最简可用规则示例：

markdown

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