Claude Code Hooksとは?使い方を解説

Rebecca Kovács

Rebecca Kovács

2 7月 2025

Claude Code Hooksとは?使い方を解説

Vibe Codersにとって、AnthropicのClaude Codeのようなツールは、開発者がプロジェクトを記述、デバッグ、管理する方法を変革しています。Claude Codeは、ターミナル内で動作する「エージェント型コーディングツール」として機能し、コードベース全体を理解し、ファイルシステムと対話し、コマンドを実行し、さらにはドキュメントのためにウェブを閲覧することも可能です。自然言語プロンプトを通じて、新機能の作成、バグ修正、コードのリファクタリングといったタスクに優れています。

しかし、大規模言語モデル(LLM)の核となる特性は、その確率的な性質です。これにより創造的な問題解決が可能になる一方で、時には予測不可能性につながることもあります。ファイル変更後のリンティングや新機能記述後のテスト実行など、特定のアクションを毎回確実に実行したい場合があります。LLMが毎回これを記憶して実行することに頼ると、一貫性がなくなる可能性があります。

ここでClaude Code Hooksが登場します。フックは、Claude Codeの動作を確定的かつプログラム的に制御する強力な機能であり、LLMが実行を選択するのではなく、特定のアクションが常に実行されるように保証します。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか?

API仕様から正確なコードを生成できるApidog MCP Serverをお試しください!
ボタン

この記事は、Claude Code Hooksを理解し、設定し、活用して、完全に自動化され、合理化された開発ワークフローを作成するための包括的なガイドとして機能します。

Claude Code Hooksとは?

その核となるClaude Code Hooksは、Claude Codeのライフサイクルの特定の時点で自動的に実行される、ユーザー定義のシェルコマンドです。これらは、特定のアクションの前後に起動するように設定できるトリガーとして機能し、独自のカスタムロジック、スクリプト、コマンドをClaudeの操作に直接注入することを可能にします。

フックは、AI駆動型アシスタンスとルールベースの自動化の間のギャップを埋めます。これにより、標準を強制し、反復的なタスクを自動化し、外部ツールをワークフローに完全に信頼性をもってシームレスに統合することができます。

フックをトリガーできる主要なライフサイクルイベントは4つあります。

  1. PreToolUse: Claudeが特定のツールを使用するに実行されます(例:ファイルに書き込む前)。
  2. PostToolUse: ツールが正常に使用されたに実行されます(例:ファイルが変更された後)。
  3. Notification: Claudeが通知を送信するたびに実行されます(例:ユーザー入力が必要な場合や、時間のかかるタスクが完了した場合)。
  4. Stop: Claudeが応答の生成を終了し、停止したときに実行されます。

これらのイベントをターゲットにすることで、継続的インテグレーション(CI)チェックのような最新のソフトウェア開発のベストプラクティスを反映しつつ、ローカル開発の速度で強力な自動化を作成できます。

Claude Code Hooksの構造:設定の詳細

フックを使用するには、Claude Codeの設定ファイルでそれらを定義する必要があります。これは、プロジェクト内の.claude/ディレクトリにあるsettings.tomlファイルに[[hooks]]テーブルを追加することで行います。各フックの設定には、いくつかの主要なコンポーネントがあります。

# .claude/settings.toml のフック例

[[hooks]]
# フックをトリガーするイベント。
event = "PostToolUse"

# (オプション) フックを実行するための条件。
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# 実行するシェルコマンド。
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (オプション) コマンドをバックグラウンドで実行するかどうか。
run_in_background = false

各部分を詳しく見ていきましょう。

Claude Code Hooksのeventフィールド(必須)

この文字列は、4つのライフサイクルイベントのうち、どのイベントがフックをトリガーするかを指定します。

Claude Code Hooksのhooks.matcher(オプション)

マッチャーは、フックがいつ実行されるべきかを正確に定義することを可能にします。マッチャーを省略した場合、フックは指定されたeventのすべてのインスタンスに対して実行されます。例えば、マッチャーのないPostToolUseフックは、すべてのツール呼び出しの後に起動します。

マッチャーには、イベントをフィルタリングするために使用できる3つのフィールドがあります。

Claude Code Hooksのcommandフィールド(必須)

これはフックの核心であり、トリガー条件が満たされたときに実行されるシェルコマンドです。このコマンドは、ユーザーアカウントと同じ権限で実行されるため、ターミナルでできることなら何でも実行できます。

