Claude Code Hooks：ワークフロー自動化の実践ガイド

Claude Code を使っていると、よくある問題に気づくはずです。コードはうまく書くのに、フォーマット、テストの実行、セキュリティ手順の順守といった重要なステップを忘れてしまうことがあります。毎回同じ注意を繰り返す羽目になります。 Claude Code Hooks を使えば、ワークフローの特定のタイミングでシェルコマンドを自動実行し、こうしたリマインドを自動化できます。

このチュートリアルでは、コード整形、テスト実行、通知、ファイル保護のためのフック設定方法を解説します。手作業なしで開発基準を徹底できる自動化システムを構築しましょう。

Claude Code についてさらに学ぶには、Claude Code のベストプラクティスガイドや Claude Skills のチュートリアルをご覧ください。プロジェクト単位の指示を設定する方法は、CLAUDE.md の書き方ガイドを参照してください。

TL;DR

• Claude Code Hooks は、Claude Code のライフサイクルの特定ポイント（ツール呼び出しの前後、セッション開始時、Claude 停止時）で自動実行されるシェルコマンドです

• プロジェクトは .claude/settings.json、グローバルは ~/.claude/settings.json に、イベント・マッチャ・コマンドを含む JSON で設定します

• PreToolUse フックで、危険な操作を実行前にブロックできます（終了コード 2 = ブロック）

• PostToolUse フックで、Claude がコードを書いた後のフォーマット、リンティング、テスト実行などの後処理を行います

• フックは stdin で JSON コンテキストを受け取り、終了コード・stdout・stderr を通じて結果を通知します

Claude Code Hooks とは？

Claude Code Hooks は、AI コーディングセッション中の特定イベント発生時に自動実行されるシェルコマンドです。カスタムスクリプトを、—Claude がファイルを書く前後や、通知を送るタイミングなど、正確な瞬間に実行するトリガーのようなものだと考えてください。

この仕組みは、Claude Code の動作を監視し、設定ファイルで定義したルールに照らして照合します。一致したとき、直前に起きたことのコンテキストを受け取って指定コマンドが実行されます。これにより Claude の挙動をコントロールし、本来は手作業が必要な繰り返し作業を自動化できます。

以下は、Claude が Python ファイルを書くたびにコードフォーマッタを実行する基本的なフックです。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black ."
          }
        ]
      }
    ]
  }
}

このフックは 3 つの要素で構成されています。

• イベント: PostToolUse（Claude のアクション完了後）

• マッチャ: Write（ファイル書き込み時のみ）

• コマンド: python -m black .（カレントディレクトリの Python ファイルを整形）

フックは、スクリプトの入力に送られる JSON データを通じて、Claude が直前に行った操作の詳細情報を受け取ります。これにより、特定のファイル変更に応じた高度な自動化が可能になります。

Claude Code の自動化をさらに進めたい場合は、フックやエージェントをクラウドで定期実行する方法を解説した Claude Code Routines のチュートリアルをご覧ください。

それでは、フックを一から作成して Claude Code に登録する方法を見ていきます。

前提条件

始める前に、次の準備が必要です。

• Claude Code のインストールと起動：Claude Code を基本的なコーディング作業に使えるようになっていること

• コマンドラインの基礎：フックはシェルコマンドを実行するため、OS に応じた基本的なターミナルコマンドの知識が必要です

• テキストエディタ：フック設定のために JSON 構成ファイルを編集します

• プロジェクトディレクトリ：重要な作業に影響を与えずフックを安全に試せるコーディングプロジェクト

シェルスクリプトの達人である必要はありませんが、ls、cd、基本的なファイル操作などのコマンドの理解があると例に沿って進めやすくなります。 bash やターミナルが初めてであれば、Introduction to Shell コースをおすすめします。

Claude Code Hooks の始め方

フックの概要が分かったところで、最初の自動化を設定してみましょう。ニーズに合ったイベントを選び、簡単なルールを設定し、基本的なコマンドでテストする手順です。

フックイベントを理解する

Claude Code には 25 以上のフックイベントがあります。以下の表では、特によく使う 10 個を取り上げます。全リストは公式フックリファレンスを参照してください。

