2026年9月23日 / 最終更新日 : 2026年10月3日 fujifuji コラム

Claude Code Hooksとは？設定方法・活用例・できることを徹底解説

Claude Code の Hooks（フック） を使えば、AIコーディングアシスタントの動作を「確実に」自動化できます。本記事では、Hooksの基本概念から設定方法、実践的な活用例まで、日本語でわかりやすく解説します。

テックジム東京本校では、情報科目の受験対策指導やAI駆動開発コースもご用意しております。

Claude Code Hooksとは？

Claude Code Hooks は、Claude Code のライフサイクルの特定タイミングで、ユーザーが定義したシェルコマンドやスクリプトを自動実行する仕組みです。

Anthropic が提供するターミナルベースの AI コーディングツール「Claude Code」は、コードの作成・編集・実行を自律的に行えますが、Hooks を使うことでその動作に確定的なルールを組み込むことができます。

「AIに頼むのではなく、必ず実行させる」—— それが Hooks の本質です。

なぜHooksが重要なのか

従来の AI コーディングアシスタントは、ユーザーがプロンプトで「コードをフォーマットして」「テストを実行して」と指示しても、モデルが忘れたり省略したりすることがありました。

Hooks はこの問題を根本的に解決します。

比較項目	プロンプト指示	Hooks
実行の確実性	確率的（モデル次第）	確定的（必ず実行）
設定の場所	チャットの都度	設定ファイルに一度だけ
チーム共有	難しい	`.claude/settings.json` で共有可能
外部ツール連携	限定的	CLI・HTTP・エージェント等すべて対応

Hooksの構成要素

すべてのフック設定は、以下の 3つの要素 で構成されます。

1. Event（イベント）

フックが発火するライフサイクルのタイミングです。SessionStart、PreToolUse、PostToolUse などがあります。

2. Matcher（マッチャー）

フックを特定の条件に絞り込むオプションのフィルターです。対象ツール名などを指定します。単純な文字列・縦棒区切りのリスト・正規表現のいずれかとして解釈されます（詳しい規則は後述）。

3. Action（アクション）

条件が一致したときに実際に実行される処理です。シェルコマンド、HTTPリクエスト、プロンプト評価など複数の種類があります。

イベントの種類一覧

Claude Codeには30種類以上のライフサイクルイベントがあります。まず押さえるべき主要なものを以下に示します（全一覧は後述）。

イベント名	発火タイミング	主な用途
`SessionStart`	セッション開始時（起動・再開・クリア）	開発コンテキストの注入、環境変数の設定
`PreToolUse`	Claudeがツールを実行する直前	危険なコマンドのブロック、バリデーション
`PostToolUse`	ツール実行完了後	自動フォーマット、テスト実行、ログ記録
`UserPromptSubmit`	ユーザーがプロンプトを送信したとき	プロンプトの前処理、追加コンテキストの付与
`Notification`	Claude が通知を送るとき	デスクトップ通知、Slack 通知
`Stop`	Claude が応答を完了したとき	自動コミット、セッションログの保存
`SubagentStart`	サブエージェント起動時	DB接続のセットアップ、環境準備

ハンドラーの種類

Hooksには5種類のハンドラーがあり、用途に応じて使い分けられます。

command（コマンド）

最も基本的なハンドラー。シェルコマンドやスクリプトを実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

http（HTTP）

イベントの JSON データを HTTP POST リクエストとして外部エンドポイントに送信します。外部サービスやウェブフックとの連携に適しています。

prompt（プロンプト）

軽量な Claude モデルにプロンプトを送り、yes/no の判定をさせます。自然言語によるバリデーションが可能です。

agent（エージェント）

Read・Grep・Glob などのツールを使えるサブエージェントを起動し、より複雑な条件を検証してから判定を返します。

設定方法

設定ファイルの場所

フックは主に次の2か所に設定します（全6か所は後述）。

