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

Message to show Claude when this rule triggers.
Can include markdown formatting, warnings, suggestions, etc.

フロントマターのフィールド

name（必須）：ルールの一意な識別子

• kebab-case を使用します：warn-dangerous-rm、block-console-log
• 内容がわかりやすく、アクションを示す名前にします
• 動詞で始めます：warn、prevent、block、require、check

enabled（必須）：有効／無効を切り替えるブール値

• true：ルールは有効です
• false：ルールは無効です（実行されません）
• ルールを削除せずに切り替えられます

event（必須）：実行するフックイベント

• bash：Bash ツールのコマンド
• file：Edit、Write、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
---

You're adding an API key to a .env file. Ensure this file is in .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 detected!**

You're adding console.log to production code.

**Why this matters:**
- Debug logs shouldn't ship to production
- Console.log can expose sensitive data
- Impacts browser performance

**Alternatives:**
- Use a proper logging library
- Remove before committing
- Use conditional debug builds

イベントタイプのガイド

bash イベント

Bash コマンドのパターンに一致させます：

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

Dangerous command detected!

よく使われるパターン：

• 危険なコマンド：rm\s+-rf、dd\s+if=、mkfs
• 権限昇格：sudo\s+、su\s+
• 権限の問題：chmod\s+777、chown\s+root

file イベント

Edit／Write／MultiEdit の操作に一致させます：

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

Potentially problematic code pattern detected!

さまざまなフィールドに対する一致：

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

Console.log in TypeScript file!

よく使われるパターン：

• デバッグコード：console\.log\(、debugger、print\(
• セキュリティ上のリスク：eval\(、innerHTML\s*=、dangerouslySetInnerHTML
• 機密ファイル：\.env$、credentials、\.pem$
• 生成ファイル：node_modules/、dist/、build/

stop イベント

エージェントが停止しようとするときに一致させます（完了チェック）：

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

Before stopping, verify:
- [ ] Tests were run
- [ ] Build succeeded
- [ ] Documentation updated

用途：

• 必須手順のリマインダー
• 完了チェックリスト
• プロセスの徹底

prompt イベント

ユーザーのプロンプト内容に一致させます（高度な用途）：

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

Production deployment checklist:
- [ ] Tests passing?
- [ ] Reviewed by team?
- [ ] Monitoring ready?

パターン作成のヒント

正規表現の基本

リテラル文字： ほとんどの文字は、その文字自体に一致します

• rm は「rm」に一致します
• console.log は「console.log」に一致します

特殊文字はエスケープが必要です：

• .（任意の文字）→ \.（リテラルのピリオド）
• ( ) → \( \)（リテラルの括弧）
• [ ] → \[ \]（リテラルの角括弧）

よく使われるメタ文字：

• \s - 空白文字（スペース、タブ、改行）
• \d - 数字（0-9）
• \w - 単語構成文字（a-z、A-Z、0-9、_）
• . - 任意の文字
• + - 1 回以上
• * - 0 回以上
• ? - 0 回または 1 回
• | - または

例：

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

パターンのテスト

使用前に正規表現パターンをテストします：

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

または、オンラインの正規表現テスター（regex101.com の Python 形式）を使用します。

よくある落とし穴

広すぎるパターン：

pattern: log    # Matches "log", "login", "dialog", "catalog"

改善例：console\.log\(|logger\.

具体的すぎるパターン：

pattern: rm -rf /tmp  # Only matches exact path

改善例：rm\s+-rf

エスケープの問題：

• YAML の引用符付き文字列："pattern"では、バックスラッシュを二重にして\\sとする必要があります
• YAML の引用符なし文字列：pattern: \sはそのまま使用できます
• 推奨事項：YAML では引用符なしのパターンを使用してください

ファイルの整理

**場所：**すべてのルールを.claude/ディレクトリに配置します 命名規則：.claude/hookify.{descriptive-name}.local.md Gitignore：.gitignoreに.claude/*.local.mdを追加します

適切な名前：

• 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 の接頭辞がありません）

ワークフロー

ルールの作成

1. 避けたい動作を特定します
2. 関連するツール（Bash、Edit など）を特定します
3. イベントタイプ（bash、file、stop など）を選択します
4. 正規表現パターンを記述します
5. プロジェクトのルートに.claude/hookify.{name}.local.mdファイルを作成します
6. すぐにテストします。ルールは次にツールを使用したときに動的に読み込まれます

ルールの調整

1. .local.mdファイルを編集します
2. パターンまたはメッセージを調整します
3. すぐにテストします。変更は次にツールを使用したときに反映されます

ルールの無効化

**一時的：**フロントマターで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
---

Warning message here

条件付きルール：

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

Warning message

イベントタイプ：

• 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