「日々のコーディング、もっと楽にならないかな…」
「手作業によるミスを減らして、開発に集中したい」
開発者なら誰もが一度はこう考えた経験があるのではないでしょうか。この非効率な状況を打破してくれたのが、Claude Codeのhooksという機能です。
この記事では、そんな私の実体験を交えながら、Claude Codeのhooksについて徹底的に解説します。
この記事を読み終えるころには、あなたもClaude Codeのhooksの基本をマスターし、日々の退屈な作業を自動化して開発効率を飛躍的に向上させる第一歩を踏み出せるはずです。
Claude Codeのhooksとは？
Claude Codeのhooksは、特定のイベントが発生したタイミングで、あらかじめ設定しておいたスクリプトやコマンドを自動的に実行する仕組みです。
例えば、「コードがリポジトリにプッシュされたら」や「新しいプルリクエストが作成されたら」といったイベントをきっかけ（トリガー）に、さまざまな処理を自動で動かせます。
hooksの役割と仕組み
hooksの最大の役割は、開発ワークフローの自動化です。
釣りで魚を「フック」にかけるように、Gitの操作などの特定のイベントに処理を引っかけて自動実行させます。開発者が手動で行っていた作業をClaude Codeが肩代わりしてくれるんです。
仕組みは開発者が設定ファイルに、「いつ」「何をするか」を定義した設定ファイルと実行スクリプトを置くだけ。あとはClaudeCodeがイベントを監視し、条件に合致したタイミングでスクリプトを実行してくれます。
なぜhooksが必要なのか
hooksが必要な理由は、主に3つあります。
Claude Codeにおけるhooksの位置づけ
Claude Codeのプラットフォームにおいて、hooksはCI/CDパイプラインを支える重要な機能です。
GUIで設定する複雑なパイプラインとは異なり、コードベースで手軽に自動化を導入できるのが大きな特徴。小規模なチェックから本格的なデプロイフローまで、幅広い用途に対応できる柔軟性を持っています。まさに、開発者のかゆいところに手が届く機能といえるでしょう。
hooksの使い方【基本編】
ここからは、実際にClaude Codeでhooksを使うための基本的な手順を解説します。
hooksを設定する手順
- 以下の設定ファイルを作成する
.claude/settings.json- 設定ファイルに “hooks” セクションを追加 たとえば、ファイル編集後に lint を走らせたいなら、以下のように書きます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "npm run lint"
}
]
}
]
}
}3. スクリプト本体（もし自作するなら）を用意・実行可能に
例えば ./.claude/hooks/pre-commit-check.shのようなスクリプトを作って、それを設定ファイルの command で呼び出します。
#! /bin/sh
echo "Lint & testsを実行します..."
npm run lint
npm test作成後に、
chmod +x .claude/hooks/pre-commit-check.shを実行して実行権限を付与します。
event
フック（hook）イベント の一覧と、それぞれの意味・使いどころです。もちろん「理論上はこう動く」までで、実環境ではバージョンや設定によって微妙に挙動が異なる可能性があります。
| イベント名 | いつ発火するか | 主な用途・補足 |
|---|---|---|
| PreToolUse | ツールを実行する直前（“tool call” を起こす前）に発動。 | ツールの実行を 制御する（ブロック・許可）ために使う。例えば「このディレクトリのファイルを編集しようとしてる？それ、大丈夫？」というチェックに。 |
| PostToolUse | ツールが 成功裏に終了したあと に発動。 | ツール実行後の “後片付け” や “フォーマット” や “ログ記録” に最適。実行を取り消すには遅いタイミングなので、「実行後のチェック・追加作業」が主。 |
| Notification | Claude Code がユーザーに通知を出す時（例：ユーザー入力を待った／ツール使用許可を求めた）に発動。 | 通知をカスタム化したり、デスクトップ通知・サウンド・ログを差し込んだり。 |
| UserPromptSubmit | ユーザーがプロンプト（質問・指示）を送信した 直後に発動、つまり Claude に処理される前。 | プロンプトの内容を検証したり、補足コンテキストを付加したり、特定タイプの入力をブロックしたり。 |
| Stop | メインの Claude Code エージェントが応答を終了したときに発動（ただし、ユーザー割り込み／中断による停止では発動しない）｡ | セッション終了時の “クリーンアップ” やログ書き出し、次のタスク起動などに。 |
| SubagentStop | “サブエージェント”（タスクとして起動された別インスタンス）終了時に発動。 | 例えば内部で複数のエージェントを並行実行しているとき、「このサブタスク終わったぞ」というタイミングで何かを挟む。 |
| PreCompact | Claude Code がコンテキストを圧縮（compact）しようとする直前に発動。 | セッション中の文脈（会話履歴）が大きくなってきたとき、自動で整理・圧縮される “compact” 処理に先立って何かを行う。 |
| SessionStart | 新しいセッションを開始する、または既存セッションを再開するタイミングで発動。 | プロジェクトのコンテキストロードとか、初期化処理、前回セッションの復元などに利用。 |
| SessionEnd | セッションが終わる（終了・クリア・ログアウトなど）ときに発動。 | セッション統計を書いたり、リソース解放したり、ログ出力など |
matcher
matcher は、フック設定内で「どのツール実行（またはどの条件）に対してこのフックを走らせるか」を指定するフィルターです。つまり「ツール名」「ツールの入力／出力」「ファイルパス」といった条件にマッチしていたら、該当フックが発動する、という仕組みです。
具体的には、以下のようなルールがあります
- matcher は主に PreToolUse／PostToolUse イベントのときに使われます。
- matcher に指定できる値としては ツール名の文字列（厳密一致）や、正規表現パターン（例：Edit|Write）が使えます。
- すべてのツールに対してフックを走らせたいときは matcher: "*" や空文字 "" で “無条件” に設定可能です。
いくつか matcher を使うときに押さえておくべき仕様ポイントがあります。
| キーワード | 説明 |
|---|---|
| ツール名一致（exact match） | 例えば matcher: "Write" と書けば「ツール名がちょうど Write のとき」に発動。 |
| 正規表現／複数候補 | `matcher: “Edit |
| ワイルドカード／空文字 | matcher: "*" や matcher: ""（もしくは matcher を省略）で「すべてのツール／条件」に適用可能。 |
| 大文字・小文字区別 | ドキュメントでは “case-sensitive (only applicable for PreToolUse and PostToolUse)” という記述あり。つまり “Write” と “write” は別扱い。 |
| 対象イベント限定 | matcher が意味を持つのは主に PreToolUse／PostToolUse のイベント。その他のイベント（例：Notification／UserPromptSubmit）では matcher を省略するか意味が少ない。 |
利用可能なツール名（matcher で指定する値）は、主に以下のようなものがあります。
| ツール名 | 説明 |
|---|---|
| Edit | ファイルの編集を行うツール。 |
| Write | ファイルへの書き込みを行うツール。 |
| Bash | シェルコマンドを実行するツール。 |
| Git | Git コマンドを実行するツール。 |
| Notebook | Jupyter Notebook などのノートブックツール。 |
| WebFetch | Web ページの情報を取得するツール。 |
| RunCommand | 任意のコマンドを実行するツール。 |
| EditFile | ファイルの編集を行うツール。 |
| WriteFile | ファイルへの書き込みを行うツール。 |
| GitCommit | Git のコミットを行うツール。 |
| RunCommand | 任意のコマンドを実行するツール。 |
type
typeで指定できるものは現状はシェルコマンドを実行するcommandのみ。将来的に増える可能性はあります。
例で理解するhooksの流れ
上記で設定したhooksのもう少し具体的なhooksの流れを見てみましょう。
- ユーザーの操作 ユーザーが Claude Code を使用してファイルを編集します。例えば、コードエディタで TypeScript ファイルを開いて内容を変更します。
- ツールの呼び出し Claude Code は内部で Edit ツールを使用して、編集されたファイルを処理します。
- フックのトリガー PostToolUse イベントが発生し、matcher が "Edit" に一致するため、設定されたフックが実行されます。
- コマンドの実行 フック内で指定されたコマンド（この場合は npm run lint）が実行されます。
- 結果の確認 npm run lint の実行結果がターミナルに表示され、コードの静的解析結果を確認できます。
hooksを活用した実践例
基本を理解したところで、次はより実践的なClaude Codeのhooks活用例を5つ紹介します。これらを参考に自動化を導入してみましょう。
自動通知
MacのCaude Codeの作業が完了した際に自動で通知音を送るhooksです。
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Funk.aiff"
}
]
}
]
}pre-commitでのlintとフォーマット実行
これは最も一般的で効果的なhooksの一つです。pre-commitフックを利用して、ESLintやPrettierといったツールを自動実行し、コーディング規約に沿わないコードがコミットされるのを防ぎます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "sh ./.claude/hooks/pre-commit-check.sh"
}
]
}
]
}
}.claude-hooks/pre-commit スクリプト例:
#!/bin/sh
echo "コードフォーマットとlintチェックを実行中..."
npm run format
npm run linthooksを使うときによくあるエラーと対処法
hooksは非常に便利ですが、設定でつまずくこともあります。ここでは、よくあるエラーとその対処法を紹介します。
hookが動かないときに確認すべきポイント
「設定したはずなのにhookが動かない…」というときは、まず以下の3点を確認しましょう。
ログで原因を特定する方法
問題が解決しない場合は、ログを確認するのが一番の近道です。
ClaudeCodeのダッシュボードには、各hooksの実行結果と出力ログが記録されています。ログを見れば、「どのコマンドでエラーが発生したのか」「どんなエラーメッセージが出力されたのか」が一目瞭然です。
また、スクリプト内でset -xコマンドを実行すると、どのコマンドが実行されているかを詳細にログ出力できるため、デバッグに非常に役立ちます。
hooks活用のベストプラクティス
最後に、Claude Codeのhooksをより安全かつ効果的に活用するためのベストプラクティスを紹介します。
安全にhooksを使うための設計指針
- フックは高速に保つ:
pre-commitのような開発者の操作をブロックするフックは、処理が数秒で終わるように設計しましょう。重い処理（例: E2Eテスト）は、バックグラウンドで実行されるpost-commitフックなどを利用するのがおすすめです。 - 冪等性（べきとうせい）を意識する: フックスクリプトは、何度実行しても同じ結果になるように作りましょう。これにより、予期せず再実行された場合でも問題が起きにくくなります。
- エラー処理を丁寧に行う: スクリプトが失敗した場合は、分かりやすいエラーメッセージを出力して処理を中断するようにします。これにより、問題の早期発見につながります。
開発効率を上げるhooksの組み方
- チームでhooksを共有する:
.claude-hooksディレクトリをGitの管理対象に含めることで、チーム全員が同じフックを利用できます。これにより、開発環境の差異による問題を減らし、チーム全体の生産性を向上させられます。 - 小さな自動化から始める: 最初から複雑なワークフローを組もうとせず、まずは「コードフォーマットの自動化」のような、簡単で効果の大きいものから導入してみましょう。成功体験を積み重ねることが大切です。
まとめ｜Claude Codeのhooksで自動化の幅を広げよう
この記事では、Claude Codeのhooksの基本から実践的な使い方、トラブルシューティングまでを網羅的に解説しました。
hooksの要点整理
- hooksとは: 特定のイベントをきっかけに、処理を自動実行する仕組み。
- 目的: ヒューマンエラーの防止、開発効率の向上、チーム開発の標準化。
- 使い方:
.claude-hooksディレクトリに実行権限を付与したスクリプトを置くだけ。 - 活用例: Slack通知、lint実行、自動テスト、デプロイの自動化など、用途は無限大。
hooksを使いこなせば、これまで手作業に奪われていた時間を取り戻し、より創造的な開発作業に集中できます。
