AIエージェント開発に「インデックス」という考え方を持ち込めないか

AIエージェントを使った開発では、README、CLAUDE.md、AGENTS.mdなどにプロジェクトのルールや仕様を書き、エージェントに最初に読ませるやり方がよく使われる。

これはかなり強力だ。

AIのメモリ機能や、過去の会話履歴に頼るのではなく、リポジトリ内に置かれたドキュメントを唯一の正として扱える。

仕様が変わったらドキュメントを更新する。
次に起動したエージェントも、その最新の仕様を読む。

いわゆる仕様駆動開発とAIエージェントは、かなり相性がいい。

ただ、実際にやっていると一つ気になることがある。

ドキュメントを読むだけで、かなりのトークンを消費する。

仕様書が育つほど、毎回読むコストが高くなる

最初はCLAUDE.md一枚だけだったものが、プロジェクトが育つにつれて増えていく。

たとえば、

• 要件定義
• 技術仕様
• アーキテクチャ設計
• API仕様
• ディレクトリ構成
• コーディング規約
• テスト方針
• ADR
• 運用手順

などだ。

すると、エージェントはタスクを始めるたびに大量の文書を読むことになる。

もちろん、コンテキストウィンドウが大きくなれば全部入れることはできる。

しかし「入れられる」ことと「毎回入れるべき」ことは違う。

数万トークンある仕様書のうち、今回必要なのは認証仕様の一節だけ、ということは珍しくない。

そこでふと思った。

データベースにはインデックスがある。
同じ発想を、AIエージェントのコンテキスト取得にも使えないだろうか。

データベースは毎回Full Scanしない

データベースで大量のデータを検索するとき、毎回すべての行を先頭から読むわけではない。

インデックスを使って、

「必要なデータがどこにあるか」

を先に特定する。

その後、必要なデータだけを取得する。

AIエージェントも同じ構造にできるのではないか。

現在の仕様駆動開発では、エージェントに仕様書そのものを渡している。

これを、

仕様そのものではなく、まず仕様へ到達するためのインデックスを渡す

形に変える。

たとえば、ユーザーから、

「ログイン処理を変更して」

と言われたとする。

エージェントは最初に巨大な仕様書を読むのではなく、まず小さなインデックスを検索する。

capability: auth.login

docs:
  - docs/product/auth.md#login
  - docs/architecture/session.md#authentication

