writing-rules

Hookify ルール作成ガイド

使用する場面

• 望ましくない操作を防ぐための動作ルールを作成するとき
• Claude Code セッション向けの永続的なガードレールを定義するとき

使用しない場面

• 複雑な複数ステップのワークフロー — 代わりにエージェントを使用してください
• 永続的な動作ルールが不要な一度限りの操作

概要

Hookify ルールは、監視するパターンとそのパターンに一致したときに表示するメッセージを定義する、YAML フロントマター付きの Markdown ファイルです。ルールは .claude/hookify.{rule-name}.local.md ファイルに保存されます。

クイックスタート

.claude/hookify.dangerous-rm.local.md を作成します。

---
name: dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

🛑 **Dangerous rm command detected!**

This command could delete important files.

確認： コマンドに --help フラグを付けて実行し、利用できることを確認します。

ルールはすぐに有効になります。再起動は不要です。

ルールファイルの形式

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

name（必須）：一意の識別子（ケバブケース） enabled（必須）：true または false event（必須）：bash、file、stop、prompt、または all action（任意）：warn（デフォルト）または block pattern（シンプル）：照合する正規表現パターン

イベントの種類

• bash：Bash ツールのコマンド
• file：Edit、Write、MultiEdit ツール
• stop：エージェントが停止しようとしたとき
• prompt：ユーザーのプロンプト送信
• all：すべてのイベント

高度な条件

複数のフィールドをチェックする場合：

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

演算子

• regex_match：パターン照合
• contains：部分文字列のチェック
• equals：完全一致
• not_contains：含まれていてはならない
• starts_with：接頭辞のチェック
• ends_with：接尾辞のチェック

フィールドの参照先

bash イベント： command file イベント： file_path、new_text、old_text、content prompt イベント： user_prompt stop イベント： transcript

パターンの記述

正規表現の基本

• \s - 空白文字
• \d - 数字
• \w - 単語構成文字
• . - 任意の文字（ドットそのものには \. を使用）
• + - 1 回以上
• * - 0 回以上
• | - OR

例

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

パターンのテスト

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

ルールの例

破壊的なコマンドをブロックする

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

🛑 **Destructive operation blocked!**
Can cause data loss.

デバッグコードについて警告する

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

🐛 **Debug code detected!**
Remove before committing.

テストを必須にする

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

本番ファイルを保護する

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

🚨 **Production file!**
Requires review.

管理

有効化／無効化： .local.md ファイルを編集します：enabled: false

削除：

rm .claude/hookify.my-rule.local.md

一覧表示：

/hookify:list

関連スキル

• abstract:hook-scope-guide - Hook の配置に関する判断
• abstract:hook-authoring - SDK Hook の開発
• abstract:hooks-eval - Hook の評価

ベストプラクティス

1. シンプルなパターンから始める
2. 正規表現を十分にテストする
3. 明確で役立つメッセージを使う
4. 最初はブロックより警告を優先する
5. 説明的な名前を付ける
6. メッセージに意図を記載する

トラブルシューティング

よくある問題

ルールがトリガーされない場合は、event の種類が使用中のツールと一致していることを確認してください（例：コマンドラインツールには bash を使用します）。正規表現の pattern が有効で、対象のテキストに一致することを、短い Python スクリプトでテストしてください。.claude/ にルールファイルを作成するときに権限エラーが発生する場合は、そのディレクトリにユーザーが書き込めることを確認してください。

完了条件

• ルールファイルが .claude/hookify.<rule-name>.local.md に存在し、必須のフロントマターフィールドである name（ケバブケース）、enabled、event、および pattern または conditions がすべて記載されている
• ルールを保存する前に、 python3 -c "import re; print(re.search(r'<pattern>', '<test>'))" で正規表現パターンを検証している。未テストのパターンは含めない
• 一致する入力でルールが正しくトリガーされる：warn アクションではメッセージ本文が表示され、block アクションでは操作が阻止される
• 一致しない入力ではルールが発動しない。既知の安全な例を少なくとも 1 つ使って誤検知をテストしている