Claude CodeのHooks機能で開発フローを自動化する方法

本記事を読めば、Claude CodeのHooks機能で実行前後のチェックや通知を自動化し、lint・テスト・危険コマンド確認の抜け漏れを減らせるようになります。

AIzen株式会社は、AIエージェントを活用した開発フロー設計や業務システム開発を支援する中で、便利な自動化ほど「いつ止めるか」「どこを記録するか」の設計が重要だと考えています。

本記事では、Claude Code Hooksをチームの品質管理に組み込む実務手順を解説します。

Claude CodeのHooks機能とは

Claude CodeのHooks機能は、Claude Codeのライフサイクル上の特定タイミングで、ユーザー定義の処理を自動実行する仕組みです。公式ドキュメントでは、シェルコマンド、HTTPエンドポイント、LLMプロンプトなどをフックとして設定できるとされています。開発チームで使う場合は、単なる便利機能ではなく、AIエージェントの作業に品質確認と記録を挟むための制御点として捉えると設計しやすくなります。

Hooksで自動化できる処理

Hooksで自動化しやすいのは、実行条件と期待結果が明確な処理です。たとえば、Bash実行前に危険なコマンドを検査する、ファイル編集後にlintを走らせる、作業完了時にログを保存する、といった処理が代表例です。人が毎回思い出して実行していた確認作業を、Claude Codeの操作タイミングに合わせて自動化できます。

重要なのは、Hooksを「何でも自動実行する仕組み」にしないことです。毎回同じ判断でよい確認をHooksへ寄せ、人の判断が必要な操作は承認フローに残すと、開発速度と安全性のバランスを取りやすくなります。

設定ファイルの配置場所

HooksはClaude Codeの設定ファイルに定義します。公式ドキュメントでは、個人設定、プロジェクト設定、ローカル専用設定、管理ポリシーなど複数の配置場所が示されています。個人利用なら ~/.claude/settings.json、プロジェクト共有なら .claude/settings.json、マシン固有の値を含む場合は .claude/settings.local.json のように分けて考えるのが基本です。

チーム開発では、共有すべきものと共有すべきでないものを分ける必要があります。たとえば「TypeScriptファイル編集後に npm run lint を実行する」というルールはプロジェクト共通でよい一方、個人の通知スクリプトやローカルパスを含むコマンドは共有設定に入れるべきではありません。リポジトリに入れるHooksは、全員の環境で成立する最小限の品質ルールに絞るのが安全です。

チーム開発で使うメリット

チームでClaude Codeを使い始めると、エンジニアごとに依頼の粒度や確認の仕方が変わりやすくなります。Hooksを使うと、AIエージェントが生成した変更に対して、チーム共通のチェックを自動で挟めます。

PRレビュー時に「lintは通したのか」「どのファイルを触ったのか」を毎回確認しているなら、Hooksで事前に出力させるだけでレビュー観点が揃います。AIzen株式会社が開発フローを設計する際も、誰が見ても同じ品質確認が残る状態を重視しています。

Hooks機能の設定方法

Hooksの設定は、イベント名、matcher、実行するhandlerを組み合わせて作ります。設定自体はJSONで書けますが、運用で大切なのは「どのタイミングで、どの操作だけを対象にし、何秒以内に終わらせるか」を先に決めることです。

EventNameの指定

EventNameは、Claude CodeのどのタイミングでHooksを起動するかを決める項目です。代表的なものとして、ツール実行前の PreToolUse、ツール実行後の PostToolUse、Claudeの応答終了時の Stop があります。実行前に止めたい処理は PreToolUse、実行後に検査したい処理は PostToolUse、セッションやターンの整理をしたい処理は Stop という分け方が実務的です。

たとえば、Bashの危険コマンドを確認するなら、実行後では遅いため PreToolUse を使います。一方、ファイル編集後のlintは編集内容が存在してから実行する必要があるため PostToolUse が向いています。EventNameの選定は、処理を止める必要があるか、結果を確認すればよいかで判断すると迷いにくくなります。

matcherの書き方

matcherは、対象にするツールやイベントを絞り込むための条件です。公式ドキュメントでは、Bash のような完全一致、Edit|Write のような複数指定、正規表現を含む指定が紹介されています。MCPツールの場合は mcp__<server>__<tool> という命名パターンになるため、特定サーバー全体を対象にするなら mcp__github__.* のような指定ができます。

