MemoryLake
すべての記事に戻る
Tutorial2026年11月13日·12 分で読了

Claude Code のフックとは?コンテキストを追加できるフックの種類、再開されたセッションで古い出力が再生される理由、CLAUDE.md が適しているケース (2026年)

プロンプトを送信するたびに、現在のブランチと最新の CI 結果を Claude Code に伝える小さなフックを作成したとします。それはうまく機能しています。その後、昨日のセッションを --continue で再開し、ビルドについて尋ねると、Claude は自信満々に昨日の CI ステータスと、すでに置き換えられたコミットを報告します。フックが失敗したわけではありません。Claude Code が昨日言ったことを「再生」したのです。

Anthropic のフックに関するリファレンスには、まさにこのことが記載されています。「PostToolUse や UserPromptSubmit のようなセッション途中のイベントでは、--continue や --resume で再開した際、Claude Code は過去のターンのフックを再実行するのではなく、保存されたテキストを再生します。そのため、タイムスタンプやコミット SHA などの値は古くなります。」

フックは Claude Code にコンテキストを与える柔軟な方法ですが、誤解されやすいものでもあります。このガイドでは、フックとは何か、どこで定義されるのか、どのフックイベントが Claude にコンテキストを追加できるのか、そのコンテキストはどこに配置されるのか、再開時やコンパクション(要約)後に何が起こるのか、フックがコンパクションの要約をどのように形成するのか、そして同じ情報に対して CLAUDE.md ファイルの方が適しているのはどのような場合かについて説明します。

Claude Code のフックとは何か

Anthropic による定義は次の通りです。「フックとは、ユーザー定義のシェルコマンド、HTTP エンドポイント、MCP ツール呼び出し、LLM プロンプト、またはサブエージェントであり、Claude Code のライフサイクルの特定のポイントで自動的に実行されます。」

これらはターミナル以外の場所でも実行されます。「Claude Code は、ターミナルでのセッション、IDE 拡張機能、デスクトップアプリ、クラウドセッションなど、実行場所に関わらず同じフックイベントを発生させます。」

各フックはイベントに関連付けられています。リファレンスには、セッションの開始または再開時の SessionStart から、ツール呼び出し実行前の PreToolUse、コンパクション前後の PreCompact と PostCompact、セッション終了時の SessionEnd まで、数十のイベントがリストされています。

フックは、編集後のファイルフォーマット、リスクのあるコマンドのブロック、通知の送信などのサイドエフェクト(副次的な処理)を行うこともできます。このガイドでは、Claude のコンテキストにテキストを挿入するサブセットに焦点を当てます。なぜなら、そのテキストは独自のルールを持つ「記憶(memory)」のように振る舞うからです。

フックの定義場所

フックを定義する場所によって、そのスコープが決まります。リファレンスには以下の場所が挙げられています。

  • ~/.claude/settings.json: マシン内のすべてのプロジェクト用。
  • .claude/settings.json: 単一プロジェクト用。リポジトリにコミット可能。
  • .claude/settings.local.json: 単一プロジェクト用。共有されない。
  • 管理ポリシー設定: 組織用。管理者が制御。
  • プラグインの hooks/hooks.json: プラグインが有効な間。
  • スキルまたはサブエージェントのフロントマター: そのスキルまたはサブエージェントが使用されている間。

フックのエントリは、互いに置き換わるのではなく組み合わされます。「フックのエントリは、設定レベル(ユーザー、プロジェクト、ローカル設定)を越えてマージされます。管理されたフックを削除することなく、独自の設定を追加できます。」

リモートワークで知っておくべき制限が1つあります。「クラウドセッションはローカルの ~/.claude/settings.json を読み込みません。」ローカルで依存しているフックは、クラウドセッションが読み取れる場所に定義されていない限り、クラウドセッションでは実行されません。

設定されている内容を確認するには、/hooks と入力します。Anthropic はこれを「設定されたフックの読み取り専用ブラウザ」と表現しており、各フックがどこから来ているかをラベル付けして表示します。

