エージェントコンテキストローダー
概要
プロジェクト階層全体で AGENTS.md ファイルを自動的に検出して読み込む、AI コーディングエージェント向け機能。このスキルは現在のワークスペースとその親ディレクトリをスキャンしてエージェント指示ファイルを特定し、その内容を抽出してアクティブなエージェントセッションに完全な運用コンテキストを提供します。
前提条件
- 任意のディレクトリ深度に1つ以上の
AGENTS.mdファイルが含まれるプロジェクトワークスペース - ディレクトリツリーを走査するための読み取りおよび Glob パーミッション
- 複数の候補ファイルが存在する場合にファイル内容を検索するための Grep アクセス
手順
- 現在の作業ディレクトリとすべての親ディレクトリ(ファイルシステムルートまたはリポジトリルートまで)をスキャンして、
AGENTS.mdまたはagents.mdという名前のファイルを探します。 - 現在のワークスペースのサブディレクトリを検索し、サブプロジェクトやモジュールに適用される追加の
AGENTS.mdファイルを探します。 - 読み込み順序を決定します。リポジトリルートに近いファイルが最初に読み込まれ(グローバルコンテキスト)、より深いディレクトリのファイルは後で読み込まれます(オーバーライドまたは補足)。
- 検出された各
AGENTS.mdファイルを読み込み、その指示ブロック、ワークフロー定義、制約宣言を抽出します。 - 指示を統合コンテキストにマージし、レベル間の競合(例:サブディレクトリのエージェントがルートレベルのルールをオーバーライドする)を記録します。
- 読み込まれたコンテキストを構造化されたサマリーとして表示します:ソースファイルパス、指示数、検出された競合。
- 検出結果を現在のセッションにキャッシュし、後続のアクティベーションでファイルシステムの冗長なスキャンを回避します。
出力
- 検出された
AGENTS.mdファイルパスの順序付きリスト(ディレクトリ深度付き) - 検出されたすべてのエージェントコンテキストを結合したマージ指示セット
- レベル間の矛盾する指示を強調表示する競合レポート
- 結果が新しいものか再利用されたものかを示すセッションキャッシュステータス
エラーハンドリング
| エラー | 原因 | 解決策 |
|---|---|---|
AGENTS.md が見つからない | ワークスペースにエージェント指示ファイルがない | 正しい作業ディレクトリを確認する;必要であればプロジェクトルートに AGENTS.md を作成する |
| ディレクトリ走査のパーミッション拒否 | ワークスペース上の制限された親ディレクトリ | スキャン深度をリポジトリルート(.git/ の存在で検出)に制限する |
| 循環シンボリックリンク検出 | シンボリックリンクされたディレクトリが無限の走査ループを作成する | スキャン中にシンボリックリンクされたディレクトリをスキップする;シンボリックリンクパスを含む警告をログに記録する |
| レベル間の指示の競合 | サブディレクトリの AGENTS.md がルートレベルのファイルと矛盾する | 出力で競合をフラグする;デフォルトでより具体的な(深い)指示を適用する |
| ファイルエンコーディングエラー | AGENTS.md が UTF-8 以外のエンコーディングを使用している | Latin-1 フォールバックを試行する;ファイルパスとエンコーディングの問題を報告する |
例
例1: パッケージごとのエージェント指示を持つモノレポ
- 構造:ルート
AGENTS.mdがグローバル規約を設定;packages/api/AGENTS.mdが API 固有のツールルールを追加。 - 結果:両方のファイルが順序通りに読み込まれる。API 固有のルールは競合なくグローバルコンテキストを補足する。
例2: 競合するコミットポリシーを持つネストされたワークスペース
- 構造:ルート
AGENTS.mdは「常にコミットに署名する」と指示;services/legacy/AGENTS.mdは「コミット署名をスキップ」と指示。 - 結果:競合が検出され報告される。デフォルトでより深い(レガシー)指示が適用され、オーバーライドに関する警告が表示される。
例3: エージェントファイルのない初回セットアップ
- 構造:
AGENTS.mdがどこにもない新しくクローンされたリポジトリ。 - 結果:スキャンが完了し、0 ファイルが見つかる。出力には、リポジトリルートに最小限のテンプレートで
AGENTS.mdを作成する提案が含まれる。
リソース
- Claude Code AGENTS.md 仕様:https://docs.anthropic.com/en/docs/agents
- エージェント設定のためのモノレポワークスペースパターン:https://docs.anthropic.com/en/docs/claude-code
- 階層的設定読み込みのためのファイル発見のベストプラクティス