Back to Details

writing-rules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Table of Contents

目录

Hookify Rule Writing Guide

Hookify规则编写指南

When To Use

适用场景

  • Creating behavioral rules to prevent unwanted actions
  • Defining persistent guardrails for Claude Code sessions
  • 创建行为规则以阻止不必要的操作
  • 为Claude Code会话定义持久化的防护规则

When NOT To Use

不适用场景

  • Complex multi-step workflows - use agents instead
  • One-time operations that do not need persistent behavioral rules
  • 复杂的多步骤工作流 - 请使用Agent替代
  • 不需要持久化行为规则的一次性操作

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
文件中。

Quick Start

快速开始

Create 
.claude/hookify.dangerous-rm.local.md
:
yaml
---
name: dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

🛑 **Dangerous rm command detected!**

This command could delete important files.
Verification: Run the command with 
--help
flag to verify availability.
The rule activates immediately - no restart needed!
创建
.claude/hookify.dangerous-rm.local.md
文件：
yaml
---
name: dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

🛑 **检测到危险的rm命令！**

该命令可能会删除重要文件。
验证： 携带
--help
参数运行命令以验证可用性。
规则会立即生效 - 无需重启！

Rule File Format

规则文件格式

Frontmatter Fields

前置元数字段

name (required): Unique identifier (kebab-case) enabled (required): 
true
or 
false
event (required): 
bash
, 
file
, 
stop
, 
prompt
, or 
all
action (optional): 
warn
(default) or 
block
pattern (simple): Regex pattern to match
name（必填）：唯一标识符（短横线命名法） enabled（必填）：
true
或 
false
event（必填）：
bash
、
file
、
stop
、
prompt
或 
all
action（可选）：
warn
（默认）或 
block
pattern（简单模式）：用于匹配的正则表达式

Event Types

事件类型

  • bash: Bash tool commands
  • file: Edit, Write, MultiEdit tools
  • stop: When agent wants to stop
  • prompt: User prompt submission
  • all: All events
  • bash：Bash工具命令
  • file：Edit、Write、MultiEdit工具操作
  • stop：当Agent想要停止会话时
  • prompt：用户提交提示时
  • all：所有事件

Advanced Conditions

高级条件

For multiple field checks:
yaml
---
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.
如需多字段检查：
yaml
---
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
---

🔐 **检测到.env文件中包含API密钥！**
请确保该文件已添加到.gitignore中。

Operators

操作符

  • regex_match
    : Pattern matching
  • contains
    : Substring check
  • equals
    : Exact match
  • not_contains
    : Must NOT contain
  • starts_with
    : Prefix check
  • ends_with
    : Suffix check
  • regex_match
    ：模式匹配
  • contains
    ：子字符串检查
  • equals
    ：精确匹配
  • not_contains
    ：必须不包含
  • starts_with
    ：前缀检查
  • ends_with
    ：后缀检查

Field Reference

字段参考

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

Pattern Writing

模式编写

Regex Basics

正则表达式基础

  • \s
    - whitespace
  • \d
    - digit
  • \w
    - word character
  • .
    - any character (use 
    \.
    for literal dot)
  • +
    - one or more
  • *
    - zero or more
  • |
    - OR
  • \s
    - 空白字符
  • \d
    - 数字
  • \w
    - 单词字符
  • .
    - 任意字符（使用
    \.
    匹配字面量点）
  • +
    - 一个或多个
  • *
    - 零个或多个
  • |
    - 或

Examples

示例

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

Test Patterns

测试模式

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

Example Rules

规则示例

Block Destructive Commands

拦截破坏性命令

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

🛑 **Destructive operation blocked!**
Can cause data loss.
yaml
---
name: block-destructive
enabled: true
event: bash
pattern: rm\s+-rf|dd\s+if=|mkfs
action: block
---

🛑 **破坏性操作已被拦截！**
可能会导致数据丢失。

Warn About Debug Code

调试代码警告

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

🐛 **Debug code detected!**
Remove before committing.
yaml
---
name: warn-debug
enabled: true
event: file
pattern: console\.log\(|debugger;
action: warn
---

🐛 **检测到调试代码！**
提交前请移除。

Require Tests

要求执行测试

yaml
---
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.
yaml
---
name: require-tests
enabled: true
event: stop
action: warn
conditions:
  - field: transcript
    operator: not_contains
    pattern: pytest|npm test
---

⚠️ **未执行测试！**
请验证更改内容。

Protect Production Files

保护生产文件

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

🚨 **Production file!**
Requires review.
yaml
---
name: protect-prod
enabled: true
event: file
action: block
conditions:
  - field: file_path
    operator: regex_match
    pattern: /production/|\.prod\.
---

🚨 **生产环境文件！**
需要审核。

Management

管理

Enable/Disable: Edit 
.local.md
file: 
enabled: false
Delete:
bash
rm .claude/hookify.my-rule.local.md
List:
bash
/hookify:list
启用/禁用： 编辑
.local.md
文件：
enabled: false
删除：
bash
rm .claude/hookify.my-rule.local.md
列出所有规则：
bash
/hookify:list

Related Skills

相关技能

  • abstract:hook-scope-guide - Hook placement decisions
  • abstract:hook-authoring - SDK hook development
  • abstract:hooks-eval - Hook evaluation
  • abstract:hook-scope-guide - Hook作用域决策
  • abstract:hook-authoring - SDK Hook开发
  • abstract:hooks-eval - Hook评估

Best Practices

最佳实践

  1. Start with simple patterns
  2. Test regex thoroughly
  3. Use clear, helpful messages
  4. Prefer warnings over blocks initially
  5. Name rules descriptively
  6. Document intent in messages
  1. 从简单模式开始
  2. 彻底测试正则表达式
  3. 使用清晰、有帮助的提示信息
  4. 初期优先使用警告而非拦截
  5. 为规则起描述性名称
  6. 在提示信息中说明规则意图

Troubleshooting

故障排除

Common Issues

常见问题

If a rule doesn't trigger, verify that the 
event
type matches the tool being used (e.g., use 
bash
for command line tools). Check that the regex 
pattern
is valid and matches the target text by testing it with a short Python script. If you encounter permission errors when creating rule files in 
.claude/
, ensure that the directory is writable by your user.
如果规则未触发，请验证
event
类型是否与所用工具匹配（例如，针对命令行工具使用
bash
类型）。通过简短的Python脚本测试正则表达式
pattern
是否有效且能匹配目标文本。如果在
.claude/
目录中创建规则文件时遇到权限错误，请确保该目录对当前用户可写。