matcherを広くしすぎると、関係ない操作にもHooksが反応します。逆に狭すぎると、期待した操作で動きません。チーム共有する設定では、正規表現を複雑にしすぎず、なぜそのmatcherにしたのかをレビュー時に説明できる状態にしておくべきです。

command・timeoutの設定

commandには、実際に起動するシェルスクリプトやコマンドを指定します。Hooksのhandlerにはイベント情報がJSONで渡されるため、スクリプト側で tool_name や tool_input を読み取り、必要な判定を行います。

timeoutは、Hooksが開発体験を重くしないための重要な設定です。lintやテストを毎回フル実行すると、Claude Codeの応答待ちが長くなり、開発者がHooksを無効化したくなります。短時間で終わる静的検査は同期実行し、重いテストや集計は非同期Hooksに回す、という分離が現実的です。Hooksは品質を上げるための仕組みですが、遅すぎるHooksは運用から外されます。

PreToolUseを使う方法

PreToolUseは、Claude Codeがツールを実行する前に処理を挟むイベントです。実行前に判断できるため、危険なBash、想定外のファイル編集、許可していないMCP書き込み操作の確認に向いています。特にAIエージェントにコマンド実行を任せる場面では、PreToolUseを最初に設計しておくと、チームの不安を減らしやすくなります。

Bash実行前のコマンド検査

Bash実行前の検査では、コマンド文字列を見て、禁止・確認・許可の判定を行います。rm -rf、本番環境を示す接続文字列、外部送信などは確認対象にできます。ただし、単純な文字列一致だけでは誤判定も起きるため、最初は「確認」に寄せるほうが安全です。

検査スクリプトでは、常に拒否する操作、確認を挟む操作、許可する操作を分けます。この分類をREADMEやAGENTS.mdにも残しておくと、Hooksの挙動がチームに伝わりやすくなります。

ファイル編集前の対象確認

ファイル編集前の確認では、Claude Codeが編集しようとしているパスを見て、対象範囲に入っているかを判定します。AIエージェントは広い範囲を探索するため、編集してよい場所と確認が必要な場所をパス単位で分けることが効果的です。

この設計は、サンドボックスや承認ポリシーの代替ではありません。Hooksは追加の確認レイヤーとして使い、ファイルシステム上の権限境界はClaude Code側の設定やリポジトリ運用で管理します。特にチーム共有のHooksでは、個人のローカルパスに依存せず、リポジトリ相対パスで判定できる形にする必要があります。

deny・ask・allowの使い分け

PreToolUseでは、処理結果として許可、拒否、確認要求に相当する判断を返せます。運用上は、deny・ask・allowを次のように使い分けるとわかりやすいです。denyは明確に禁止したい操作、askは人の判断を挟みたい操作、allowはチームで安全と判断済みの操作に使います。

注意したいのは、allowを増やしすぎないことです。allowを便利に使うほど承認回数は減りますが、意図しない操作も通りやすくなります。最初はdenyとaskを中心にし、CIやレビューで問題が出ていない定型コマンドだけallowへ移すのが現実的です。自動化の目的は承認をゼロにすることではなく、確認すべき場面を明確にすることです。

PostToolUse・Stopを使う方法

PostToolUseとStopは、実行後の品質確認や記録に向いています。PreToolUseが「実行してよいか」を判断する仕組みだとすれば、PostToolUseとStopは「実行後に何を残すか」を整える仕組みです。レビューや引き継ぎに効くのは、こちらの設計です。

編集後のlint・テスト実行

PostToolUseでは、EditやWriteの後にlint、format、型チェック、単体テストを起動できます。ただし、すべての編集後にフルテストを走らせると待ち時間が大きくなります。現実的には、軽いチェックを同期実行し、重いテストは特定ディレクトリの変更時やStop時に限定するのがよいです。

たとえば、フロントエンドのTypeScript変更では npm run lint — –cache、バックエンド変更では対象パッケージの単体テストだけを実行するなど、変更範囲に合わせて処理を絞ります。AIzen株式会社が支援する開発現場でも、AIエージェント導入後の品質低下を防ぐには、人間のレビュー前に機械的に検出できる問題を先に潰す設計が効果的です。