PreToolUse と PostToolUse が最も一般的です。PreToolUse は、ファイルの書き込みやコマンド実行などのアクション前に動作し、検証や危険な操作のブロックに適しています。PostToolUse はアクション完了後に動作し、コード整形やテスト実行などの後処理に向いています。

UserPromptSubmit は、プロンプトを送信したとき（Claude が処理を始める前）にトリガーされます。会話にコンテキストを追加したり、プロンプトが要件を満たしているか検証したりできます。

Notification は、コマンド実行の許可を求める、入力を求めるなどのアラートを Claude が送信した際に動作します。PermissionRequest は許可ダイアログの表示時に発火し、ユーザーに代わって自動承認・拒否が可能です。

Stop と SubagentStop は、Claude の応答が終了したときにトリガーされ、最終チェックやレポート作成に有用です。違いは、Stop が全体の応答完了時に発火するのに対し、SubagentStop はツールが起動したヘルパー（「サブエージェント」）の作業完了時に発火する点です。

残りの PreCompact、SessionStart、SessionEnd はライフサイクル特有の状況を扱います。PreCompact は会話履歴を短縮する直前に動作します。『SessionStart』は新しいセッションの開始時に発火し初期設定を行い、SessionEnd はセッション終了時に発火してクリーンアップや最終レポートに利用できます。

マッチャを理解する

マッチャは、どの Claude Code のアクションでフックを起動するかを決めるフィルタです。技術的には正規表現として解釈される文字列で、完全一致も柔軟なパターンも使えます。

最も関連性が高いのは、Write（ファイル書き込み時）や Edit（内容編集時）といったシンプルなもの、または Edit|Write のように複数アクションをカバーする組み合わせです。

また、Notebook.* のようなプレフィックスパターンで「Notebook.」から始まるツールすべてにマッチさせることも可能です。すべてのアクションでフックを起動したい場合は、汎用の正規表現 .*、空文字列（""）、または matcher を未指定にします。

マッチャは大文字小文字を区別し、アクション名にのみ作用します。可能な限り特定的に保つのが最適です。より細かく制御したい（例：特定のファイルタイプに限定したい）場合は、フックに渡される JSON ペイロードを読み取り、そこで独自の正規表現や条件を適用してください。

Claude Code で最初のフックを作成する

Claude Code では、対話的な /hooks コマンドと、設定ファイルを直接編集する方法の 2 通りでフックを設定できます。まずは初心者向けの対話的アプローチから始めましょう。

/hooks コマンドの使い方：

1. Claude Code を開き、チャットインターフェースで /hooks と入力します

2. トリガーイベントを選択します（この例では PostToolUse を選びます）

3. メニューから「Add new hook」を選択します

4. マッチャパターンを設定します（Write と入力してファイル書き込みを対象にします）

5. コマンドを入力します：

• Mac：say "Task complete"

• Windows：powershell -c [console]::beep()

• Linux：spd-say "Task complete"

6. 設定を保存し、Esc を 3 回押して Claude Code に戻ります

/hooks コマンドは設定ファイルを自動更新し、構成をリロードします。既存のフックを確認したり変更したりする際も、いつでも /hooks を使えます。

設定ファイルを直接編集する場合、フックはグローバル設定が ~/.claude/settings.json、プロジェクトディレクトリ内は .claude/settings.json（チーム共有フックとしてリポジトリにコミット）、個人用は .claude/settings.local.json（既定で .gitignore 済み）にあります。 先ほどの例は次のようになります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Task complete'"
          }
        ]
      }
    ]
  }
}

ファイルを手動で編集した後は、Claude Code を再起動するか、/hooks コマンドで構成をリロードしてください。これで Claude がファイルを書くたびに音声通知が鳴るようになります。

フックをテストする

先に進む前に、フックが実際に動作することを確認しましょう。

1. Claude に任意の Python ファイルの作成を依頼します（例：「hello.py を作成して hello world を出力して」）

2. 書き込み処理が完了すると音声通知が聞こえるはずです

3. 何も聞こえない場合は、Ctrl-O を押して Claude Code のトランスクリプトを開き、エラーメッセージを確認します

4. よくある原因は、フックコマンドが見つからない、ファイル権限の誤り、設定ファイルの文法エラーなどです