個人設定：~/.claude/settings.json（すべてのプロジェクトに適用）
プロジェクト設定：.claude/settings.json（チームで共有可能）

基本的な設定例

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/lint.sh"
          }
        ]
      }
    ]
  }
}

フックの確認方法

Claude Code 内で /hooks と入力すると、設定済みフックを一覧表示するインタラクティブなブラウザが開きます。各フックのイベント・マッチャー・ハンドラーの詳細を確認できます（読み取り専用）。

実践的な活用例

例1：コード編集後に自動フォーマット

Python ファイルを編集するたびに black と ruff を自動実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

編集されたファイルのパスは、フックの標準入力に渡されるJSONの tool_input.file_path から取り出します。

#!/bin/bash
# .claude/hooks/format.sh
FILE=$(jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
case "$FILE" in
  *.py)             ruff check --fix "$FILE" && black "$FILE" ;;
  *.ts|*.tsx|*.js)  prettier --write "$FILE" ;;
esac
exit 0

例2：危険なコマンドをブロック

rm -rf などの危険な操作を PreToolUse で検知してブロックします。

#!/bin/bash
# hooks/validate-bash.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if echo "$COMMAND" | grep -qE 'rm\s+-rf|sudo rm'; then
  echo "危険なコマンドが検出されました: $COMMAND" >&2
  exit 2  # ブロック
fi

exit 0  # 許可

例3：セッション終了後に自動コミット

Stop イベントを使い、作業完了後に変更を自動的に git コミットします。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git add -A && git commit -m \"auto: Claude Code $(date +%Y%m%d-%H%M%S)\""
          }
        ]
      }
    ]
  }
}

例4：デスクトップ通知

Claude の作業完了時にデスクトップ通知を送ります（macOS の場合）。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code が作業を完了しました\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

例5：テストの自動実行（非同期）

時間のかかるテストスイートはバックグラウンドで非同期実行できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/test-related.sh",
            "async": true,
            "statusMessage": "関連テストを実行中"
          }
        ]
      }
    ]
  }
}

終了コードとエラー制御

フックのシェルコマンドは 終了コード（exit code） によって Claude Code の動作を制御できます。

終了コード	意味	動作
`0`	成功	処理を続行。stdout の JSON 出力を解析
`2`	ブロックエラー	処理を中断。stderr の内容が Claude へのエラーメッセージとして渡される
その他	非ブロックエラー	エラーをログに残しつつ処理は続行

PreToolUse で exit 2 を返すとツール呼び出しがブロックされ、UserPromptSubmit で exit 2 を返すとプロンプト自体が拒否されます。

イベントの全一覧

先ほどの表は代表的なものだけです。実際には30種類以上あり、「何を自動化したいか」から逆引きするのが現実的な使い方になります。用途別に整理します。

ツール実行まわり

イベント	発火タイミング	止められるか
`PreToolUse`	ツール実行の直前	止められる
`PostToolUse`	ツールが成功した後	—
`PostToolUseFailure`	ツールが失敗した後	—
`PostToolBatch`	並列実行されたツール群の後	—
`PermissionRequest`	権限の確認が必要になったとき	—
`PermissionDenied`	自動モードが拒否したとき	—

会話・セッション

イベント	発火タイミング	止められるか
`SessionStart`	セッション開始・再開時	—
`SessionEnd`	セッション終了時	—
`UserPromptSubmit`	プロンプト送信時	止められる
`UserPromptExpansion`	入力したコマンドが展開されるとき	止められる
`Stop`	Claudeが応答を終えたとき	止められる
`StopFailure`	APIエラーでターンが終わったとき	—
`MessageDisplay`	回答テキストが表示されるとき	—
`PreCompact` / `PostCompact`	会話の自動要約の前後	—
`Notification`	通知が出るとき	—

エージェント・タスク

