08-04. Hooks で Claude の動作を制御する

この回のゴール

• Hooks の主要イベント(PreToolUse / PostToolUse / Stop / UserPromptSubmit)とその使い分けを理解する
• .claude/settings.json で Hook を 2 つ以上書ける
• Exit Code の意味 (0 / 2 / その他) を覚え、Hook で Claude をブロックできる

1. 動機: Skills では「強制」できない

08-03 で作った Skills は Claude が「使うべき」と判断したら呼ばれる = lazy。 だが業務には 絶対に毎回守らせたい ルールがある:

• Edit の 後、必ずフォーマッタを通す
• Bash で rm -rf を打とうとしたら、必ず止める
• ユーザーが質問を投げる 前 に、特定のコンテキスト(現在の git ブランチなど)を自動で付ける

→ Hooks = Claude のセッション中、特定のイベントで 無条件に実行されるシェルコマンド。

2. Hook の主要イベント

3. Exit Code = 強制力

Hook はシェルコマンド(or スクリプト)。返り値が:

→ exit 2 が 唯一の強制ブロック手段。

4. 設定ファイル .claude/settings.json

最小例(危険コマンドブロック + Edit 後フォーマッタ):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|sudo rm'; then echo 'Blocked: dangerous command' >&2; exit 2; fi"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff format $CLAUDE_FILE_PATHS 2>&1 || true"
          }
        ]
      }
    ]
  }
}

環境変数(Hook に渡されるもの)

• CLAUDE_TOOL_INPUT — tool の入力(Bash の場合はコマンド文字列)
• CLAUDE_FILE_PATHS — Edit/Write 対象のファイルパス
• CLAUDE_SESSION_ID — セッション識別子
• (詳細は公式 docs に変動あり、現状の最新を確認)

5. ハンズオン

5.1 危険コマンドブロック Hook

上記の例の PreToolUse だけをまず入れて起動:

claude
> ホームディレクトリ全部消して

→ Claude が rm -rf ~/ を試みる → Hook が exit 2 → ブロックされる挙動を確認。

5.2 Edit 後フォーマッタ Hook

Python リポジトリで ruff (or black, prettier) をインストール。

> README.md を整形して(行末スペース削除など)

→ Edit 後に ruff format が走り、フォーマット済みになることを確認。

5.3 Stop Hook でログ保存

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date)] session $CLAUDE_SESSION_ID ended\" >> ~/.claude/sessions.log"
          }
        ]
      }
    ]
  }
}

セッション終了ごとに ~/.claude/sessions.log に追記される。

6. アンチパターン

7. CLAUDE.md / Skills / Hooks の総まとめ

→ 階層: CLAUDE.md (Soft) → Skills (Lazy) → Hooks (Hard)

8. 今回の限界 (notes に書く内容)

• Hook は強力だが、Claude Code 本体の挙動を変えるだけ
• 「Claude Code そのものを部分的に 再構成 したい」「特化したエージェント を CI 内で動かしたい」場合は不十分
• → 次回 (08-05) で Agent SDK を学び、自分用エージェント を作る方法を見る

参考

• 公式: Hooks ガイド
• 姉妹サイト: claude-academy-japanese ch6-l2: Hooks で振る舞いを制御する