この基本テストが通れば、後で複雑なフックを作る際のデバッグ時間を節約できます。設定ファイルを手動編集した直後、マッチャやイベントを変更した直後、フックで使う新しいツールをインストールした直後などは、/hooks を開き直すか Claude を再起動して構成をリロードすると良いでしょう。

この基本パターン（イベント、マッチャ、コマンド）が、すべてのフック自動化の土台です。同じイベント発火時に同時実行するコマンドを複数追加することもできます。例えば、Claude がファイルを書いたときに音を鳴らすのと同時にバックアップを作成する、といった具合です。

同じイベント内でツールごとに別のマッチャを作成することもでき、ファイル書き込みとコード編集で異なるアクションを起動できます。同じツールパターンに一致するフックは並列で実行されます。同一イベントに複数のマッチャを設定した場合は、それぞれのマッチャがトリガーされたときに個別に動作します。

フック入力の扱い方

Claude Code がフックをトリガーすると、標準入力（stdin）を通じて直前に起きたことの情報を送ります。これはコマンド実行時に直接渡されるデータストリームです。任意のタイミングで走るスクリプトではなく、フックが強力な仕組みになるのはこのデータのおかげです。

Claude Code はこの情報を JSON としてパッケージ化し、設定したコマンド（シンプルな端末コマンドでもカスタムスクリプトでも）に渡します。

フック入力の構造

どのフックにも、現在のセッションに関する基本フィールドを持つ JSON オブジェクトが渡されます。

{
  "session_id": "abc123",
  "transcript_path": "/Users/you/.claude/projects/my-project/conversation.jsonl", 
  "cwd": "/Users/you/my-project",
  "hook_event_name": "PostToolUse"
}

各要素の意味は次のとおりです。

• session_id：現在の会話を識別

• transcript_path：会話履歴へのパス

• cwd：作業ディレクトリ

• hook_event_name：どのイベントが発火したか

このコンテキストがあれば、どの会話がアクションをトリガーしたかを追跡し、必要に応じてチャット履歴全体にアクセスしたり、正しいディレクトリでコマンドを実行したりできます。

イベント別の入力の違い

PreToolUse や PostToolUse のようなツールイベントには、アクションの詳細が追加されます。ここが自動化で特に有用になるポイントです。PreToolUse では tool_input が、PostToolUse ではさらに tool_response が含まれます。

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.py",
    "content": "print('Hello world')"
  },
  "tool_response": {
    "filePath": "/path/to/file.py", 
    "success": true
  }
}

フック入力では、file_path に書き込み・編集対象のファイルパスが、content にツールが書き込もうとしている正確なテキストが含まれます。実行後、ツールの応答では実際に触れたファイルの最終的な filePath（キャメルケースに注意）と、処理が正しく完了したかを示す success フラグが返ります。

この詳細情報により、実際の内容に応じてフックの挙動を変えられます。Python ファイルだけ整形する、重要なディレクトリだけバックアップする、特定のファイルタイプが変更されたときだけ通知を送る、などが可能です。

UserPromptSubmit のようにツールを伴わないイベントは、よりシンプルです。

{
  "session_id": "abc123",
  "hook_event_name": "UserPromptSubmit", 
  "prompt": "Write a function to calculate factorial"
}

UserPromptSubmit フックは設定にマッチャを使いません。ツール操作ではなく、すべてのプロンプトで発火します。会話のログ取得、プロジェクトコンテキストの自動追加、Claude による処理前のプロンプト検証に最適です。

実践的な入力の読み取り

ユーザープロンプトをすべて記録するフックを作ってみましょう。これは、特に長いコーディングセッションで、Claude に何を依頼したか分からなくなる問題の解決に役立ちます。まずフックの設定です。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/log_prompts.py"
          }
        ]
      }
    ]
  }
}

次に、~/.claude/log_prompts.py に以下の Python スクリプトを作成します。

#!/usr/bin/env python3
import json
import sys
from datetime import datetime

# Read JSON data from stdin
input_data = json.load(sys.stdin)

# Extract information
session_id = input_data.get("session_id", "unknown")
prompt = input_data.get("prompt", "")
timestamp = datetime.now().isoformat()