イベント	発火タイミング	止められるか
`SubagentStart` / `SubagentStop`	サブエージェントの起動・終了	—
`TeammateIdle`	チームのメンバーが手を止めようとしたとき	—
`TaskCreated`	タスクが作られるとき	—
`TaskCompleted`	タスクが完了扱いになるとき	—

下の3つはAgent Teams（エージェントチーム）で効いてきます。「テストが通っていないのに完了にする」という挙動は、TaskCompleted で機械的に止められます。

環境・設定の変化

イベント	発火タイミング
`InstructionsLoaded`	CLAUDE.md や `.claude/rules/*.md` が読み込まれたとき
`ConfigChange`	設定ファイルが変わったとき
`CwdChanged`	作業ディレクトリが変わったとき
`DirectoryAdded`	`/add-dir` でディレクトリが追加されたとき
`FileChanged`	監視対象のファイルがディスク上で変わったとき
`PreModelSwitch` / `PostModelSwitch`	モデル切り替えの前後（前は止められる）
`WorktreeCreate` / `WorktreeRemove`	ワークツリーの作成・削除（どちらも止められる）
`Elicitation` / `ElicitationResult`	MCPサーバーが入力を求めたとき・応答したとき
`Setup`	`--init` などの初期化フラグ付きで起動したとき

FileChanged で .env を監視しておき、変更されたら警告を出す、といった使い方ができます。

matcher の書き方には規則がある

matcher は「なんとなく正規表現」ではなく、書いた文字によって解釈が切り替わります。ここを知らないと、意図せず正規表現として扱われて一致しなくなります。

書き方	解釈	例
省略、`""`、`"*"`	すべてに一致	全ツールを対象にする
英数字・`_`・`-`・空白・`,`・`\|` のみ	完全一致、または縦棒区切りのリスト	`Bash`、`Edit\|Write`
それ以外の文字を含む	正規表現（先頭・末尾の固定なし）	`^Notebook`、`mcp__.*`

イベントごとに「何と照合するか」が違う

matcher が照合する対象は、ツール名とは限りません。

イベント	照合される値	例
PreToolUse / PostToolUse など	ツール名	`Bash`、`Edit\|Write`、`mcp__.*`
SessionStart	開始理由	`startup`、`resume`、`clear`、`compact`
SessionEnd	終了理由	`clear`、`logout`、`other`
Notification	通知の種類	`permission_prompt`、`idle_prompt`
SubagentStart / SubagentStop	エージェント種別	`Explore`、`general-purpose`
PreCompact / PostCompact	要約のきっかけ	`manual`、`auto`
FileChanged	ファイル名	`.envrc\|.env`
ConfigChange	設定の出どころ	`project_settings`、`skills`

MCPのツールは mcp__<サーバー名>__<ツール名> という名前になるため、mcp__github__.* のように書けば特定サーバーのツールだけを対象にできます。

5つ目のハンドラーと共通オプション

command・http・prompt・agent に加えて、MCPサーバーのツールを直接呼ぶ mcp_tool があります。

{
  "type": "mcp_tool",
  "server": "my_server",
  "tool": "tool_name",
  "input": { "file_path": "${tool_input.file_path}" }
}

どのハンドラーでも使える共通のオプションが次です。

項目	役割
`timeout`	秒数。command・http・mcp_tool は既定600秒、prompt は30秒、agent は60秒
`async`	`true` で待たずに次へ進む。テスト実行など時間のかかる処理向け
`statusMessage`	実行中に表示する文言
`once`	`true` で1回だけ実行する
`if`	権限ルールと同じ記法で、さらに条件を絞る（例：`Bash(git *)`）
`shell`	`bash` または `powershell`

終了コードより細かく制御する

終了コードだけでは「止める／止めない」しか表現できません。標準出力にJSONを返すと、もっと細かい指示ができます。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "本番DBへの直接操作は禁止です",
    "additionalContext": "代わりにマイグレーションスクリプトを使ってください"
  },
  "systemMessage": "本番DBへのアクセスをブロックしました"
}

