AIチャットにコードベースをコンテキストとして渡す方法

なぜファイルの貼り付けでは限界があるのか

コンテキストウィンドウは、実際のリポジトリと並べるまでは巨大に感じられます。中規模のサービスなら2,000ファイル・20万行は軽くあります。ウィンドウに一部が収まるとしても、貼り付けた内容の大部分——ロックファイル、テストの足場、生成コード——は、質問が実際に関わる少数のファイルを薄めるノイズです。

失敗モードは拒否ではなく、もっともらしさです。雑多なソースの山を与えると、モデルはあなたが尋ねた特定のコールチェーンではなく、見たものの平均から答えます。ファイル名も検証可能な主張もない、自信に満ちた一般的な文章が返ってきます。

モデルが最初に必要とするもの:構造

チームに加わったシニアエンジニアは、初日に全ファイルを読みません。マップを受け取ります:何が何に依存し、エントリポイントがどこで、どのモジュールが重要か。リポジトリについて答えるLLMにも、同じ成果物が同じ順序で必要です——まず構造、ソースは必要に応じて。

• エントリポイント——実行が始まる場所:サーバーのブートストラップ、CLIのmain、ルートテーブル。
• レイヤー——コードベースが責務をどう整理しているか:API、サービス、データアクセス、UI。
• 正確な行範囲付きのシンボル——各ファイルの関数とクラス。フォローアップの質問が正確な範囲を取り出せます。
• 依存エッジ——どのファイルがどれをインポートしているか。これが「返金ロジックはどこ?」をコールグラフ上の探索に変えます。
• 明示的な契約——マップに基づいて答え、足りないファイルの名前を挙げ、実装を決して捏造しないようモデルに指示する文言。

ビフォー・アフター

同じ質問、2つの入力。ビフォー:「返金はどう動く?」+貼り付けた12ファイル——答えは一般的なECサイトの作文。アフター:トークン予算付きバンドル1つ——答えは src/services/order-service.ts を行範囲で引用し、refundOrder からリポジトリ、プールへと辿り、欠けていることが分かる1つのマイグレーションファイルを要求します。「アフター」の入力の実際の姿がこれです(サンプルプロジェクトで生成された本物のバンドルからの抜粋):

# Context bundle — "how does order refund work,
# and what could break if I change it?"

> Static-analysis map of sample-shop (21 files, 271 lines).
> Structure only — function bodies are absent unless included below.
> Answer from this file alone; where it is silent, name the file
> you need. Never invent an implementation.

## Files (16)

### `src/api/orders.ts`
27 lines · API Layer · exports `listOrdersHandler`, `refundOrder`
  · imports `order-service.ts`, `order-repo.ts`, `pool.ts`, `errors.ts`

### `src/services/order-service.ts`
34 lines · Service Layer · exports `refundOrder`, `createOrder`
  · imports `order-repo.ts`, `errors.ts`, `money.ts`

予算と、ソースを含めるタイミング

コンテキストバンドルにトークン予算があるのは、チャットウィンドウに限りがあり、詰め込みすぎると費用と精度の両方を損なうからです。役に立つ作法はこうです:まず構造だけで始め、モデルに足りないファイルを言わせ、そのファイルだけソースを含める。本物の実装3ファイルは、当てずっぽう30ファイルに勝ります。

同じ作法が最もよくあるフォローアップ——「次に何を貼ればいい?」——への答えにもなります。マップはすでに、どのシンボルがどのファイルの何行目に住んでいるかを知っているので、2回目は探索ではなく取得です。ワークフロー全体はこれだけです:方位を定め、問い、取り出し、解決する。