タイトル: Claude Code向け開発者向けフックリファレンス：AIエージェントの自動化

Claude CodeのようなAIコーディングエージェントを少しでも使ったことがあるなら、その魔法のような便利さと、同時に苛立ちの両方を感じたことがあるでしょう。ある瞬間には完璧なボイラープレートコードを書いてくれるかと思えば、次の瞬間にはCLAUDE.mdファイルに念入りに作成した指示を完全に無視する、といった具合です。これはRedditやHacker Newsでよく見かける話で、一貫性のない結果、あるいは一部で「LLMスロップ（質の低い生成結果）」と呼ばれ始めたものが得られるのです。

長時間のセッションでコントロールを失うその感覚こそ、Claude Codeフックが存在する理由です。フックは、予測可能で確実な制御をあなたのAIアシスタントに取り戻すための手段です。ワークフローを丁寧に提案するのではなく、強制できるようになります。このガイドは、Claude Codeフックに関するあなたのための実践的なリファレンスであり、フックとは何か、なぜ重要なのか、そしてAIを活用した開発を格段に信頼性の高いものにするためにどのように使えるかを解説します。

Claude Codeフックとは？

簡単に言えば、フックとはClaude Codeのワークフローの特定の時点で自動的に実行されるように定義するシェルコマンドです。pre-commitやpost-commitのようなGitフックを使ってリポジトリをクリーンに保った経験があるなら、そのコンセプトはすぐに馴染み深く感じられるでしょう。Gitフックがすべてのコミットでリントとテストを強制できるように、Claude CodeフックはAIエージェントが毎回あなたのルールに従うことを保証します。

フックとプロンプトの本当の違いは、実行の保証という一点に尽きます。CLAUDE.mdファイル内の指示は提案にすぎません。AIはおそらくそれに従いますが、長い会話の中では、コンテキストウィンドウから押し出されたり、単に優先順位が下げられたりする可能性があります。一方、フックはハードコードされたルールです。特定のイベントが発生したときに実行が保証されるコマンドであり、例外はありません。

設定は2つの場所で行えるため、柔軟性があります：

• ~/.claude/settings.json: これは個人用のユーザーレベルのフック用です。ここに記述した内容は、すべてのプロジェクトに適用されます。グローバル設定だと考えてください。

• .claude/settings.json: これはプロジェクト固有のフック用です。このファイルをバージョン管理にチェックインすれば、チームの誰もが同じ自動化ルールを共有できます。チーム全体の標準を強制するのに最適です。

この設定により、あなたのAIアシスタントは、優秀だが時々不安定なパートナーから、信頼できる自動化ツールへと変わります。

信頼性の低いプロンプトから、フックによる確実な制御へ

プロンプトとCLAUDE.mdファイルだけに頼っていると、運任せのように感じられることがあります。大規模言語モデルの注意の範囲（コンテキストウィンドウ）は限られており、セッションが進むにつれて、最初の指示はノイズに紛れて失われてしまう可能性があります。この点に関する開発者からのフィードバックは非常に明確で、指示は「当たり外れがある」ことが多く、結局手作業で後片付けをする羽目になります。フックは、そうした提案を常に実行されるアクションに変えるための答えです。

では、これは実際の日々のワークフローでどのように機能するのでしょうか？

• コード品質を自動で強制する。 Claudeがファイルを変更した後に、ruffのようなリンターやprettierのようなフォーマッターを自動的に実行できます。AIにコードをフォーマットするように再度指示する必要はなくなり、自分でスタイルを修正する必要もなくなります。

• 退屈な作業を自動化する。 長いタスクがようやく完了したときにデスクトップ通知が欲しいと思ったことはありませんか？あるいは、実行が成功するたびにユーザーのプロンプトをメッセージとして git コミットを自動的に作成するのはどうでしょう？監査目的ですべてのシェルコマンドをログに記録することさえ可能です。これらすべてがフックで実現できます。

