Hooksで自動ワークフローを組む
このレッスンで学ぶこと
- □Hooksの仕組み — 特定のイベントに自動処理を紐づける
- □5つのHookタイプ（SessionStart / PreToolUse / PostToolUse / Notification / Stop）
- □.claude/settings.jsonへの設定方法
- □実践例: セッション開始時の自動読み込み・停止時のログ保存
- □Hookが失敗しても本処理を止めないための設計原則
Hooksとは何か
Hooksは、Claude Codeの特定のイベントに対して自動で処理を実行する仕組みです[1]。 「セッションが始まったらこれをやる」「ツールを実行する前にチェックする」「セッションが終わったらログを保存する」といった定型処理を、設定ファイルに書いておくだけで毎回自動で走ります。
重要なのは、HooksはClaude（AI）ではなく、あなたのマシン上で直接実行されるという点です。 bashコマンドやPythonスクリプトなど、任意のプログラムを指定できます。AIが介在しないため、決定論的（毎回同じ結果）で信頼性が高い処理が可能です。
Hookの実行フロー
5つのHookタイプ
Claude Codeでは5種類のイベントにHookを設定できます。それぞれの発火タイミングと典型的なユースケースを見ていきましょう[1]。
SessionStart
発火タイミング: セッション開始時、最初のメッセージが処理される前
ユースケース: 過去の作業ログを読み込む、前回のTODOリストを表示する、日次のデータを確認する、Git statusをチェックする
PreToolUse
発火タイミング: Claude Codeがツール（Bash, Edit, Write等）を実行する直前
ユースケース: 危険なコマンド（rm -rf、force pushなど）をブロックする、特定ファイルの変更を禁止する、機密ファイルへのアクセスを検知する
PostToolUse
発火タイミング: Claude Codeがツールを実行した直後
ユースケース: ファイル変更のログを記録する、コードフォーマッターを自動実行する、テスト結果を記録する
Notification
発火タイミング: Claude Codeがユーザーに通知を送るとき
ユースケース: 音声通知を鳴らす（VOICEVOXなど）、Slackに通知を転送する、デスクトップ通知をカスタマイズする
Stop
発火タイミング: Claudeのレスポンスが完了した後
ユースケース: 作業ログをファイルに保存する、セッションの要約を生成する、変更ファイルの一覧を記録する
Hooksの設定方法
Hooksは .claude/settings.json のhooks セクションに記述します[3]。 JSON形式で、どのイベントにどのコマンドを紐づけるかを定義します。
設定ファイルの基本構造
設定の各フィールド
| フィールド | 説明 | 例 |
|---|---|---|
| matcher | 実行条件。ツール名やパターンを指定 | "always", "Bash", "Write" |
| command | 実行するシェルコマンド | "python3 log.py" |
| timeout | タイムアウト（ミリ秒） | 10000（10秒） |
matcherの使い分け
"always" はすべてのイベントで実行されます。 PreToolUseやPostToolUseでは、ツール名を指定して特定のツールだけに反応させることもできます。 たとえば "Bash" を指定すると、 bashコマンド実行時のみ発火します。実践例: よく使うHookパターン
実務で特に役立つHookのパターンを3つ紹介します。そのまま使えるので、まずはコピーして試してみてください。
パターン1: セッション開始時にTODOを表示
毎回「前回の続きは何だっけ？」と思い出す必要がなくなります。TODO.mdの内容がセッション開始時に自動で読み込まれます。
パターン2: 危険なコマンドをブロック
rm -rf やgit push --force を検知して実行を止めます。 PreToolUseのHookが exit 2 を返すと、 そのツール実行がブロックされます。
パターン3: セッション終了時にログ保存
セッションが終了するたびに、作業内容をログファイルに自動保存します。「あの時何やったっけ？」が後から確認できます。
json.load(sys.stdin) すれば何でもできる。最初はシンプルなcatコマンドから始めて、慣れたらスクリプトに移行するのがおすすめ。Hookを安全に運用するための注意点
Hookの失敗が本処理を止めないように
安全設計のチェックリスト
- 1.タイムアウトを設定する — 外部APIを呼ぶHookは必ずtimeoutを指定。無限に待たせない
- 2.エラーハンドリング — スクリプト内でtry-except。失敗してもexit 0
- 3.冪等性を意識 — 同じHookが複数回走っても問題ない設計にする
- 4.機密情報に注意 — Hookの出力はClaude Codeのコンテキストに入る。APIキー等を標準出力に流さない
- 5.ログを残す — デバッグ用に、Hookの実行結果をファイルに記録しておく
PreToolUseの特殊な戻り値
exit 0 で続行、exit 2 でブロック。 stdoutにJSON {"decision":"block","reason":"理由"} を出力すると、ブロック理由をClaudeに伝えられます。Lesson 9 まとめ
- ✅Hooksは特定のイベント（開始・ツール実行前後・通知・終了）に自動処理を紐づける仕組み
- ✅AIではなく自分のマシン上で実行されるため、決定論的で信頼性が高い
- ✅PreToolUseで危険な操作をブロック、Stopで作業ログを自動保存が定番パターン
- ✅Hookの失敗が本処理を止めない設計（エラーハンドリング・タイムアウト）が必須
あなたの番です
出典・参考文献
本レッスンで引用したデータの原典一覧です。数値は各調査の公開時点のものであり、閲覧時期により更新されている可能性があります。
- [1]Claude Code Hooks Documentation — Anthropic（2025）
- [2]Claude Code Overview — Anthropic（2025）
- [3]Claude Code Configuration — Anthropic（2025）
よくある質問
HooksはClaude Code Maxプランでないと使えない？
Hooksは全プランで利用可能です。.claude/settings.json に記述するだけで動作します。有料プラン限定の機能ではありません。
Hookの中でAPI呼び出しはできる？
はい、可能です。PythonやNode.jsのスクリプトを指定すれば、Slack API、Discord webhook、その他あらゆるHTTP通信が可能です。ただし、APIキーを標準出力に流さないよう注意し、タイムアウトを必ず設定してください。
Hookが複数ある場合の実行順序は？
同じイベントに複数のHookが設定されている場合、配列に記述された順番で実行されます。あるHookの失敗が後続のHookに影響しないよう、各Hookは独立して動作するように設計しましょう。
自動化の土台ができた。次はサブエージェントで複数タスクを同時に処理する方法を学ぼう。
Lesson 10: サブエージェント →