どのフックが Claude にコンテキストを追加できるか

すべてのフックが Claude と対話できるわけではありません。対話可能なフックは additionalContext というフィールドを使用します。Anthropic は次のように説明しています。「additionalContext フィールドは、フックからの文字列を Claude のコンテキストウィンドウに渡します。」

そのテキストが表示される場所は、イベントによって異なります。

  • SessionStart および SubagentStart: 「会話の開始時、最初のプロンプトの前」
  • UserPromptSubmit および UserPromptExpansion: 「送信されたプロンプトと並んで」
  • PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch: 「ツール結果の隣」
  • Stop および SubagentStop: ターンの最後。Claude がフィードバックに基づいて行動できるようにするため。
  • PostModelSwitch: 「切り替え後の次のリクエスト時」

UserPromptSubmit の場合、通常の標準出力も機能します。リファレンスでは、通常の標準出力と additionalContext の2つのチャネルについて説明しており、「どちらのチャネルも、目に見えるトランスクリプトエントリを生成しません」と述べています。

これが人々を驚かせる部分です。Claude Code はテキストをシステムリマインダーでラップします。「Claude は次のモデルリクエストでリマインダーを読み取りますが、インターフェース上のチャットメッセージとしては表示されません。」Claude には見えていますが、チャット画面には表示されないのです。

フックが何を追加したかを確認したい場合は、トランスクリプトビューを使用すると、チャットよりも詳細なセッション内容が表示されます。これについては、Claude Code のトランスクリプトビューで表示されるもの に関するガイドで詳しく説明しています。

フックが追加できるコンテキストの量

サイズ制限があります。「値が 10,000 文字を超える場合、Claude Code はテキストをセッションディレクトリ内のファイルに書き込み、代わりに最初の 2,000 文字までのプレビューとともにファイルパスを Claude に渡します。Claude はファイルを読み取ることができますが、Claude Code はそれを強制しません。」

つまり、長いレポートを出力するフックは、レポート全体を Claude の目の前に置くわけではありません。プレビューとパスを提示し、ファイルを開くかどうかは Claude 次第となります。

同じイベントで複数のフックが実行される場合、すべてがカウントされます。「複数のフックが同じイベントに対して additionalContext を返す場合、Claude はすべての値を受け取ります。」

フックが追加するコンテキストの書き方

Anthropic は言葉遣いについて具体的なアドバイスをしています。「テキストは、命令的なシステム指示ではなく、事実に基づいた記述として書いてください。」

その理由はセキュリティです。会話の外からのコマンドのように聞こえるテキストは、プロンプトインジェクションのように見える可能性があります。Anthropic は、そのようなフレーミングは「Claude のプロンプトインジェクション防御をトリガーする可能性があり、その結果、Claude はテキストをコンテキストとして扱うのではなく、ユーザーに表面化させてしまう」と警告しています。

例として挙げられているのは、「デプロイ先は本番環境です」や「このリポジトリは bun test を使用します」といった単純な事実です。また、フックに適した情報の種類もリストされています。

  • 環境の状態: 現在のブランチ、デプロイ先、または機能フラグ。
  • 条件付きのプロジェクトルール: 編集したばかりのファイルに適用されるテストコマンド、ワークツリー内で読み取り専用のディレクトリ。
  • 外部データ: オープンなイシュー、最近の CI 結果、内部サービスからのコンテンツ。

これらに共通しているのは、「変化する」ということです。これが、ファイルではなくフックを使用する理由です。

再開されたセッションで古いフック出力が再生される理由

導入部で触れた挙動の詳細は以下の通りです。「Claude Code は注入されたテキストをセッションのトランスクリプトに保存します。」

セッションに戻ったとき、過去のターンは再実行されません。「PostToolUse や UserPromptSubmit のようなセッション途中のイベントでは、--continue や --resume で再開した際、Claude Code は過去のターンのフックを再実行するのではなく、保存されたテキストを再生します。そのため、タイムスタンプやコミット SHA などの値は古くなります。」

