カスタムPostToolUseフックによるプロジェクトツリー外でのオンデマンドCLAUDE.md読み込み

Claude CodeにおけるCLAUDE.mdの読み込み動作

ソースでは、Claude Codeが異なる条件下でCLAUDE.mdファイルをどのように処理するか詳細に説明されています：

• 階層的な読み込み： サブディレクトリでセッションを開始すると、ローカルのCLAUDE.mdと親ディレクトリのCLAUDE.mdファイルの両方が読み込まれます。例：root/a/でのセッションはroot/a/CLAUDE.mdとroot/CLAUDE.mdの両方を読み込みます。
• オンデマンドの子ディレクトリ読み込み： 現在のセッションのルートディレクトリの子ディレクトリは、Claudeがそれらのディレクトリ内のファイルにアクセスする際に、それぞれのCLAUDE.mdファイルを読み込みます。例：root/でのセッションは最初にroot/CLAUDE.mdを読み込み、その後root/a/内のファイルをClaudeが読み取る際にroot/a/CLAUDE.mdを読み込みます。
• フラグによる追加ディレクトリアクセス： --add-dirをCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1と共に使用すると、プロジェクトツリー外のディレクトリ内のCLAUDE.mdファイルにアクセスできますが、これらはオンデマンドではなくセッション開始時に読み込まれます。

問題点：外部ディレクトリのCLAUDE.mdファイルがオンデマンドで読み込まれない

著者は、あるプロジェクトで作業中に、Claudeにセッションのディレクトリツリー外のディレクトリからファイルを読み取るよう指示した場合、それらの外部ディレクトリ内のCLAUDE.mdファイルは自動的に読み込まれないと指摘しています。これにより、コンテキストの段階的な開示に問題が生じ、毎回手動での介入が必要になります。

解決策：カスタムPostToolUseフック

この解決策は、以下の機能を持つPostToolUseフックを作成することを含みます：

• 各ツール呼び出し時に、Claudeがプロジェクトツリー外で動作しているかどうかをチェック
• そのディレクトリから上方向に探索し、CLAUDE.mdファイルを探す
• 見つかった場合、Claudeにそれらを読み取るよう指示するためにコード2で終了
• 既に表示されたファイルをセッションスコープの一時ファイルで追跡し、重複した指示を避ける

SessionStopフックは、追跡に使用された一時ファイルをクリーンアップします。著者は、このPostToolUseフック機能を実装するcheck_claude_md.pyというスクリプトを提供しています（元の投稿にソースリンクあり）。

実用的な実装

このアプローチは、--add-dirフラグをCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1と共に使用した場合に、外部ディレクトリのCLAUDE.mdファイルがセッション開始時のみ読み込まれるという特定の制限に対処します。ツール呼び出しを傍受し、プロジェクトツリー外での操作をチェックすることで、このフックはプロジェクトツリー内の子ディレクトリが動作するのと同様に、オンデマンド読み込みを可能にします。

この種のカスタムフックは、複数のプロジェクトを頻繁にまたがって作業する開発者や、外部ディレクトリから共有コンテキストファイルを参照する必要があり、毎回手動でClaudeにCLAUDE.mdファイルを読み取るよう指示したくない開発者にとって有用です。