# Log the prompt
log_entry = f"{timestamp} | Session: {session_id[:8]} | {prompt}\n"
with open("prompt_history.txt", "a") as f:
    f.write(log_entry)

このスクリプトは、Claude Code が送る JSON データを読み取り、セッションのコンテキストとともにプロンプトを記録します。やり取りの履歴を検索可能にでき、数週間後に問題解決の経緯を振り返る際に大いに役立ちます。

フック出力の扱い方

フックのコマンド実行後は、何が起きたか、通常どおり続行すべきかを Claude Code に伝える必要があります。この制御機構によって、単なるログ収集から、Claude の挙動を導く強力なワークフロー自動化へと発展します。これには標準出力（stdout）、標準エラー（stderr）、終了コードの 3 つのチャネルを使います。

出力チャネルと終了コード

標準出力（stdout）は通常の出力です。たとえば print した内容は stdout に送られます。多くのフックでは、Ctrl-O で開ける Claude Code のトランスクリプトに表示され、メイン会話を煩雑にせず自動化の実行ログを残せます。

標準エラー（stderr）はエラーメッセージ用です。stderr への書き込みは以下のように行えます。

• Python：print("message", file=sys.stderr)

• コマンドライン：echo "message" >&2

重要な違いとして、stderr は Claude に直接送られ自動処理されます。これにより、フックが検知した問題に Claude が対応できます。

終了コードは、次に何をすべきかを Claude Code に伝えます。

• 終了コード 0：成功（stdout をユーザーに表示）

• 終了コード 2：ブロックすべきエラー（stderr を Claude に送信）

• その他のコード：ブロックしないエラー（stderr をユーザーに表示しつつ継続）

この仕組みにより、Claude を停止させる・続行させる・自動化の発見事項をフィードバックする、という細やかな制御が可能です。ここでは重要な 2 つの終了コードの例を見ていきます。

終了コード 0：通常動作

多くのフックは、すべてが正常であることを示す終了コード 0 を使います。以下はファイル操作を記録し、ユーザーに通知する完全なフックです。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import datetime; open('activity.log','a').write('File written: ' + datetime.datetime.now().isoformat() + '\\n'); print('Logged file operation')\""
          }
        ]
      }
    ]
  }
}

このフックは、ファイルへのログ追記と、トランスクリプトへのメッセージ出力という 2 つの処理を行います。方法はいくつもありますが、このアプローチはクロスプラットフォームで、コマンドライン固有の挙動に依存しません。

明示的な終了コードがない場合は 0 が既定です。出力したメッセージは Claude Code のトランスクリプトに表示され、ロギングが成功したことを確認できます。変更履歴の監査や、Claude がプロジェクトに加えた変更を時系列で追跡する用途に最適なパターンです。

終了コード 2：ブロックとフィードバック

終了コード 2 はエラーメッセージを Claude に直接送信し、自動応答を促します。ここから、フックは単なる自動化ではなく安全装置として機能します。以下は危険なファイル操作をブロックするフックです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/security_check.py"
          }
        ]
      }
    ]
  }
}

次に、~/.claude/security_check.py にセキュリティチェック用スクリプトを作成します。

#!/usr/bin/env python3
import json
import sys

# Read hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Check for dangerous patterns
dangerous_paths = ["/etc/", "/usr/", "production.conf"]
is_dangerous = any(pattern in file_path for pattern in dangerous_paths)

if is_dangerous:
    # Block the operation and tell Claude why
    print(f"Blocked modification of {file_path} - this appears to be a system or production file", file=sys.stderr)
    sys.exit(2)  # Sends stderr message to Claude
else:
    # Allow the operation
    print(f"Approved modification of {file_path}")
    sys.exit(0)  # Shows stdout in transcript

このフックが危険なパスを検知すると、終了コード 2 で終了します。Claude Code は stderr のメッセージを Claude に送り、なぜブロックされたかの説明や代替案の提案が返されます。こうしてシステムファイルの誤操作を防ぎつつ、セキュリティポリシーを Claude に周知できます。

Claude Code のスマート通知フックを作る

入力処理と賢い出力制御を組み合わせた改良版の通知フックを作りましょう。これは、すべてのファイル変更で通知が鳴ってノイズになるという元の問題を解決します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/smart_notify.py"
          }
        ]
      }
    ]
  }
}

