Hooks（フックス）

Claude Codeの動作に介入する自動化を組みたい人向け（settings.json の編集経験があれば読めます）

Claude Codeの動作の節目（プロンプト送信前、ツール実行前後、セッション開始時など）に自前のシェルコマンド（=ターミナルから叩くコマンド）を差し込める仕組み。「○○が起きたら必ず△△を実行する」という自動化の入り口。

噛み砕くと

会社の入退室にカードリーダーがあるとして、「入室したら自動で照明をつける」「退室したら自動でPCをロックする」みたいな、特定のタイミングに別の処理を割り込ませる仕掛けが「フック」。Claude Codeにも同じ概念があって、ツールを使う前後・プロンプトを送る瞬間・セッション開始時などに自前のスクリプトを呼べる。

つまり「Claudeに割り込んで自分の処理を挟む」仕組み。本体に手を入れずに自分流のチェック・自動化を足せる。

具体的に何ができる？

• PreToolUse: ツール実行直前に介入（実行を止める・引数をチェックする等）
• PostToolUse: ツール実行直後にログ取り・後処理
• UserPromptSubmit: ユーザーがプロンプトを送信した瞬間に発火
• SessionStart / SessionEnd: セッション開始/終了時の処理
• Notification: Claudeが通知を出すタイミングをカスタム処理
• シェルコマンドだけでなく HTTP（=Webリクエスト）/ Prompt / Agent タイプも選べる

使いどころ3シナリオ

シナリオ1: 禁止フレーズを自動ブロックする

UserPromptSubmit でPythonスクリプトを呼び、プロンプト本文や生成HTMLに禁止語が含まれていたら exit 2（=終了コード2、ブロック判定）で止める。Claudeは「ブロックされた」と認識して別の表現にリトライする。

シナリオ2: 危険コマンドを毎回必ず確認する

PreToolUse で Bash の引数を見て、rm -rf（=強制削除コマンド）や git push --force（=履歴を強制上書きするgit操作）等のパターンが含まれる場合は確認プロンプトを強制表示する。許可リストの抜けを補うガード。

シナリオ3: コード変更を自動でテスト・lint（=コード品質チェック）にかける

PostToolUse で Edit / Write の後に npm run lint や tsc --noEmit（=TypeScriptの型チェック）を走らせて、エラーがあればClaudeに即座にフィードバック。修正の品質を自動でガードできる。

初心者が踏みやすい落とし穴

• フックスクリプトの終了コードに意味がある。0=正常通過、1=警告、2=ブロック。意図しないexit codeで全部止まる事故がある
• 無限ループに注意。フックの中でClaudeに再度プロンプトを投げると延々と回る。フックは「介入だけ・新規呼び出ししない」が原則
• パスは絶対パスで書く。scripts/check.sh のような相対パスは cd 状態に依存して動かないことがある
• フック設定は .claude/settings.json（=Claude Codeの設定ファイル）に書く。プロジェクト内設定とユーザー設定のスコープが違うので、共有したいフックはプロジェクト側に置く

書き方

.claude/settings.json の "hooks" キー

やってみるとこうなる

入力

"hooks": { "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "scripts/check.sh"}]}] }

出力例

指定タイミングでスクリプトが起動し、終了コードや出力でClaudeの挙動を制御する。

関連項目

• /settings-json（準備中）
• /permissions（準備中）
• /pretooluse（準備中）
• /usersubmit（準備中）

公式ドキュメント

https://code.claude.com/docs/en/hooks