作業ログの記録

作業ログは、AIエージェントの変更内容をチームで追跡するために有効です。StopやPostToolUseで、変更ファイル一覧、実行したコマンド、失敗したテスト、未解決のTODOをMarkdownに出力しておけば、レビュー担当者は会話履歴をすべて読まなくても作業の流れを把握できます。

ログは詳細すぎると読まれません。1回のセッションにつき「変更ファイル」「実行コマンド」「未完了事項」「確認してほしい点」に絞ると、レビュー担当者が短時間で確認できます。

セッション終了時の確認処理

Stopイベントは、Claudeの応答が終わるタイミングで発火するため、完了確認や要約生成に向いています。たとえば、最後に git diff –stat を出す、変更ファイルに対するテスト未実行を警告する、レビュー依頼用のメモを生成する、といった使い方ができます。

ただし、Stopは「完全に作業が完了したときだけ」発火するものとして扱うと誤解が生まれます。応答の区切りで動くため、重い処理を毎回入れると邪魔になります。Stopでは軽い確認や要約に留め、必要に応じてユーザーが手動で実行する検査コマンドも併用すると、実務に馴染みます。

弊社エンジニアからのコメント：

Claude Code Hooksは、最初から大きな自動化を組むより「Bash実行前の確認」と「編集後のlint」だけに絞って始めるほうが定着しやすいです。以前、Stopごとにフルテストを走らせる設計にしたケースでは、待ち時間が増えてチームが設定を外したくなる状態になりました。短い検査を同期、重い検査を非同期またはCIに分けると、開発体験を保ちながら品質確認を残せます。

Hooks機能のチーム運用ルール

Hooksは設定して終わりではありません。チームで使うなら、誰が追加し、誰がレビューし、どの設定を共有するかを決める必要があります。特にAIエージェントの作業範囲はプロジェクトごとに異なるため、Hooksの運用ルールもリポジトリ単位で管理するのが現実的です。

プロジェクト共通ルールの管理

プロジェクト共通ルールは、.claude/settings.json のような共有設定に置き、Pull Requestで変更をレビューします。レビューでは、対象イベント、matcher、実行コマンド、timeout、失敗時の挙動を確認します。Hooksの変更は開発者全員の作業体験に影響するため、通常のコード変更と同じように差分レビューが必要です。

また、AGENTS.mdやREADMEに許可操作、確認が必要な操作、自動実行する検査を明記しておくと、Claude Codeを初めて使うメンバーも迷いにくくなります。

ローカル専用設定の分離

ローカル専用設定には、個人の通知、OS依存コマンド、ローカルパス、個人用ツールを含めます。これらを共有設定に入れると、他のメンバーの環境でエラーが出ます。.claude/settings.local.json のようにgit管理外のファイルへ分離し、共有設定には入れないルールを徹底します。

Slack通知や個人のタスク管理ツール連携では、トークンやWebhook URLをリポジトリに入れず、環境変数経由で参照します。

非同期Hooksの使いどころ

非同期Hooksは、Claude Codeの進行を止めずに後続処理を走らせたい場合に向いています。長めのテスト、作業ログの外部保存、通知などは非同期に回すと、開発者の体感速度を保てます。

一方で、非同期Hooksは結果を見落としやすいという注意点があります。同期はブロックする確認、非同期は記録と重い検査という役割分担にすると、チーム運用に乗せやすくなります。

まとめ

Claude CodeのHooks機能は、AIエージェントの開発フローに品質確認と記録を組み込むための実務的な仕組みです。要点は次の3つです。

• PreToolUseでは、Bash実行前やファイル編集前に危険操作や対象範囲を確認する
• PostToolUse・Stopでは、lint・テスト・作業ログを残し、レビュー前の確認負担を減らす
• チーム運用では、共有設定とローカル専用設定を分け、timeoutや非同期処理まで設計する

AIzen株式会社では、Claude CodeやCodexなどのAIエージェントを使った開発フロー設計、HooksやMCPを含む運用ルール整備、業務システムへのAI活用支援を行っています。Claude Code Hooksを導入したいが、どこまで自動化してどこを人間確認に残すべきか迷う場合は、貴社の開発体制に合わせた設計からご相談ください。