~/.claude/smart_notify.py に通知スクリプトを作成します。

#!/usr/bin/env python3
import json
import sys
import os
import subprocess

# Read the hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Categorize file importance
important_extensions = [".py", ".js", ".ts", ".java", ".cpp"]
config_files = ["Dockerfile", "requirements.txt", "package.json"]

is_code = any(file_path.endswith(ext) for ext in important_extensions)
is_config = any(filename in file_path for filename in config_files)

if is_code:
    # Important: notify and log
    print(f"Code file modified: {os.path.basename(file_path)}")
    subprocess.run(["say", "Code updated"], check=False)  # Mac
    sys.exit(0)  # Show message in transcript
elif is_config:
    # Very important: louder notification
    print(f"Configuration file changed: {os.path.basename(file_path)}")
    subprocess.run(["say", "Configuration updated - review changes"], check=False)
    sys.exit(0)
else:
    # Not important: silent success
    sys.exit(0)

このフックは、変更されたファイルを読み取り、その種類に基づいて通知の重要度を判断します。重要な変更は stdout に記録し、ファイルタイプごとに異なる音声アラートを発し、いずれも情報目的のため終了コードは常に 0 です。

入力解析と出力制御の組み合わせにより、コンテキストに応じて賢く振る舞い、ユーザーと Claude Code の双方に適切なフィードバックを提供するフックが実現します。一時ファイルのような変更で不必要に通知される代わりに、プロジェクトにとって本当に重要な変更だけを知らせます。

なお、この例では macOS の say コマンドを使用しています。Linux では notify-send、Windows では PowerShell コマンドなどで同様の通知を実現できます。

Claude Code Hooks の落とし穴

初週によくつまずくポイントをいくつか紹介します。

シェルのプロファイルでの echo がフックを壊す。 フックは非対話型シェルで実行されますが、~/.zshrc や ~/.bashrc を読み込みます。プロファイルに無条件の echo があると、フックの stdout の先頭にテキストが付与され、JSON パースが壊れます。対話型シェルのときだけ出力する条件で囲んでください。

if [[ $- == *i* ]]; then
  echo "Welcome back"
fi

Stop フックは無限ループになることがある。 Stop フックが終了コード 2 を返すと、Claude は作業を続けようとします。スクリプトが入力 JSON の stop_hook_active を確認し、true のときに正しく終了しないと、タイムアウトまで回り続けます。必ず早期リターンのガードを入れてください。

マッチャは大文字小文字を区別する。 bash は Bash に一致しません。Claude Code に表示される正確なツール名を使ってください。

出力は 10,000 文字で上限。 それ以上を生成すると、Claude のコンテキストに取り込まれる前に切り捨てられます。stdout は簡潔にし、モデルが行動するのに必要な情報だけを出しましょう。

チーム用フックと個人用フックの取り違え。 .claude/settings.json のフックはチーム共有（リポジトリにコミット）です。共有したくない個人用フックは .claude/settings.local.json を使います（既定で gitignore 済み）。

Hooks と Skills：使い分けの指針

フックと Claude Skills は目的が異なり、併用が最適です。Skill は Markdown ファイルで、手順・規約・テンプレートなどを通じて Claude にやり方を教えます。Hook は、Claude の判断に関係なく規則を確実に実行させるシェルコマンドです。

違いは重要です。Skill はモデルが状況次第で無視することもある「提案」です。一方で Hook は毎回必ず発火します。チームの移行手順を文書化するには Skill を。Claude が書くすべての .sql に対して移行リンタを走らせるには PostToolUse の Hook を。Skill は Claude を有能にし、Hook は Claude に責任を持たせます。

Claude Code Hooks の発展的パターン

基本的な通知やロギングを超えて、フックはチームが日常的に直面する開発ワークフローの課題を解決できます。自分のプロジェクトに合わせて応用できるアイデアを紹介します。

ありがたいことに、実際にはこれらのフックを手作業で作らなくても構いません。以下のプロンプト案のいずれかを Claude Code に与え、あわせてHooks リファレンスを渡せば、関連するコードと設定用 JSON を生成してくれます。

各パターンは、ツールやワークフローに合わせてカスタマイズ可能です。まずは日々の最大の不満を解消するものから始め、フック開発に慣れてきたら自動化を広げていきましょう。

