【2026年8月最新】Claude Code Hooksとは？テスト・整形・禁止操作を自動化する方法

2026年8月20日 12:37

Claude Codeに「編集後は必ずテストして」「`.env`は変更しないで」と伝えても、指示だけでは実行を保証できません。作業が長くなったり、別の担当者が使ったりすると、確認漏れも起こります。

そこで使えるのがClaude Code Hooksです。ファイルを編集した直後、コマンドを実行する直前、Claudeが作業を終えるときなど、決めたタイミングで処理を自動実行できます。

この記事では、Hooksの仕組みから、コード整形、テスト、保護ファイルの編集防止、チームでの共有方法までを実例で解説します。

この記事の要点

✅ Claude Code Hooksは、決めたイベントでコマンドや検証処理を自動実行する仕組みです
✅ CLAUDE.mdやSkillsが「指示」を与えるのに対し、Hooksは整形・検査・禁止処理を決めた条件で実行できます
✅ 最初から多くのHooksを入れず、整形、テスト、保護ファイルの順に小さく導入すると原因を追いやすくなります

Claude Code Hooksとは？

Anthropicの公式ガイドでは、HooksをClaude Codeのライフサイクル上の特定時点で実行される、利用者定義の処理として説明しています。

たとえば、Claude Codeがファイルを編集した後にPrettierを実行する、シェルコマンドを実行する前に内容を検査する、入力待ちになったら通知を出す、といった使い方ができます。

重要なのは、Claudeが必要だと判断したときだけ動く機能ではないことです。設定したイベントと条件が一致すれば処理されます。AIの判断に任せたくない確認を、作業の流れへ組み込めます。

Hooksが必要になる場面

個人が小さなファイルを編集するだけなら、毎回「最後にテストして」と伝える方法でも足りるかもしれません。しかし、次のような場面では指示だけに頼る運用が不安定になります。

複数人が同じリポジトリでClaude Codeを使う
編集後に必ずコード整形や静的解析を行いたい
`.env`やロックファイルなど、変更させたくないファイルがある
完了前にテスト結果を確認させたい
設定変更やツール利用を記録したい
長時間作業の入力待ちを見逃したくない

Hooksは、Claude Codeを高性能な対話ツールから、決めた確認工程を含む作業環境へ近づける機能です。

CLAUDE.md・Skills・Hooksの違い

Claude Codeには、動作を調整する仕組みが複数あります。役割を混ぜると、CLAUDE.mdが長大になったり、Hooksへ判断の難しい処理を詰め込んだりします。

「この命名規則を守ってください」はCLAUDE.mdに書けます。「ファイルを編集したら必ずフォーマッターを動かす」はHooks向きです。

複数工程をClaudeへ教える場合は、Claude Skillsの作り方で解説しているSkillsが合います。会話をまたぐ情報の扱いは、CLAUDE.mdとAuto Memoryの違いで整理しています。

説明はCLAUDE.md、再利用する作業手順はSkills、実行を仕組みにする処理はHooksと分けると、設定を保守しやすくなります。

Hooksはいつ実行される？

Hooksはイベントを起点に動きます。すべてを覚える必要はありません。最初は次のイベントを押さえれば十分です。

ファイル変更を止めたいなら、実行後の`PostToolUse`では遅すぎます。変更前に動く`PreToolUse`を選びます。一方、編集されたファイルを整形するなら`PostToolUse`が自然です。

止める処理は実行前、整える処理は実行後と考えると選びやすくなります。

hookには5つの実行方法がある

2026年8月時点の公式リファレンスでは、hook typeは5種類です。`command`はシェルコマンド、`http`はHTTPエンドポイント、`mcp_tool`は接続済みMCPサーバーのツールを呼び出します。`prompt`はClaudeへ単発の判断を依頼し、`agent`はファイル確認やコマンド実行を伴う検証に使います。

すべてのイベントが5種類すべてに対応するわけではありません。まずは挙動を追いやすい`command`から始め、複数端末の監査情報を集約したい場合は`http`、既存の社内ツールを使いたい場合は`mcp_tool`を検討します。

Claude Code Hooksの設定場所

Hooksはsettingsファイルの`hooks`ブロックへ記述します。置き場所によって適用範囲が変わります。

`~/.claude/settings.json`は、自分が使う全プロジェクトに適用
`.claude/settings.json`は、そのプロジェクトに適用し、リポジトリで共有可能
`.claude/settings.local.json`は、そのプロジェクトの自分だけに適用
管理ポリシーは、組織の管理者が全体へ適用
プラグイン、Skill、Subagentの設定にもHooksを含められる