実際には、Claude はその時点でフックが言ったことを見ることになります。昨日フックが CI ステータス、ブランチ、またはイシューリストを報告した場合、それが再開された会話の履歴の中で、実行されたターンの隣に残っています。

SessionStart は例外です。Anthropic によれば、SessionStart フックは再開時に再度実行されます。その際、source フィールドは resume(または --fork-session を追加した場合は fork)に設定され、「コンテキストをリフレッシュできる」ようになっています。

したがって、再開されたセッションで最新の値が必要な場合は、resume マッチャーを持つ SessionStart フックがドキュメント化された適切な場所です。古い値は依然として履歴に残っているため、新しいテキストで何が最新であるかを明示するのが役立ちます。

コンパクション時にフックのコンテキストに何が起こるか

コンパクション(要約)は、スペースを空けるために会話の初期部分を要約します。Anthropic のフックガイドはそのリスクについて率直です。「これにより、重要な詳細が失われる可能性があります。」

フックのテキストは会話履歴の中にあり、コンパクションはそれを要約します。フックには、これを管理するための2つの方法があります。

コンパクション後の再注入。 SessionStart には compact マッチャーがあり、自動または手動のコンパクション後に実行されます。ガイドの推奨事項は次の通りです。「compact マッチャーを持つ SessionStart フックを使用して、すべてのコンパクション後に重要なコンテキストを再注入してください。」

要約自体の形成。 PreCompact はコンパクションの前に実行され、その出力は特別な役割を持ちます。「PreCompact フックが終了コード 0 で終了し、ブロックしない場合、Claude Code はその標準出力をコンパクション要約の指示として使用します。」同じ 10,000 文字の制限が適用され、長い出力は制限でカットされます。

PreCompact はコンパクションをブロックすることもできますが、タイミングによって結果が異なります。コンパクションが予防的にトリガーされた場合、ブロックすると会話は要約されずに継続されます。コンテキスト制限エラーから回復するためにトリガーされた場合、「根本的なエラーが表面化し、現在のリクエストは失敗します」。

PostCompact は、生成された要約を compact_summary というフィールドで受け取ります。これは、Claude Code 外でのログ記録やメモの更新に役立ちます。リファレンスでは、決定制御なしのサイドエフェクト用としてリストされています。

SessionStart のマッチャー

SessionStart はフックがコンテキストをリフレッシュするための主要な方法であるため、そのマッチャーを知っておく価値があります。リファレンスには5つリストされています。

  • startup: 新しいセッション用
  • resume: --resume、--continue、または /resume 用
  • clear: /clear 用
  • compact: 自動または手動のコンパクション用
  • fork: 既存のセッションからフォークされた新しいセッション用

タイミングに関する詳細もあります。起動時および /clear 後、SessionStart フックはバックグラウンドで実行されるため、すぐにタイピングを開始できますが、「Claude の最初の応答はフックが終了するまで待機するため、そのコンテキストは Claude に届きます」。また、バックグラウンドフックがまだ実行されている間に /clear を実行したり会話を切り替えたりした場合、それらが返す内容はセッションに適用されないとも記載されています。

CLAUDE.md が適しているケース

Anthropic はリファレンスでこれに直接答えています。「決して変わらない指示については、CLAUDE.md を優先してください。スクリプトを実行せずにロードされ、静的なプロジェクトの慣習を記述する標準的な場所です。」

SessionStart のセクションでも同様のことが述べられています。「スクリプトを必要としない静的なコンテキストについては、代わりに CLAUDE.md を使用してください。」

簡単なテスト:フックが実行されるたびにテキストが同じになるのであれば、それは CLAUDE.md に属します。ブランチ、時刻、最新のビルドなど、その瞬間に依存するのであれば、フックが適切なツールです。