セキュリティとコンプライアンス向けの高度なフック

フックはセキュリティルールやコンプライアンス基準の徹底に最適です。代表的な 4 つの用途を挙げます。

API キースキャナ

• 課題：機密情報を誤ってバージョン管理にコミットしてしまう

• トリガー：任意のファイルを書き込む前

• 解決策：正規表現で API キー、トークン、パスワードをファイル内容から検出

「フック入力の JSON を読み取り、ファイル内容を抽出して、api_key=、token:、password= など一般的な秘密情報の形式を正規表現で検出する Python スクリプトを作成してください。疑わしい一致があった場合はローカルで検証し、絶対に生の秘密情報を外部に送らないでください。マスクした抜粋（先頭・末尾 4 文字のみ保持）やハッシュだけを Anthropic API に送り、疑わしい文字列が実際の秘密か変数名かを判定します。終了コード 2 で終了し、検出内容と安全な代替方法を Claude にフィードバックします。」

ライセンスヘッダー強制

• 課題：OSS プロジェクトで新規ファイルに必要なライセンスヘッダーが欠落

• トリガー：ソースコードファイルを書き込む前

• 解決策：新規 .py、.js、.java に正しいライセンス文言があるか検証

「フック入力を解析してファイル内容を取得し、先頭 10 行にライセンス文言が含まれるかを文字列マッチで確認します。より高度な検証が必要なら、ファイルヘッダーを Anthropic API に送り、著作権表記とライセンス情報が正しいか確認します。ヘッダーが欠落している場合は終了コード 2 で作成をブロックし、Claude に正しいライセンスのテンプレートを提示させます。」

本番ファイルガード

• 課題：重要なシステム設定ファイルを誤って変更してしまう

• トリガー：機微なディレクトリ内のファイルを編集する前

• 解決策：/etc/、nginx.conf、database.yml など重要設定の変更をブロック

「フック入力 JSON からファイルパスを抽出し、/etc/、production.yml などのパターンに一致するか確認します。Claude の API を使ってファイルパスを分析し、本番システムに影響しうる設定ファイルかどうかを判断します。危険なパスを検出したら終了コード 2 で終了し、安全な開発手順に関する具体的なガイダンスを提供します。」

画像最適化

• 課題：大きな画像ファイルがアプリやリポジトリを遅くする

• トリガー：新しい画像ファイルの追加後

• 解決策：PNG/JPEG を画質を保ったまま圧縮

「フック入力からファイルパスを取得し、拡張子で画像かどうかを判定します。imageoptim のような圧縮ツールを実行するか、TinyPNG API を呼び出して画質を保ったまま圧縮します。圧縮結果は stdout に記録し、Claude のトランスクリプトでファイルサイズの削減量を確認できるようにします。」

バージョン管理自動化の高度なフック

Git のワークフローやドキュメント整備でもフックは有用です。いくつかのアイデアを見ていきましょう。

Git ブランチバリデータ

• 課題：保護ブランチに誤って変更をプッシュしてしまう

• トリガー：任意のファイル書き込み・編集前

• 解決策：現在の Git ブランチを確認し、main/master/production では操作をブロック

「git branch --show-current のような簡単な bash コマンドで現在のブランチ名を取得し、保護ブランチのリストと比較します。保護ブランチにいる場合は終了コード 2 で終了し、ブランチ保護ポリシーを説明するエラーメッセージを Claude に送ります。ブランチ名の規則が複雑な場合は、Claude の API を使ってブランチ名を分析し、保護パターンに一致するか判定します。」

スマート自動コミット

• 課題：コミットを忘れる、または不十分なコミットメッセージを書く

• トリガー：任意のファイル変更後

• 解決策：変更を自動ステージング・コミットし、AI で要約した説明的メッセージを付与

「フック入力から変更ファイルのパスを読み取り、git diff で差分を取得して、Claude の API に簡潔なコミットメッセージを依頼します。生成したメッセージを使って git add と git commit を実行し、変更を自動コミットします。API へのプロンプトにはファイル名や変更種別も含め、Conventional Commits に沿ったメッセージになるよう促します。」

ドキュメント自動生成