code:
  - src/auth/**
  - src/api/login.ts

tests:
  - tests/auth/login.test.ts

tools:
  - test.auth
  - db.schema.users

related:
  - auth.session
  - security.rate-limit

これを見るだけで、

• どの仕様を読むべきか
• どのコードを見るべきか
• どのテストを実行すべきか
• 必要ならどのツールを使うべきか

が分かる。

そして必要になった箇所だけを読む。

不足していれば、relatedにある次の候補を読む。

それでも足りなければ、通常のgrepや検索にフォールバックする。

つまり、

Index Scan → 必要箇所の取得 → 不足時のみ追加探索

という流れだ。

「仕様書のインデックス」だけではなく「ツールのインデックス」にする

この発想で特に面白いと思っているのが、ドキュメントだけを対象にしないことだ。

LLMは基本的には、テキストを受け取り、テキストを返す。

そこにAPI、MCP、シェル、ブラウザ操作などのツールを組み込むことで、エージェントとして汎用的になる。

であれば、

ドキュメントとツールに共通のインデックスを貼ればいい。

たとえば、

auth.login

という共通IDに、

• 要件
• 設計
• 実装
• テスト
• DBスキーマ
• ブラウザ操作
• 検証コマンド

を紐づける。

イメージとしてはこうだ。

                    requirement
                         |
                    architecture
                         |
docs ----------- auth.login ----------- code
                         |
                       tests
                         |
                       tools

エージェントにとって重要なのは、

「何を知っているか」

だけではない。

「その領域について何ができるか」

も同時に知る必要がある。

ならば、知識とアクションを別々の探索空間にする必要はない。

Capability = Knowledge + Action + Validation

という単位でまとめてもいい。

インデックスは真実を持ってはいけない

ただし、この仕組みには重要な原則がある。

インデックス自体を仕様書にしてはいけない。

たとえばインデックスに、

auth.login = JWT認証

と書いてしまう。

その後、本当の仕様書ではCookie Sessionに変更したのに、インデックスの更新を忘れたとする。

すると真実が二つできてしまう。

これは危険だ。

データベースのインデックスも、本体データとは別物だ。

インデックスの役割は、

「データがどこにあるかを示すこと」

であって、

「データそのものになること」

ではない。

同じように、

仕様書はSource of Truth。
インデックスはSource of Location。

と分離するのが重要だと思う。

インデックスには、

id: auth.login
source: docs/product/auth.md
anchor: "#login"

までを書く。

実際の仕様は必ず参照先に置く。

ファイル単位ではなく、セクション単位で参照したい

さらに、インデックスが、

auth.login → docs/auth.md

だけでは不十分だ。

結局auth.md全体を読むことになる。

なので、

auth.login → docs/auth.md#login

のように、できるだけ細かい単位で参照する。

大きなドキュメントなら、

AUTH-LOGIN-BEGIN
...
AUTH-LOGIN-END

のような安定した境界を持たせてもいい。

するとエージェントは、その区間だけを取得できる。

これはトークン削減だけでなく、不要な情報による判断ノイズも減らせる。

AGENTS.mdは「百科事典」ではなく「ブートローダー」にする

この考え方を突き詰めると、AGENTS.mdやCLAUDE.mdの役割も変わる。

大量の仕様を書く場所ではなくなる。

代わりに、

「このリポジトリでどう情報を探すか」

だけを書く。

たとえば、

1. タスクを受け取ったら最初に.agent/indexを検索する
2. capabilityを特定する
3. normativeな仕様だけを読む
4. 不足時のみrelatedを辿る
5. 最後に指定されたvalidationを実行する
6. indexと仕様が矛盾した場合、仕様を優先する

程度でいい。

つまり、

AGENTS.md = ブートローダー
Index = クエリプランナ用メタデータ
docs = Source of Truth

という三層構造になる。

一番難しいのはインデックスの陳腐化

もちろん問題もある。

一番怖いのは、

仕様書は更新されたのに、インデックスだけ古い

状態だ。

通常の全文探索なら遅くても仕様を見つけられる。

インデックス方式は高速だが、インデックスから漏れた情報は見つからない可能性がある。

データベースでインデックスが成立するのは、データ更新とインデックス更新が一体になっているからだ。

AIエージェント用のインデックスも同じで、

document update
↓
index regenerate
↓
validation
↓
commit

という流れにすべきだと思う。

手作業でindex.yamlを更新する方式は、おそらく長期運用では壊れる。

なので各ドキュメントにメタデータを持たせ、

---
id: auth.login
type: product-spec
related:
  - auth.session
tests:
  - test.auth.login
---

そこからインデックスを自動生成する方がよさそうだ。

つまり、インデックスは手書きの仕様ではなく、生成物にする。

インデックスが外れたらFull Scanに戻ればいい

そして、インデックスは絶対的なものにしない。

検索の最初に使うだけだ。

理想的には、

Task
↓
Index Lookup
↓
候補の仕様を読む
↓
十分？
 ├─ Yes → 実装
 └─ No
     ↓
 relatedを辿る
     ↓
 grep / semantic search
     ↓
 必要ならFull Scan

とする。

データベースのクエリプランナと同じで、

Index Scanが効くなら使う。

効かなければ別の探索手段を使う。

重要なのは、

インデックスによって探索を禁止するのではなく、探索順序を最適化すること

だ。

LLMにプロジェクト全体を覚えさせるのではなく、探索方法を覚えさせる

この発想の本質は、トークン削減だけではないと思っている。

現在のAIエージェント開発では、

「必要な知識を全部コンテキストに入れる」

方向に寄りやすい。

しかし別の考え方もある。

プロジェクト全体をコンテキストとして持たせるのではなく、
プロジェクトを探索する能力をコンテキストとして持たせる。

つまり、

巨大なKnowledge Context

ではなく、

小さなIndex
+
必要な情報を取得するTool

を持たせる。

必要な情報は、その都度取得する。

これは、AIエージェントが巨大なコードベースを扱うようになるほど重要になってくる気がする。

今の多くのエージェント開発は、まだかなり「Full Table Scan」に近い。

その次に来るのは、

semantic key → index scan → pointer chase → 必要なら追加scan

という仕組みなのかもしれない。

仕様駆動開発の次のテーマは、

「何を仕様書に書くか」

だけではなく、

「AIがその仕様へどう到達するか」

になるのではないかと思っている。