CLAUDE.md には、コンパクションに関する独自の挙動があります。リファレンスには、コンパクション後に指示ファイルが再ロードされたときに発生する InstructionsLoaded のロード理由 compact が記されています。コンパクション後も維持するために静的なルールをフックに入れていたのであれば、CLAUDE.md がそれらのドキュメント化された保管場所です。CLAUDE.md ファイルがどのようにロードされ、どの程度のコストがかかるかを確認するには、Claude Code の /doctor がチェックする内容 に関するガイドを参照してください。

フックをオフにする

フックを削除するには、設定ファイルからそのエントリを削除します。すべてのフックを一時的にオフにするには、リファレンスに記載されている disableAllHooks 設定を使用します。これは設定の優先順位に従います。管理者にはより強力なバージョンがあります。管理設定で allowManagedHooksOnly を使用すると、ユーザー、プロジェクト、ローカル、およびプラグインのフックがブロックされます。

フックのコンテキストが消えたように見える場合は、スクリプトをデバッグする前にこれら2つの設定を確認してください。

よくある間違い

再開されたセッションの値を信頼する。 セッション途中のフック出力はトランスクリプトから再生されるため、タイムスタンプやコミット SHA が古くなっている可能性があります。

チャット内でフックの出力を探す。 追加されたコンテキストはチャットメッセージとして表示されません。

静的なルールをフックに入れる。 Anthropic は、決して変わらない指示には CLAUDE.md を推奨しています。

フックのテキストをコマンドとして書く。 命令的なフレーミングは、プロンプトインジェクション防御をトリガーする可能性があります。

長いレポートを返す。 10,000 文字を超えると、Claude にはプレビューとファイルパスしか渡されません。

クラウドセッションでローカルフックを期待する。 クラウドセッションはローカルのユーザー設定を読み込みません。

解決策:古い情報を残さず Claude に最新のコンテキストを与える

ステップ 1: 静的なルールを CLAUDE.md に移動する

フックが常に同じことを言っている場合は、そのテキストを代わりに CLAUDE.md に記述します。

ステップ 2: 再開時およびコンパクション後にリフレッシュする

変化する値については、resume および compact マッチャーを持つ SessionStart を使用します。

ステップ 3: 事実を書き、短く保つ

フックの出力は事実に基づいた記述にし、何が最新であるかをラベル付けし、10,000 文字以内に収めます。

ステップ 4: 理由を書き留める

ディレクトリが読み取り専用である理由やテストコマンドが異なる理由など、慣習の背後にある決定事項を、セッションごとに再生成されない場所に保管します。

MemoryLake でのセットアップ

フックは「現在形」が得意です(どのブランチにいるか、CI が今何と言っているか)。CLAUDE.md は固定された慣習が得意です。どちらも、チームがなぜその移行順序を選んだのか、どのアプローチがすでに除外されたのかといった、ゆっくりと変化し、複数のツールに届く必要のある決定事項には向いていません。

MemoryLake は、決定事項、制約、慣習などのプロジェクトコンテキストのための記憶レイヤーです。これらを一箇所で維持し、ChatGPT、Claude Code、Codex など、接続したアシスタントから利用できるようにします。

エントリはあなた自身の言葉で書きます。フック、設定ファイル、CLAUDE.md ファイル、セッションのトランスクリプト、コンパクションの要約、またはベンダーのストレージから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。フック、コンパクション、再開は Anthropic が説明する通りに機能します。

ステップ 1: API キーを作成する

サインインしてダッシュボードからキーを生成します。他の認証情報と同様に、リポジトリの外やフックスクリプトの外に保管してください。

エージェントで使用するために新しいキーが作成されコピーされる API キー画面を表示する MemoryLake コンソール
エージェントで使用するために新しいキーが作成されコピーされる API キー画面を表示する MemoryLake コンソール

ステップ 2: 最初の記憶をアップロードする

解決策のステップ 4 で書いた内容から始めましょう。慣習の背後にある理由や、フックが前提としている決定事項です。1つのエントリにつき1つの決定事項を記述します。

最初のドキュメントがアップロードされ、各ファイルが検索可能な記憶としてリストされている MemoryLake ワークスペース
最初のドキュメントがアップロードされ、各ファイルが検索可能な記憶としてリストされている MemoryLake ワークスペース