• 課題：API ドキュメントがコード変更に追随しない

• トリガー：インターフェースファイル（コントローラ、モデル、API）の変更後

• 解決策：JSDoc、Sphinx、OpenAPI などのドキュメンテーションツールを自動実行

「変更ファイルのパスをチェックし、API エンドポイント、モデル、インターフェースかをパターンマッチで判定します。ファイル内容を Claude の API に送り、API 変更点の抽出とドキュメント更新の生成を依頼します。適切なドキュメンテーションツール（jsdoc、sphinx-build など）を実行し、更新されたドキュメントを自動コミットします。」

コラボレーションとワークフロー統合の高度なフック

最後に、チーム全員の最新状況を保つのにもフックは役立ちます。

Slack 連携

• 課題：共有コードベースの重要な変更をチームが把握できない

• トリガー：重要な操作に対する通知の送信時

• 解決策：ファイル名と変更概要を含む整形メッセージをチャンネルに投稿

「フック入力からファイル情報を抽出し、ソースコードや設定ファイルなど重要な種類にフィルタします。ファイル名や種類に基づいて、何が変わったのかを人間が読みやすい要約にするよう Claude の API に依頼します。Webhook URL を使って Slack に整形メッセージを送り、重大な変更ではメンションを付けます。」

Webhook ディスパッチャ

• 課題：手動の CI/CD トリガーがデプロイを遅らせる

• トリガー：特定のイベント発生時（設定変更、デプロイ関連ファイルの変更）

• 解決策：外部 API を呼び出してビルドやデプロイなどの自動処理をトリガー

「Dockerfile、package.json、デプロイ設定などのパターンにファイルパスが一致するかを確認し、CI/CD を起動すべきか判断します。Python の requests ライブラリで、認証ヘッダーと変更情報のペイロードを含む Webhook を呼び出します。外部システムが何をビルド・デプロイすべきか賢く判断できるよう、ファイルパスや変更メタデータをペイロードに含めます。」

ステータスページ更新

• 課題：メンテナンスやデプロイ作業が顧客に伝わらない

• トリガー：デプロイやインフラ関連ファイルの変更時

• 解決策：サービスのステータスページにメンテナンス通知を更新

「Kubernetes マニフェストや Terraform 設定などインフラファイルの変更を、ファイルパスのパターンで検出します。検出したインフラ変更の種類に応じて、Claude の API を使ってメンテナンス通知文を生成します。StatusPage.io や PagerDuty などの REST API を用い、適切なインシデント種別と想定時間を設定してステータス更新を投稿します。」

チームステータス通知

• 課題：複数の開発者が同じ機能に並行して取り組み、衝突が起きる

• トリガー：新しい Claude Code セッションの開始時

• 解決策：特定プロジェクトやコンポーネントに取り組み始めたことをチームに通知

「フック入力からプロジェクトディレクトリを読み取り、最近のファイルや git 履歴を分析して作業内容を把握するよう Claude の API に依頼します。氏名、プロジェクト名、フォーカス領域を含む整形メッセージをチームのコミュニケーションチャンネルに送信します。想定作業時間を含め、関連機能に取り組んでいるメンバーへの調整を呼びかけます。」

まとめ

Claude Code Hooks を使えば、予測しづらい AI コーディングアシスタントを、必要なときに正確に動く自動化ワークフローへと変えられます。本チュートリアルでは、対話的な /hooks コマンドと手動設定の両方でフックを構築する方法、知的な自動化を支える JSON 入力データの理解、終了コードと構造化出力による Claude の挙動制御を学びました。

取り上げた実践パターンには、危険な操作をブロックするセキュリティ検証や、ノイズを減らすスマート通知が含まれます。これらは、AI アシスタントを完全にコントロールしつつ、実際の開発上の課題を解決する方法を示しています。基礎を理解した今、チームのワークフローに合った自動化を自由に構築していきましょう。

AI ツールの活用についてさらに学ぶには、DataCamp の Understanding Prompt Engineering コースをご覧ください。フック開発と直結するプロンプト戦略を取り上げています。より広範な AI コーディングスキルには、 Intermediate ChatGPT コースもおすすめです。AI アシスタントを信頼できる開発パートナーにするスキルを身につけましょう。