フィールド	効果
`permissionDecision`	`allow` / `deny` / `request` を指定する
`permissionDecisionReason`	拒否した理由。Claudeに伝わる
`additionalContext`	Claudeに追加で渡す情報
`updatedInput`	ツールの入力を書き換えて実行させる
`systemMessage`	利用者の画面に出すメッセージ

とくに有用なのが permissionDecisionReason と additionalContext です。単に止めるだけでなく、「なぜ駄目か」と「代わりにどうすべきか」を返せるため、Claudeが自分で正しい方法に切り替えます。

終了コード2が効くイベントは限られる

イベント	終了コード2の効果
`PreToolUse`	そのツール呼び出しをブロックする
`UserPromptSubmit`	プロンプトをブロックし、入力を消す
`Stop`	Claudeを終了させず、作業を続けさせる
`WorktreeCreate` / `WorktreeRemove`	作成・削除を中止する
`PreModelSwitch`	モデル切り替えをブロックする
上記以外	終了コード2は効かない。JSONの判定フィールドを使う

ここは間違えやすい点です。TaskCompleted や TeammateIdle のように「止められる」と説明されるイベントでも、止め方が終了コードなのかJSONなのかはイベントによって違います。意図どおり止まらないときは、まずここを疑ってください。

設定はどこに置けるか

個人設定とプロジェクト設定以外にも置き場所があります。

置き場所	適用範囲	共有
`~/.claude/settings.json`	自分の全プロジェクト	されない
`.claude/settings.json`	そのリポジトリ	される
`.claude/settings.local.json`	そのリポジトリ・自分だけ	されない
管理ポリシー設定	組織全体	利用者は上書きできない
プラグインの `hooks/hooks.json`	そのプラグインが有効な間	プラグインとして配布
スキル・サブエージェントのフロントマター	それが動いている間	される

最後の行が見落とされがちです。スキルの定義ファイルにフックを書いておけば、そのスキルを使う間だけ有効なフックになります。スキルの書き方はAgent Skills・SKILL.mdの解説を参照してください。プラグインとして配布する方法はプラグイン完全ガイドにまとめています。

フックから使える環境変数

変数	内容
`$CLAUDE_PROJECT_DIR`	プロジェクトのルートパス
`$CLAUDE_PLUGIN_ROOT`	プラグインのディレクトリ
`$CLAUDE_EFFORT`	現在の思考の深さの設定
`$CLAUDE_CODE_REMOTE`	クラウド実行時に `true`

スクリプトのパスを書くときは ${CLAUDE_PROJECT_DIR}/.claude/hooks/check.sh のように書いてください。相対パスで書くと、作業ディレクトリが変わったときに動かなくなります。

編集されたファイル名やコマンドの中身は環境変数ではなく、標準入力に渡されるJSONから取り出します。session_id、cwd、permission_mode、tool_input などが入っています。

動かないときの調べ方

/hooks で読み込まれているか確認する。ここに出ていなければ設定ファイルの構文エラーです
JSONの構造を確認する。"hooks" はイベント名をキーにしたオブジェクトです。配列ではありません
matcher の解釈を確認する。特殊文字を含むと正規表現として扱われます
デバッグログを見る。CLAUDE_CODE_LOG_LEVEL=debug claude で起動すると、フックの登録と実行結果が記録されます
スクリプト単体で動かす。標準入力にJSONを流し込んで、終了コードを確認します

すべてのフックを一時的に止めたい場合は、設定ファイルに次を書きます。

{
  "disableAllHooks": true
}

ただし管理ポリシー設定で有効化されたフックは、利用者側からは止められません。

権限ルールとの使い分け

「危険なコマンドを止める」だけなら、フックより権限ルールのほうが簡単です。役割が違います。

	権限ルール	PreToolUseフック
