撰寫 Hookify 規則
概述
Hookify 規則是以 YAML 前端資料 (frontmatter) 結尾的 Markdown 檔案，用來定義要監控的模式 (pattern)，以及在比對成功時顯示的訊息。規則存放在 .claude/hookify.{規則名稱}.local.md 檔案中。
規則檔案格式
基本結構
---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---
觸發規則時要顯示給 Claude 的訊息。
可包含 Markdown 格式、警告、建議等。
Frontmatter 欄位
| 欄位 | 必要 | 值 | 說明 |
|---|---|---|---|
| name | 是 | 短橫線分隔的小寫字串 | 唯一識別碼（以動詞開頭：warn-, block-, require-*） |
| enabled | 是 | true/false | 開關，無需刪除規則即可切換 |
| event | 是 | bash/file/stop/prompt/all | 觸發規則的鉤子事件 |
| action | 否 | warn/block | warn (預設) 顯示訊息；block 阻止操作 |
| pattern | 是* | 正則表達式字串 | 要比對的模式 (*或使用 conditions 處理複雜規則) |
進階格式（多條件）
---
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
---
你正在 .env 檔案中加入 API 金鑰。請確保此檔案已在 .gitignore 中！
依事件而異的條件欄位：
- bash：
command - file：
file_path、new_text、old_text、content - prompt：
user_prompt
運算子： regex_match、contains、equals、not_contains、starts_with、ends_with
必須所有條件都符合，規則才會觸發。
事件類型指南
bash 事件
比對 Bash 指令模式：
- 危險指令：
rm\s+-rf、dd\s+if=、mkfs - 權限提升：
sudo\s+、su\s+ - 權限問題：
chmod\s+777
file 事件
比對編輯/寫入/多重編輯操作：
- 除錯程式碼：
console\.log\(、debugger - 安全風險：
eval\(、innerHTML\s*= - 敏感檔案：
\.env$、credentials、\.pem$
stop 事件
完成檢查與提醒。固定比對 .* 模式。
prompt 事件
比對使用者提示的內容，用於工作流程強制規範。
模式撰寫技巧
正則表達式基礎
- 跳脫特殊字元：
.寫成\.，(寫成\( \s空白字元，\d數字，\w文字字元+一個以上，*零個以上，?可選|OR 運算子
常見陷阱
- 太寬泛：
log會比對到 "login"、"dialog"——請改用console\.log\( - 太具體：
rm -rf /tmp——請改用rm\s+-rf - YAML 跳脫：使用不帶引號的模式；帶引號的字串需使用
\\s
測試
python3 -c "import re; print(re.search(r'your_pattern', 'test text'))"
檔案組織
- 位置：專案根目錄下的
.claude/目錄 - 命名：
.claude/hookify.{描述性名稱}.local.md - Gitignore：將
.claude/*.local.md加入.gitignore
指令
/hookify [描述]- 建立新規則（若不提供參數，會自動分析對話內容）/hookify-list- 以表格形式檢視所有規則/hookify-configure- 互動式切換規則開關/hookify-help- 完整文件說明
快速參考
最小可行規則：
---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
警告訊息區