Hooks で振る舞いを制御する

Hooks (フック)

特定のイベント発生時に シェルコマンドを実行 する仕組み。 メモリやプロンプトでは強制できない、決定論的な自動化 に向きます。

イベント例

• SessionStart: セッション開始時
• PreToolUse: ツール実行前
• PostToolUse: ツール実行後
• UserPromptSubmit: ユーザーがプロンプト送信した時
• Stop: Claude の応答終了時
• Notification: 通知イベント
• PreCompact: コンテキスト圧縮前

設定例 (.claude/settings.json)

def route_and_answer(question: str) -> str:
    # 1. Haiku に難易度判定させる
    judge = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=10,
        messages=[{"role": "user", "content": f"次の質問の難易度を easy/hard で答えてください: {question}"}],
    )
    level = judge.content[0].text.strip().lower()

    # 2. 結果に応じて本処理モデルを選ぶ
    target = "claude-opus-4-7" if "hard" in level else "claude-sonnet-4-6"
    return client.messages.create(model=target, ...).content[0].text

Hook の役割

• 強制ルール: 編集後に必ず lint を走らせる、フォーマッタを通す。
• 通知: タスク完了時に音/通知を出す。
• ログ: 全プロンプトをファイルに記録 (監査)。
• ガード: 危険なコマンドをブロック (PreToolUse で exit code 2)。
• 自動 git checkpoint: 編集前に commit を打つ。

exit code の意味

• 0: 正常 (続行)。
• 2: ブロック (Claude がそのアクションを取り消す)。stderr の文言が次のターンに渡されるので、Claude が修正を試みる。
• それ以外: 警告として扱われる。

環境変数

Hook 実行時には便利な環境変数が渡されます: - $CLAUDE_PROJECT_DIR: プロジェクトルート - $CLAUDE_TOOL_NAME: 呼ばれたツール名 (PreToolUse / PostToolUse) - $CLAUDE_TOOL_INPUT_JSON: ツール入力 (PreToolUse)

実用例 1: 編集後フォーマット

月間コスト ≈ (input_tokens × 入力単価) + (output_tokens × 出力単価)

実用例 2: 危険コマンドブロック

PreToolUse で Bash ツールに対し、入力に rm -rf / などが含まれていたら exit 2 でブロック。

wzxhzdk:2

実用例 3: ロギング

wzxhzdk:3

注意

• Hook は ホスト OS 上で実行される ので、悪意あるリポジトリの settings.json に注意。
• 重い処理を入れると体感が悪化する。lint は変更ファイルだけに絞るなど工夫を。
• settings.local.json (gitignore 推奨) に個人設定、settings.json をチーム共有用、と分けるのが定番。

本番運用パターン集 (コピペで使える)

パターン 1: 編集後に変更ファイルだけフォーマット (高速)

「全プロジェクトを毎回フォーマット」は遅すぎる。変更ファイルだけ に絞る:

wzxhzdk:4

→ 編集された そのファイルだけ ruff format が走る。100 ms 以内で終わる。

パターン 2: シークレット流出をブロック (PreToolUse)

.env や鍵ファイルへの 書き込み・読み込み を未然にブロック:

.claude/scripts/guard-secrets.sh:

wzxhzdk:5

settings.json:

wzxhzdk:6

→ Claude が .env を編集しようとした瞬間に止まり、stderr の文言を見て自己修正を試みる。

パターン 3: 全プロンプトをログに残す (監査)

wzxhzdk:7

→ 全プロンプトが ~/.claude/audit.log に記録される。コンプライアンス要件のある現場で必須。

パターン 4: セッション終了時に WIP コミット

「Claude Code を閉じる前に必ず checkpoint」を強制:

wzxhzdk:8

→ 未コミット変更があればセッション終了時に自動 commit。作業ロスト防止。

パターン 5: 危険 git コマンドの追加ガード

PreToolUse で Bash を Inspect:

wzxhzdk:9

Hooks デバッグのコツ

• /hooks で現在登録されている hook を確認
• 失敗時は ~/.claude/logs/hooks.log に stderr が記録される (環境による)
• command の中で set -x を入れると実行コマンドが見える
• 開発中は echo で $CLAUDE_TOOL_INPUT_JSON を出力し、構造を確認