ステップ 3: AI とエージェントを接続する

Claude Code やその他の使用しているアシスタントを接続します。フックが現在の状態を提供し続け、その背後にある推論も並行して利用可能になります。

記憶レイヤーに接続可能な AI クライアントとエージェントフレームワークをリストした MemoryLake 統合画面
記憶レイヤーに接続可能な AI クライアントとエージェントフレームワークをリストした MemoryLake 統合画面

実践で何が変わるか

第一の違いは、役割分担が明確になることです。フックは分単位で変わるものを運び、CLAUDE.md は固定された慣習を運び、より長期的な決定事項は独自の場所を持ちます。

第二に、コンテキストが古くなりにくくなります。決定事項は、フックが実行された瞬間のトランスクリプトに固定されません。

第三に、ツール間での継続性です。同じリポジトリで作業する Codex や他のアシスタントも、独自のフック設定なしで同じ決定事項を利用できます。

Claude Code フックのベストプラクティス

変化するものにフックを使用する。 固定されたルールではなく、ブランチ、ビルド、イシューリストなど。

固定されたルールは CLAUDE.md に入れる。 スクリプトを実行せずにロードされます。

再開時にリフレッシュする。 再開時に再実行されるのは SessionStart だけです。

コンパクションを計画する。 compact マッチャーを使用して重要なものを再注入するか、PreCompact を使用して要約をガイドします。

コマンドではなく事実を書く。 フックのテキストがインジェクションのように見えるのを防ぎます。

サイズ制限を守る。 長い出力はファイルパスとプレビューになります。

何かが足りないときは /hooks を確認する。 各フックがどこから来ているかが表示されます。

結論

Claude Code のフックはセッションのライフサイクルの各ポイントで自動的に実行され、そのうちのいくつかは additionalContext を通じて Claude にコンテキストを追加できます(SessionStart、SubagentStart、UserPromptSubmit、ツールイベント、Stop、PostModelSwitch など)。そのテキストはシステムリマインダーとして Claude に届き、チャットメッセージとしては表示されません。

Claude Code はフックのテキストをトランスクリプトに保存し、再開時に過去のターン分を再生するため、値が古くなる可能性があります。再実行されるのは SessionStart だけです。SessionStart のマッチャーと PreCompact を使用して再開やコンパクションをまたいでコンテキストを管理し、静的なルールは CLAUDE.md に保持し、セットアップの背後にある決定事項はセッションごとに再生成されない場所に保管しましょう。

よくある質問

Claude Code のフックとは何ですか?

ユーザー定義のシェルコマンド、HTTP エンドポイント、MCP ツール呼び出し、LLM プロンプト、またはサブエージェントであり、Claude Code のライフサイクルの特定のポイントで自動的に実行されます。

フックは Claude にコンテキストを追加できますか?

はい。SessionStart、UserPromptSubmit、ツールイベントを含むいくつかのイベントは additionalContext を返すことができ、Claude はそれをシステムリマインダーとして読み取ります。

再開後に Claude が古いフック出力を見るのはなぜですか?

Claude Code は注入されたテキストをトランスクリプトに保存し、過去のターンについてはフックを再実行するのではなく再生するため、タイムスタンプやコミット SHA などの値が古くなることがあります。

セッションを再開したときにフックは再実行されますか?

SessionStart フックは再開時に再実行されます。過去のターンのセッション途中フックは再生されるだけで、再実行はされません。

コンパクション後もコンテキストを維持するにはどうすればよいですか?

compact マッチャーを持つ SessionStart フックを使用して再注入するか、PreCompact フックを使用してコンパクション要約の指示を与えます。

フックと CLAUDE.md のどちらを使うべきですか?

Anthropic は、決して変わらない指示には CLAUDE.md を推奨しています。現在のブランチや CI 結果のように変化するコンテキストにはフックを使用してください。

クラウドセッションでフックが実行されないのはなぜですか?

クラウドセッションはローカルの ~/.claude/settings.json を読み込まないためです。