ある開発者が、AIコーディングエージェントがセッションをまたいで「現在地」を把握できるようにする、3層構造のコードベース・マップを公開しました。

なぜAIエージェントにマップが必要なのか

チャットベースのコーディングアシスタントは、プロンプトウィンドウが開いている間だけリポジトリのメンタルモデルを構築します。コンテキストウィンドウが閉じると、そのモデルは消失してしまい、エージェントはシンボル、インポート、ファイル間の関係をゼロから再発見しなければならなくなります。このやり取りは計算リソースを浪費させ、開発者がファイル間を移動したり、休憩後にプロジェクトに戻ったりした際に、エージェントの有用性を低下させます。

マップを構成する3つのレイヤー

  • 構造レイヤー (Structural layer) – シンボル、関数呼び出し、インポート文のカタログ。 「何が何を呼び出しているか」という静的な問いに答えます。
  • 時間レイヤー (Temporal layer) – ファイルの変更頻度（churn rate）や所有権の履歴など、gitから得られるシグナル。コードのどの部分が最も頻繁に変更され、誰がそれらに触れる傾向があるかを示します。
  • 振る舞いレイヤー (Behavioral layer) – エージェント自身の編集およびナビゲーション履歴から抽出された、実世界での使用パターン。コーディングセッション中に実際にどのファイルが一緒に開かれているかを明らかにし、静的解析では見落とされる「真の隣接ファイル」を特定します。

振る舞いレイヤーは最も重要です。なぜなら、それは単にコードがどのように接続されているかではなく、開発者（およびエージェント）が実際にどのように作業しているかを反映しているからです。

エージェントにマップを供給する2つの方法

  1. Ambient Path – すべてのインタラクションに注入される簡潔なサマリー。追加の呼び出しなしに、「あなたはXモジュールにいます。これらのシンボルが近くにあります」といったスナップショットをエージェントに即座に提供します。
  2. Deep Path – より詳細な情報が必要なときにエージェントが呼び出せる、オンデマンドのクエリツール。例えば、頻繁に一緒に変更されるファイルのリストや、最近の所有権のタイムラインなどが含まれます。

Ambient（常時提供）情報とDeep（詳細）情報を分けることで、日常的なプロンプトを軽量に保ちつつ、必要なときには深い情報を提供できます。

システムを軽量に保つための設計ルール

  • 重量級のLanguage Serverは避ける。 このマップは、完全な型推論ではなく、浅いパース（shallow parsing）に依存しています。目的は、成熟した静的解析エンジンを凌駕することではなく、振る舞いの洞察によってそれらを補完することにあります。
  • グラフをプロジェクトごとに限定する。 このシステムは、リポジトリをまたいでグローバルな依存関係グラフを構築することはありません。この限定的な範囲により、メモリ使用量を抑え、更新を高速化します。
  • 既存のメモリ・ストアを再利用する。 ファイル変更ログは、エージェント自身のツール呼び出しのメモリから取得するため、データの重複保存を避け、データソースの一貫性を保てます。

実践的なマップの構築手順

  1. 構造データを収集：ソースファイルを素早くスキャンしてシンボルとインポート行を抽出します。
  2. 時間メトリクスを取得：リポジトリのgit履歴から、どのファイルに最も多くのコミットがあるか、誰が作成したかを記録します。
  3. 振る舞いのシグナルを収集：実際のコーディングセッション中にエージェントが行うファイルのオープン、編集、ナビゲーションのアクションをログに記録します。これらのログは、振る舞い上の隣接関係を定義する「共起（co-occurrence）」行列の基礎となります。
  4. Ambient Pathを構成：現在のタスクに最も関連性の高いシンボルとファイルの短い順序付きリストを作成します。
  5. Deep Pathを公開：軽量なクエリ関数（例：「最近のセッションで一緒に編集されたファイルのリスト」）として公開します。

高速なフックが編集のたびに内容をキャプチャし、低速なバックグラウンドのスキャンが変更頻度の統計を再計算します。これらを組み合わせることで、開発者のワークフローを妨げることなく、マップを最新の状態に保ちます。

開発を通じて得られた教訓

  • Ambientとオンデマンドを分離する。 常に存在するサマリーを最小限に抑えることでトークンの肥大化を防ぎ、より詳細なクエリはオプションとして提供します。
  • タスクごとにコンテキストの優先順位をつける。 現在の編集対象に合わせてAmbientシンボルの順序を調整することで、より有用な提案が可能になります。
  • 積極的、かつインテリジェントに更新する。 高速なフックで頻繁な変更をキャプチャし、定期的なスキャンで低頻度の変更や所有権の移り変わりを処理します。
  • 速度面では浅いパースが有利。 深い型解析は、このマップの強みである「振る舞いの洞察」を提供することなく、レイテンシ（遅延）を増大させるだけです。

まとめ: 静的な構造、git由来の履歴、そして実世界での使用パターンを、コンパクトな2層アクセスモデルに層状化することで、開発者はAIコーディングエージェントに永続的なコードベース・マップを提供できます。常に存在するサマリーを最小限に抑えることが、トークンの肥大化を防ぐ鍵となります。