コードベースマップの作り方:シンボル、レイヤー、トークン予算

推測ではなくパース

マップの品質はパーサーの品質で決まります。ContextBridgeはtree-sitter——コードエディタが使っているのと同じインクリメンタルパーサー群——でコードを解析します。それはブラウザのタブ内でWebAssemblyとして動き、15言語をカバーします。すべてのシンボルは本物のパースツリーから来るので、行範囲は推定ではなく正確です。

この正確さには意図的な限界があります。512KBを超えるファイルは切り詰められ、バイナリはスキップされ、依存ツリー・ビルド成果物・ロックファイルは解析前に剪定されます。ハードキャップは4,000ファイル——ラップトップで解析が数分ではなく数秒で終わるように選ばれた値です。

レイヤー、ハブ、エントリポイント

シンボルテーブルの上に、アナライザは分類を行います。ファイルはレイヤー——API、サービス、データ、UI、インフラ——にまとまり、パス・インポート・命名から推定されます。最も多くインポートされるファイルはハブとして浮上し、ブートストラップ、main、ルートテーブルはエントリポイントとして浮上します。これは実際の(小さな)サンプルプロジェクトのレイヤーテーブルで、生成されたマップからの逐語引用です:

| Layer         | Files | Lines | Notable                               |
|---------------|-------|-------|---------------------------------------|
| Core          | 4     | 60    | order-repo.ts, server.ts              |
| API Layer     | 3     | 53    | orders.ts, customers.ts, routes.ts    |
| Service Layer | 2     | 50    | order-service.ts, customer-service.ts |
| UI Layer      | 2     | 23    | order-list.tsx, format.ts             |
| Data Layer    | 1     | 13    | 001_init.sql                          |
| Test Layer    | 1     | 8     | order-service.test.ts                 |

トークン予算が何が残るかを決める

すべての成果物は、あなたが選んだトークン予算(軽いスケッチから上限なしのダンプまで)に対して生成されます。ランカーは、表明された質問への関連性——言語横断の用語拡張付きなので、ベトナム語や中国語の質問でも英語のコードにマッチします——と構造的重要度(ハブ、エントリポイント、マッチしたシンボルのインポートパス上のファイル)でファイルをスコアリングします。

収まらなかったものは黙って捨てられません:成果物は省略したものを列挙し、自身の限界を冒頭に明記します。限界を認める予算付きマップは、限界を隠す無制限ダンプより、あなたにとってもモデルにとっても価値があります。

静的解析が知り得ないこと

ここでは正直さが印象深さより重要です。静的マップはランタイムの挙動を決して見られません:依存性注入された実装、リフレクション、動的ディスパッチ、フィーチャーフラグ、環境固有の配線はすべて不可視です。レイヤーのラベルはヒューリスティックであり、ヒューリスティックは規約を破りたがるコードベースでは間違え得ます。

だからマップはそのままのものとして扱いましょう:方位定めであって、絶対的真実ではありません。生成される成果物も同じ考え方の周りに作られています——モデルに対し、与えられた構造から答えること、持っていないファイルの名前を挙げること、実装を決して捏造しないことを指示するのです。「分からない」と言うことを許されたマップこそ、次にどこを見るべきかを信頼して任せられるマップです。