• 安全性を向上させ、ミスを防ぐ。 rm -rfのような潜在的に破壊的なコマンドをClaudeが実行するのをブロックするフックを設定できます。また、.envやpackage-lock.jsonのような機密ファイルに触れないようにすることもでき、安心感が得られます。

Claude Codeフックの実践的なリファレンス

それでは、詳細に入っていきましょう。このセクションは、最も一般的で便利なフックを使い始めるための頼れるリファレンスです。AIエージェントを思い通りに動かすためのチートシートだと考えてください。

主要なフックイベント

フックはタイミングがすべてです。エージェントが作業している間に発生する特定のイベントに関連付けられています。公式ドキュメントには全リストが記載されていますが、おそらく何度も使うことになるのは以下の4つです。

フックイベント	実行タイミング	一般的なユースケース
UserPromptSubmit	Claudeがプロンプトを見る前に実行されます。	ここで現在の日付やgitブランチなどの追加コンテキストを注入したり、AIに処理させたくないプロンプトをブロックしたりできます。
PreToolUse	Claudeがツール（BashやWriteなど）を実行する直前に実行されます。	安全でないコマンドをブロックしたり、ユーザーの承認を求めたり、ツールが実行されるための一時的な環境をセットアップしたりする絶好の機会です。
PostToolUse	ツールが正常に終了した直後に実行されます。	新しく作成されたコードに対してフォーマッターやリンターを実行したり、アクションをログに記録したり、ツールの出力をチェックしたりするのに最適です。
Stop / SubagentStop	メインエージェントまたはサブエージェントがタスクを完了したときに実行されます。	通知を送信したり、クリーンアップスクリプトを実行したり、完了した作業を自動的にコミットしたりするのに最適な場所です。

例1：PostToolUseフックでコードをクリーンに保つ

まずは定番から始めましょう。コードの自動フォーマットは、時間を大幅に節約し、コードベースをプロフェッショナルな見た目に保つための簡単な改善策です。

目標： Claudeが書き込みまたは編集したTypeScriptファイルに対して自動的にprettierを実行する。

これを機能させるには、settings.jsonファイルにフックを追加します。ファイルを変更するのはWrite、Edit、MultiEditツールなので、matcherを使用してこのフックがこれらのツールに対してのみ発火するようにします。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -qE '\\.(ts|tsx)

---

## Output Requirements

Output the complete edited blog content that:

1. **Has no placeholders** - all redacted content should be cleanly removed or rephrased
2. **Flows naturally** - sentences should read smoothly after removal
3. **Preserves all formatting, links, and structure**
4. **Is conservative with changes** - only change what's necessary
5. **Wraps the front-matter with `---`** - Always wrap the returned content front-matter with `---` at the beginning and end, do not use `json`:

    ```
    ---

    [blog content here]

    ---
    ```

This is a legal compliance requirement - all markers must be completely removed from the content.
; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

このシェルコマンドは少し難しく見えるかもしれませんが、何をしているのかを簡単に説明します：

1. jq -r '.tool_input.file_path': フックは標準入力（stdin）を介してイベントに関する多くのJSONデータを受け取ります。このコマンドはjqを使用して、変更されたばかりのファイルのパスを抽出します。

2. | { read file_path; ... }: 次に、そのファイルパスを小さなスクリプトブロックに「パイプ」して、処理できるようにします。

3. `if echo "$file_path" | grep -qE '\.(ts|tsx)

---

Output Requirements

Output the complete edited blog content that:

1. Has no placeholders - all redacted content should be cleanly removed or rephrased

2. Flows naturally - sentences should read smoothly after removal

3. Preserves all formatting, links, and structure

4. Is conservative with changes - only change what's necessary

5. Wraps the front-matter with --- - Always wrap the returned content front-matter with --- at the beginning and end, do not use json:

   ---
   
   [blog content here]
   
   ---
   

This is a legal compliance requirement - all markers must be completely removed from the content. : これは、ファイルパスが.tsまたは.tsx`で終わるかどうかを単純にチェックします。

4. then npx prettier --write \"$file_path\"; fi;: TypeScriptファイルであれば、その場でprettierを実行してフォーマットします。