判定方法	コマンド文字列のパターン照合	自分で書いたスクリプトの判断
書きやすさ	設定に1行	スクリプトを用意する
できること	固定のパターンで許可・拒否	条件分岐、外部問い合わせ、理由の返却
向く場面	`rm -rf` のような明確な禁止	「平日の日中だけ」「特定ブランチのときだけ」など

まず権限ルールで書けないか検討し、条件付きの判断が必要なときだけフックを使うのが保守しやすい設計です。権限ルールの書き方はClaude Codeのセキュリティ｜権限設定・許可ルールの書き方で詳しく解説しています。

セキュリティ上の注意点

Hooks は強力な機能ですが、いくつかの重要な注意事項があります。

フルパーミッションで実行される フックはサンドボックスなしで、あなたのユーザー権限で実行されます。設定ミスはファイルの削除や機密情報の漏洩につながる可能性があります。

スクリプトは小さく・明確に保つ フックは「やること一つ」に絞り、副作用を最小限にしましょう。

本番コードとして扱う フックスクリプトはプロジェクトのコードと同様にバージョン管理し、チームでレビューしましょう。

エンタープライズ向け設定 組織管理者は allowManagedHooksOnly 設定を使うことで、承認済みのフックのみを許可し、開発者が独自のフックを追加できないよう制限できます。

よくある質問（FAQ）

Q. Hooks は Claude.ai でも使えますか？ A. いいえ。Hooks は CLI ツール「Claude Code」専用の機能です。Claude.ai（ウェブ版・アプリ版）には対応していません。

Q. フックが動かない場合はどうすれば？ A. claude --debug オプションで起動すると詳細なログが確認できます。また、/hooks コマンドで設定が正しく読み込まれているか確認してください。

Q. チームで同じフックを使うには？ A. プロジェクトルートの .claude/settings.json に設定を記述し、git で共有するのが最善の方法です。

Q. 非同期（バックグラウンド）実行はできますか？ A. はい。"run_in_background": true を設定することで、テストスイートのような重い処理を非同期で実行できます。

Q. HTTP エンドポイントに通知を送れますか？ A. type: "http" ハンドラーを使えば、Slack・Discord・任意のウェブフックに POST リクエストを送ることができます。

フックとmodの違い

v2.1.287で追加されたmod（Claude Mods）は、設定ファイルのフックと違い、Claude Codeの中で動く関数として出来事を書き換えたり、画面に表示を出したりできます。違いと使い分けは次の記事で解説しています。

Claude Codeの「mod（Claude Mods）」とは？できること・作り方・安全に使うための注意点を解説

まとめ

Claude Code Hooks は、AI コーディングアシスタントを「便利なアシスタント」から「確実に動く自動化パートナー」へと昇格させる機能です。

21種類のイベントでライフサイクルのあらゆる場面をカバー
4種類のハンドラー（command・http・prompt・agent）で柔軟な自動化
確定的な実行により、AIの”うっかり”をゼロに
チーム共有で全員が同じ品質基準を維持

まずは PostToolUse で自動フォーマットを設定するだけでも、日々の開発体験が大きく向上します。ぜひ試してみてください。

参考リンク

最終更新：2026年4月

■ゼロから始めるClaudeCode講座のご案内

テックジム東京本校では「ClaudeCode」の体験講座を開催。
「その日のうちに動かす」をゴールに、環境構築から実践まで。
毎週土曜日15時。参加は無料です。対面・ハンズオンだから初心者でも安心。

Claude Code 無料講座｜初心者向け・東京で学べる対面講座【毎週開催】

Claude Codeそのものの全体像はClaude Codeとは何か・何ができるのかで解説しています。記事を読んだうえで実際に手を動かしたい方は、テックジムが毎週開催している毎週開催のClaude Code無料講座をご利用ください。初心者向けの対面講座で、費用はかかりません。

プログラミング学習に関するお役立ちコンテンツ

カテゴリー: コラム