個人の通知設定は`~/.claude/settings.json`、チームで統一するテストや保護ルールは`.claude/settings.json`が候補です。ただし、プロジェクト設定を共有する前に、Windows、macOS、Linuxのどこで動くかを確認してください。

設定後はClaude Codeで次のコマンドを入力します。

/hooks

登録されたイベント、条件、処理、設定元を確認できます。公式ガイドによると、`/hooks`の画面は確認用です。追加や変更はsettingsファイルを編集するほか、実現したい動作をClaude Codeへ伝えて設定作成を依頼する方法もあります。生成された内容は、そのまま有効にせず、実行コマンドを確認してください。

実例1｜編集したコードを自動で整形する

最初に試しやすいのが、ファイル編集後の自動整形です。次の例は、Claude Codeが`Edit`または`Write`を使った後に、編集したファイルのパスを取り出し、Prettierを実行します。

プロジェクト直下の`.claude/settings.json`へ追加します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

この設定では、`matcher`が対象ツールを絞り、`command`が実際の処理を担います。公式例はJSONの読み取りに`jq`を使うため、利用環境に入っていなければ別途インストールが必要です。

何を確認すればよいか

Hooksが正常に動いても、会話上には何も表示されない場合があります。整形後のファイルを開き、期待する書式へ変わったかを確認してください。

最初から全拡張子へ適用するのではなく、対象言語と設定ファイルを決めます。対象外のファイルをPrettierへ渡すと、編集自体は成功しているのにHooksでエラーが出ることがあります。

実例2｜保護ファイルの編集を止める

`.env`、秘密情報を含む設定、依存関係のロックファイルなど、AIに変更させたくないファイルがあります。CLAUDE.mdに「編集禁止」と書くだけでなく、編集前にHooksで検査すると二重に守れます。

まず`.claude/hooks/protect-files.sh`を作ります。

#!/bin/bash

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

macOSとLinuxでは、スクリプトを実行できるようにします。

chmod +x .claude/hooks/protect-files.sh

次に、ファイル編集前にスクリプトを実行する設定を`.claude/settings.json`へ追加します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

対象ファイルに一致すると、スクリプトは終了コード2を返し、編集を止めます。理由はClaudeへ渡されるため、別の方法へ切り替えることもできます。

ここで間違えやすいのが終了コードです。通常の失敗を示す`exit 1`では、ほとんどのhookイベントで処理を止められません。 Claude Codeは非ブロッキングエラーとして扱い、操作を続行します。ポリシーとして操作を止めるcommand hookでは、公式仕様に従って`exit 2`を使います。

ただし、この例をそのまま本番へコピーするのではなく、自社の保護対象を洗い出してください。`.env.example`まで止めるのか、ロックファイルは更新申請時だけ許可するのかなど、実務上の例外があります。

生成AIやAIエージェント全体の許可・承認・ログの設計は、生成AI・AIエージェントの権限設計で詳しく解説しています。

Claude Codeのチーム利用や安全な運用ルールを整理した資料をご用意しています。

▶️ AIworkerのサービス資料をダウンロードする

実例3｜入力待ちを通知する

Claude Codeへ長い作業を任せて別の仕事をしていると、許可待ちのまま止まっていることがあります。macOSでは`Notification`イベントと`osascript`を組み合わせて通知できます。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

空の`matcher`は、すべての通知種別を対象にします。許可待ちだけに絞る場合は、公式ガイドで案内されている`permission_prompt`を指定できます。バックグラウンドセッションの待機や完了を知らせる`agent_needs_input`と`agent_completed`もありますが、Claude Code v2.1.198以降が必要です。

通知は安全性を高める機能ではありませんが、待ち時間を減らせます。まず個人設定で試し、チーム共通設定へは入れない方が扱いやすいでしょう。

実例4｜テストを自動実行する

テストの自動化には二つの考え方があります。

1つ目は、編集後の`PostToolUse`で対象テストを実行する方法です。変更直後に問題を見つけやすい一方、小さな編集のたびに重いテストを動かすと作業が遅くなります。

たとえば、JavaScriptやTypeScriptのプロジェクトで、ファイル編集後に短時間で終わるテストを実行するなら、次のように設定できます。`npm test -- --runInBand`の部分は、自分のプロジェクトで実際に使っているテストコマンドへ置き換えてください。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --runInBand",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

この例は編集のたびにテスト全体を実行します。規模が大きいプロジェクトでは、対象ファイルに近いテストだけを呼ぶスクリプトを用意するか、作業完了時の確認へ移してください。

2つ目は、Claudeが応答を終えようとする`Stop`で、テストの合格を確認する方法です。公式ガイドには、Claudeのモデルで判断するprompt hookと、ファイルやコマンドを調べられるagent hookも案内されています。ただし、agent hookは2026年8月時点で実験的機能です。仕様変更の影響を受けたくない運用では、command hookを優先します。

実務では、次のようにテストを分けると負荷を抑えられます。

編集後は、対象ファイルに近い単体テストや静的解析だけを実行
作業の区切りでは、関連範囲のテストを実行
CIでは、全体テストを実行
本番反映前は、人が結果と変更内容を確認

Hooksを入れても、CIや人のレビューが不要になるわけではありません。 ローカルの確認漏れを早く見つける層として使います。

Hooksと権限設定はどちらを使う？

禁止操作を扱うときは、Hooksと権限設定の役割を分けます。

Claude Codeの公式ガイドによると、`PreToolUse`で拒否された操作は、権限確認を省略するモードでも止められます。一方、Hooks側の許可は、settingsの拒否ルールを越えて操作を許可するものではありません。つまり、Hooksは制限を追加できますが、管理者やプロジェクトの拒否ルールを緩める用途には使えません。

基本は次の分担です。

明確に許可・拒否できるツールやコマンドは権限設定
ファイルパスや引数など、実行内容を見て止める処理は`PreToolUse`
実行後の整形や軽い検査は`PostToolUse`
組織全体で外せないルールは管理ポリシー

なお、公式ガイドは、Hooksの`if`によるコマンド解析を強制的な許可・拒否の唯一の手段にしないよう案内しています。解析できない場合にhookが動く設計になっているため、強い禁止は権限設定とHooksを組み合わせる方が安全です。

チーム導入で失敗しやすい5つのパターン

1. Web上の設定を確認せずコピーする

Hooksは自動的にコマンドを実行します。出所不明の設定には、ファイル送信、外部通信、削除、認証情報の読み取りが含まれる可能性があります。コマンド、引数、参照ファイル、通信先を読んでから使います。

2. 最初から多くのHooksを有効にする

整形、テスト、通知、監査を同時に入れると、失敗した処理を特定しづらくなります。まず1つ追加し、正常時、エラー時、対象外ファイルで挙動を確認します。

3. 開発環境の違いを無視する

macOSで動く`osascript`はWindowsでは使えません。`jq`、Node.js、Pythonの有無も端末によって異なります。共有設定では、必要な依存関係と対応OSをREADMEへ書きます。

4. PostToolUseで危険操作を止めようとする

`PostToolUse`が動く時点では、ツールはすでに実行されています。削除や外部送信、重要ファイルの変更を止めるなら、実行前の`PreToolUse`または権限設定を使います。

5. Hooksがあるから人の確認を外す

ルールに一致しない危険操作や、業務上は誤っているものの技術的には正常な変更は残ります。Hooksは決めた条件の検査には強い一方、変更の目的まで保証しません。

Hooksを安全に導入する手順

防ぎたい失敗を1つ決める
指示、権限、Hooksのどれで扱うかを選ぶ
個人設定または検証用ブランチで試す
正常、拒否、エラーの3通りを確認する
実行時間と作業への影響を測る
設定の所有者と更新方法を決める
チーム共有後も定期的に不要なHooksを外す

導入の起点は「何を自動化できるか」ではなく、どの確認漏れを減らしたいかです。整形漏れならPostToolUse、重要ファイルの誤編集ならPreToolUse、入力待ちならNotificationと、失敗から逆算します。

Claude Codeの基本操作や料金、対応環境をまだ確認していない場合は、先に総合記事を読むと設定の位置づけをつかみやすくなります。外部ツールや社内システムとの接続は、Claude CodeとMCPの仕組みで解説しています。

よくある質問（FAQ）

Q. Claude Code Hooksは無料で使えますか？

Hooks自体はClaude Codeの機能です。ただし、Hooksから呼び出す外部サービス、agent hookやprompt hookで使うモデル、実行するテスト環境などには別途費用が発生する場合があります。

Q. HooksはClaude Desktopでも使えますか？

HooksはClaude Codeの設定として利用します。Claude CodeをDesktopやIDEなどの対応環境から利用する場合も、設定元と実行環境を確認してください。通常のClaudeチャットへ同じsettings.jsonを置くだけで動く機能ではありません。

Q. CLAUDE.mdに「必ずテストする」と書けば十分ですか？

作業方針を伝える目的には有効ですが、実行を保証する仕組みではありません。テストが必須なら、HooksやCIへ組み込みます。CLAUDE.mdには、なぜ必要か、どのテストを使うかを書きます。

Q. Hooksで危険なコマンドをすべて防げますか？

防げません。想定した条件に一致しない操作や、スクリプトの不備が残るためです。権限設定、保護された実行環境、コードレビュー、秘密情報管理と組み合わせます。

Q. Hooksが動かないときは何を確認しますか？

`/hooks`で登録状況を確認し、イベント名、`matcher`の大文字と小文字、settingsファイルの場所、JSONの構文を確認します。スクリプトを使う場合は実行権限、依存コマンド、終了コードも確認してください。処理を止める目的で`exit 1`を使っていないかも確認します。

Q. 個人設定とプロジェクト設定のどちらがよいですか？

通知や個人だけの補助処理は`~/.claude/settings.json`、チームで統一する整形・検査は`.claude/settings.json`が候補です。共有前に、全員のOSと開発環境でテストします。

Claude Code Hooksを業務で活かすために｜AIworkerの支援

Hooksは便利ですが、設定を増やすだけでは開発品質は安定しません。どの操作を止めるか、どこでテストするか、例外を誰が承認するかまで決めて、初めてチームの運用になります。

AIネイティブX研修｜安全なAI開発の共通ルールを身につける

Claude Codeの基本操作だけでなく、CLAUDE.md、Skills、Hooks、権限設定の使い分けを、実際の開発作業に近い演習で学びます。研修後には、利用者が設定の意味を理解し、禁止事項と確認手順を守って作業できる共通ルールを残します。

AIネイティブX伴走｜現場で動く設定へ改善する

既存の開発フローを確認し、整形、テスト、承認、レビューのどこへHooksを置くかを一緒に決めます。導入後のエラーや例外を見ながら設定を見直し、特定の担当者しか直せない状態を避けるため、手順と更新責任者も整理します。

業務AIプロ｜権限・ログ・例外処理を含む仕組みを構築する

Claude Code単体の設定では足りず、社内データ、GitHub、CI、監査環境との連携が必要な場合は、対象業務に必要な範囲を設計・実装します。小さな検証から始め、権限、ログ、障害時の対応まで含めて本番運用へつなげます。

現在の開発環境、守りたいファイルや操作、必須テスト、利用人数を確認し、研修・伴走・開発のどこから始めるべきかを整理できます。

▶️ サービス資料のダウンロード（資料請求）

▶️ 無料カウンセリング・AI活用診断のご予約

著者情報

株式会社AIworker

企業の生成AI導入・人材育成・業務改善を支援しています。1,000件を超える企業商談から得た課題を基に、生成AI研修、業務AI・AIエージェント開発、現場に入る伴走支援を提供。「研修して終わり」ではなく、AIが実際の業務で使われ続ける状態づくりを重視しています。

株式会社AIworker：https://ai-worker.net/

この記事が参考になりましたら、今後の記事づくりの励みになるので、スキをお願いします。

参考資料

Anthropic「Automate actions with hooks」（2026年8月19日閲覧）https://code.claude.com/docs/en/hooks-guide
Anthropic「Hooks reference」（2026年8月19日閲覧）https://code.claude.com/docs/en/hooks
Anthropic「Configure permissions」（2026年8月19日閲覧）https://code.claude.com/docs/en/permissions
Anthropic「Claude Code settings」（2026年8月19日閲覧）https://code.claude.com/docs/en/configuration

#ClaudeCode #Claude #Anthropic #ClaudeCodeHooks #Hooks #生成AI #AIエージェント #コーディングAI #AIコーディング #プログラミング #ソフトウェア開発 #システム開発 #開発効率化 #業務効率化 #自動化 #テスト自動化 #コードレビュー #静的解析 #Prettier #CI #GitHub #MCP #ClaudeSkills #CLAUDEmd #AutoMemory #権限設定 #アクセス制御 #監査ログ #セキュリティ #生成AIセキュリティ #AIガバナンス #情シス #情報システム #DX推進 #AI導入 #AI研修 #AI内製化 #業務AI #株式会社AIworker #AIworker