コマンドを動的にするために、Claude Codeはフックをトリガーしたイベントのコンテキストで埋められた一連の環境変数を提供します。

利用可能な環境変数:

Claude Code Hooksのrun_in_background設定(オプション)

これはブール値(trueまたはfalse)です。trueに設定すると、フックのコマンドは別のプロセスで実行され、Claudeは完了を待たずに続行します。これは、Claudeのその後のアクションをブロックしたくない、包括的なテストスイートやビルドプロセスのような時間のかかるタスクに最適です。デフォルトはfalseです。

Claude Code Hooksの実用的なユースケースと例

フックの真の力は、実際の開発ワークフローに適用したときに明らかになります。ここでは、始めるのに役立ついくつかの実用的な例を紹介します。

1. Claude Code Hooksによる自動リンティングとフォーマット

プロジェクト全体で一貫したコードスタイルを自動的に強制します。このフックは、Claudeが編集するすべてのPythonファイルに対してruffリンターとblackフォーマッターを実行します。

ファイル: .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# 編集されたPythonファイルをリンティング、修正、フォーマットするコマンド。
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. Claude Code Hooksによるテストの自動実行

テスト駆動開発(TDD)の核となる実践は、テストを記述し、次にそれらのテストをパスするコードを記述し、すべてが機能するまで反復することです。フックを使用して「テスト実行」ステップを自動化できます。この例では、src/またはtests/ディレクトリ内のファイルが変更されるたびにpytestを実行します。

ファイル: .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # テストは遅くなる可能性があるため、バックグラウンドで実行します。

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# テストスイートを実行するコマンド。
command = "pytest"

3. Claude Code Hooksを介したカスタムデスクトップ通知

Claudeに時間のかかるタスクを実行するよう依頼した場合、コンピューターから離れることがあるかもしれません。このフックは、ntfy(シンプルなHTTPベースのpub-sub通知サービス)のようなコマンドラインツールを使用して、Claudeがあなたの注意を必要とするときに、スマートフォンやデスクトップにプッシュ通知を送信します。

ファイル: .claude/settings.toml

[[hooks]]
event = "Notification"

# 通知コンテンツを公開のntfy.shトピックに送信します。
# プライバシーのために自分でホストすることもできます。
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. Claude Code Hooksを使用したコミット前の健全性チェック

Gitフックと非常によく似ていますが、Claude Code Hooksを使用して、コミットが行われるに品質を確保できます。この例では、Claudeがgit_commitツールを使用することを許可される直前に、APIキーのチェックやその他の検証ステップを実行するカスタムスクリプトを実行します。

ファイル: .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# コミット前チェックスクリプトを実行するコマンド。
# スクリプトは、コミットを停止するためにゼロ以外のコードで終了する必要があります。
command = "sh ./.claude/pre-commit-checks.sh"

Claude Code Hooksのセットアップとデバッグ

フックの開始は簡単ですが、期待どおりに機能することを確認するには、検証とデバッグが重要です。

  1. 設定を作成する: プロジェクトのルートディレクトリに.claude/settings.tomlファイルがあることを確認してください。そこに[[hooks]]設定を追加します。
  2. 設定を確認する: settings.tomlファイルを保存した後、Claude Codeターミナルインターフェース内で/hooksコマンドを実行します。この特殊なコマンドは、現在ロードされているフック設定を表示し、Claudeがそれらを正しく解析したかどうかを即座に確認できるようにします。
  3. エラーを確認する:

結論:Claude Code Hooksの力

Claude Code Hooksは、このツールを非常に有能なコーディングアシスタントから、完全に統合された決定論的な開発パートナーへと高めます。シンプルで強力なルールを定義することで、ワークフローの平凡でありながら重要な部分を自動化し、ソフトウェアエンジニアリングの複雑で創造的な側面に集中できるようになります。コード品質の強制、TDDループの簡素化、サードパーティサービスとの統合など、フックはClaude Codeをあなたの正確なニーズに合わせて調整するために必要な堅牢なフレームワークを提供します。

Claude Codeの機能に慣れてきたら、シンプルなフォーマットフックから始めて、より複雑な自動化を試してみてください。この機能が、予測可能で効率的、そして真にパーソナライズされたAI支援開発環境を構築するために不可欠であることがすぐにわかるでしょう。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか?

API仕様から正確なコードを生成できるApidog MCP Serverをお試しください!
ボタン

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる