hookify-rules

撰寫 Hookify 規則

概述

Hookify 規則是帶有 YAML 前置資料的 Markdown 檔案，用來定義要監控的模式，以及當模式符合時要顯示的訊息。規則儲存在 .claude/hookify.{rule-name}.local.md 檔案中。

規則檔案格式

基本結構

---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---

當此規則觸發時要顯示給 Claude 的訊息。
可以包含 Markdown 格式、警告、建議等。

前置資料欄位

欄位	必填	值	說明
name	是	kebab-case 字串	唯一識別碼（動詞優先：warn-, block-, require-*）
enabled	是	true/false	開關而不需刪除
event	是	bash/file/stop/prompt/all	觸發此規則的 hook 事件
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
---

你正在將 API 金鑰加入 .env 檔案。請確保此檔案已在 .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.{descriptive-name}.local.md
• Gitignore：將 .claude/*.local.md 加入 .gitignore

指令

• /hookify [description] - 建立新規則（若無引數則自動分析對話）
• /hookify-list - 以表格格式檢視所有規則
• /hookify-configure - 互動式開啟/關閉規則
• /hookify-help - 完整文件

快速參考

最小可行規則：

---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
警告訊息在此