Claude Code のフック（hooks）入門：ワークフローを自動化する

「変更のたびに自動でフォーマットしたい」「危険なコマンドは実行前に止めたい」——こうした運用を Claude Code に組み込むのがフック（hooks）です。ライフサイクルの特定イベントで任意の処理を自動実行できます。本記事では公式ドキュメントに基づき、設定場所・主要イベント・ブロックの仕組みを実務目線で整理します。

本記事は Claude Code の公式ドキュメント（Anthropic）を参照し、当社が日本語でまとめたものです。フックの仕様・イベント名はバージョンにより追加・変更される場合があります。最新かつ正確な情報は記事末尾の一次資料でご確認ください。

1. フックとは何か

フックは、Claude Code のライフサイクルの特定のイベントで自動実行されるユーザー定義の処理です。ツール実行の前後や、応答の停止時などに割り込み、シェルコマンドの実行・整形・ポリシーの強制などを自動化できます。プロンプトでお願いするのと違い、フックは確実に・毎回実行される点が特長です。

2. どこに設定するか

フックは JSON で設定します。おもな場所は次のとおりです（優先順位順）。

• ~/.claude/settings.json — ユーザー全体（全プロジェクト共通）。
• .claude/settings.json — プロジェクト単位。バージョン管理で共有できます。
• .claude/settings.local.json — プロジェクト単位・gitignore対象（個人用）。

3. 主なフックイベント

イベントは多数ありますが、まず押さえたい代表的なものは次の通りです。

4. 設定の書き方（matcher とコマンド）

設定は「イベント名 → matcher → hooks 配列」の3階層で書きます。matcher は対象ツールを絞る条件で、Edit|Write のようにパイプで複数指定したり、省略・* で全ツール対象にできます。次は、ファイルを書き込んだ後に自動整形する例です。

# .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_PROJECT_DIR\""
          }
        ]
      }
    ]
  }
}

フックにはツールのイベント情報が標準入力（stdin）にJSONで渡されます。共通フィールドには session_id・cwd・hook_event_name などが含まれ、ツールイベントでは tool_name や tool_input も渡されます。パスには ${CLAUDE_PROJECT_DIR}（プロジェクトルート）などのプレースホルダが使えます。

5. 終了コードで挙動を制御する

フックの終了コードは、その後の挙動を左右します。ここは間違えやすいので特に重要です。

次は、PreToolUse で危険な削除コマンドを止める最小例です。stderr に理由を書き、終了コード2で終わります。

# .claude/hooks/block-rm.sh（PreToolUse から呼ぶ）
input=$(cat)   # stdin から JSON を読む
cmd=$(printf '%s' "$input" | grep -o '"command"[^,}]*')
case "$cmd" in
  *"rm -rf"*)
    echo "rm -rf は禁止されています。" >&2
    exit 2 ;;   # 終了コード2でブロック
esac
exit 0

6. 実務での使いどころ

• 自動整形 — PostToolUse で Prettier / gofmt などをかけ、常に整った差分を保つ。
• ガードレール — PreToolUse で危険なコマンドやパスへの書き込みをブロックする。
• 通知 — Notification や Stop で、作業完了をチャットやデスクトップへ知らせる。
• ログ記録 — 各イベントの入力を保存し、あとから挙動を追えるようにする。

これは、当社が別記事で紹介した Mitchell Hashimoto 氏の「ハーネスエンジニアリング」——エージェントの周囲の環境（ハーネス）を整える——という発想とも一致します。フックは、その環境を宣言的に固める有力な手段です。