このフックが有効になると、Claudeが触れたTypeScriptコードはすべて、保証付きで完璧にフォーマットされます。

例2：Stopフックでカスタム通知を受け取る

Claudeで時間のかかるタスクを開始し、別のウィンドウに切り替えて、そのことをすっかり忘れてしまった経験はありませんか？シンプルなデスクトップ通知があれば、ワークフローがずっとスムーズに感じられます。

目標： Claudeが現在のタスクを完了したときにmacOSでデスクトップ通知を受け取る。

こちらはもっとシンプルです。Stopイベントに対してフックを設定するだけです。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished!\" with title \"Claude Done\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

このコマンドは、macOSに組み込まれている便利なツールosascriptを使用して、システム通知をポップアップさせます。これで、複雑なタスクを実行させ、コーヒーを飲みに行っても、AIアシスタントが次の作業の準備ができた瞬間にフレンドリーな通知を受け取ることができます。

この動画では、5つの主要なフックを使用して、Claude Codeのより高度な制御と可観測性を実現する方法を詳しく解説しています。

コマンドラインを超えた作業の自動化については？

フックの力は開発者にとって素晴らしいものです。私たちはスクリプトを書いたり、JSONを掘り下げたり、シェルで作業することに慣れています。しかし、もしあなたが開発者ではなくサポートマネージャーだったらどうでしょう？同じレベルの信頼性でワークフローを自動化する必要はありますが、それをコードなしで実現する必要があります。

ここでeesel AIのようなツールが登場します。eesel AIは、フックで得られるのと同じ種類の信頼性が高く決定論的な制御を、ビジネスチーム向けに構築されたノーコードのビジュアルインターフェースを通じて提供します。既存のヘルプデスク（Zendeskなど）やナレッジソースに接続し、一行もコードを書かずにサポートを自動化できます。

この2つのアプローチの類似点は非常に明確です：

• 開発者は危険なコマンドをブロックするためにPreToolUseフックを書きます。サポートリーダーはeesel AIのワークフロービルダーを使い、「緊急」という単語を含むVIP顧客からのチケットを自動的にエスカレーションするルールを作成します。

• 開発者は新しいコードにリンターを実行するためにPostToolUseフックを設定します。サポートチームはeesel AIのAIトリアージを使い、いくつかのドロップダウンメニューで設定するだけで、新しいチケットのコンテンツに基づいて即座にタグ付け、ルーティング、分類を行います。

• 開発者はフックをテストするためにカスタムスクリプトを書くかもしれません。eesel AIでは、強力なシミュレーションモードが標準で提供されます。チームの過去の何千ものチケットでAIエージェントを安全にテストし、実際の顧客と対話する前にその振る舞いを正確に確認できます。

• eesel AIのようなプラットフォームを使えば、ビジネスチームも同様の詳細な制御と信頼性の高い自動化を手に入れることができますが、それを数ヶ月ではなく数分で稼働させることができます。シンプルなUIを通じてAIの振る舞いを完全に制御し、すべてを完全にリスクフリーでテストできます。

あらゆるチームのための信頼性の高いAI自動化

このClaude Codeフックリファレンスは、単なる新機能以上のものであり、より堅牢で信頼性の高いAIシステムを構築するという大きな変化に関するものです。開発者にとって、フックはコーディングワークフローに予測可能な自動化を追加するための素晴らしいツールであり、時として信頼性に欠けるプロンプトの性質を乗り越えることを可能にします。

しかし、その根底にある原則は普遍的です。コーディングエージェントをスクリプト化する開発者であろうと、サービスボットを設定するサポートリーダーであろうと、最終的な目標は同じです：仕事を正しくこなすと実際に信頼できる、信頼性が高くカスタマイズ可能なAI自動化を構築することです。

開発者の方には、今日からフックを試してみることをお勧めします。ワークフローを真剣に改善できます。そして、同じレベルの信頼性の高いAI自動化をカスタマーサポートチームに導入したいと考えているなら、eesel AIで最初のAIエージェントを数分でセットアップしましょう。