AIにrepo全体を読ませる前に、Context Packで初動調査を軽くしてみた

この記事は、自分の個人開発で試している AI 初動調査ツールの測定ログをもとにした下書きです。数字は3つの個人開発repoでの測定結果であり、一般的なベンチマークではありません。

関連する考え方として、以前 CodexでPRを量産する前に、Issue・状態・判断ログをつなぐ「文脈ハブ」を作る という記事を書いた。今回は、その中でも「AIに渡す最初の文脈をどう小さくするか」に絞った測定メモとして読んでもらえると嬉しい。

この記事で伝えること

AIコーディングエージェントにrepo調査を頼むとき、いきなりrepo全体を読ませるより、先に「読む順序」を作っておくと扱いやすい場面があった。

自分はそのために、repoの中から次の候補だけを小さくまとめる仕組みを作って試している。

• 最初に読むべきファイル
• test候補
• contract候補
• configやsource root候補
• PR / Issue metadataから見える開発領域の偏り
• 未確認範囲

この記事では、こうした最初の文脈を Context Pack と呼ぶことにする。

今回、3つの個人開発repoで測ったところ、推定token数は合計で約18.6万から約4,800まで下がった。自分の測定条件では、削減率は約97%になった。

ただし、これは「AIが正しく実装できる」ことを示すものではない。あくまで、初動で読む文脈を小さくし、候補と未確認事項を分けやすくするための測定である。

なぜ作ったか

CodexのようなAIコーディングエージェントは、repoを広く読める。

ただ、自分の使い方では、広く読めることと、最初から広く読ませることは少し分けて考えた方がよさそうだった。

自分の個人開発では、AIに調査や実装を頼む前に、毎回こういう迷いがあった。

• まずどのファイルを読ませるべきか
• testはどこにあるのか
• public contractやschemaに近いファイルはどれか
• 変更候補が本当に影響範囲なのか、それともただの名前一致なのか
• PRやIssueの履歴から、今どの領域が荒れているのか
• AIが「全部見ました」と言っても、どこを見ていないのか

この状態でrepo全体を読ませると、入力tokenが大きくなりやすく、AIの返答も長くなりがちだった。

そこで、最初にrepoを機械的に薄くスキャンして、AIに渡す入口だけを作れないか試してみた。

作ったもの

やっていることはシンプルで、repo内に軽量なスクリプトを入れて、次のようなレポートを生成する。

docs/repo-audit/context_pack.md
docs/repo-audit/evidence.tsv
docs/repo-audit/metrics.tsv
docs/repo-audit/scorecard.md

Context Packには、コード全文やdiff全文は入れない。

代わりに、候補のパス、理由、件数、未確認事項を入れる。

たとえば、AIに渡す最初の文脈はこういう形になる。

- selected files: 129 / total tracked 129
- estimated baseline tokens: 92623
- test candidates: 10
- contract candidates: 24
- PR cluster other rate: 0%
- risk: scopeやfile size上限で見ていない範囲がある
- suggested read order:
  - AGENTS.md
  - README.md
  - src/...
  - tests/...

ここで意識したのは、「これは候補であって結論ではない」と明示することだった。

Context Packは、影響範囲を確定するものではない。AIが読む順序を作るための入口として扱っている。

測定方法

3つの個人開発repoに対して、同じ手順で測った。

ざっくりした流れは次の通り。

bash scripts/ai_audit_effect_measure.sh HEAD requirement.md

測定では、repo内の対象ファイルのbyte数から推定tokenを出し、生成されたContext Packの推定tokenと比較した。

推定tokenは厳密なtokenizerではなく、bytes / 4 の近似として扱っている。

そのため、数字は「正確な課金token」ではなく、「読む文脈量の相対比較」として見ている。

結果

測定結果は次の通り。

repo	before	after	reduction	context budget	contract	scorecard	tests	contracts	evidence
Repo A	76,023	1,416	98%	PASS	PASS	PASS	2	5	10
Repo B	17,096	1,212	92%	PASS	PASS	PASS	0	1	4
Repo C	92,623	2,206	97%	PASS	PASS	PASS	10	24	37

合計ではこうなった。

指標	値
before推定token	185,742
after推定token	4,834
weighted reduction	97%
平均after推定token	1,611
context budget PASS	3/3
contract PASS	3/3
scorecard PASS	3/3
test候補	12
contract候補	30
evidence行	51

この結果だけ見ると、自分の測定対象では初動調査の入力文脈をかなり小さくできた。

特に、AIに「まずこれを読んで」と渡す量が、1repoあたり約1,100から2,200推定tokenに収まったのは、個人的には扱いやすかった。

使ってみてよかったところ

一番よかったのは、AIに渡す前に読む順序を作れることだった。

たとえば、repoに入ってすぐAIにこう頼める。

まず docs/repo-audit/context_pack.md を読んでください。
そこにある candidate / unknown / verification を分けて扱ってください。
必要になったファイルだけ追加で読んでください。

これだけでも、最初の返答の方向が少し変わった。

repo全体をざっと要約するよりも、候補、未確認、次に読むファイルの話に寄せやすくなった。

もうひとつよかったのは、PR / Issue metadataを横軸として使えることだった。

repo内のscanは、source、test、contractのような縦軸を作る。

一方で、PRやIssueのmetadataを見ると、「最近どの領域の修正が繰り返されているか」が見える。

たとえば、次のようなclusterに分ける。

ci-workflow
planning-orchestration
mvp-scaffolding
data-modeling

もちろん、これはmetadataだけの分類なので、正しい影響範囲そのものではない。

ただ、最初にどの領域を疑うかの優先度候補としては使いやすかった。

逆に弱かったところ

弱いところもある。

まず、PR数が少ないrepoでは、PR clusterは強い根拠としては使いにくい。

実際、1つのrepoではPRサンプルが少なく、clusterの評価は insufficient_pr_sample として扱った。

これは失敗というより、「横軸の根拠としては弱い」と明示するための状態として扱っている。

また、test候補が0件になるrepoもあった。

この場合、Context PackやscorecardがPASSでも、実装検証の強さは別に見た方がよい。

PASSはあくまで「レポート形式、上限、候補収集の最低条件を満たした」という意味に限定している。

PASSを誤解しない

この仕組みで特に気をつけているのは、PASSを強く見せすぎないことだ。

PASSは、次を保証するものではない。

• QA完了
• セキュリティ安全性
• 仕様適合
• 完全な影響範囲
• AIが正しく理解したこと

むしろ、Context Packには未確認事項を必ず残す。

たとえば、こういう注意を入れる。

- active scopeやfile size上限で見ていない範囲がある
- candidateは影響確定ではない
- PR titleによる分類はmetadata-onlyで誤分類しうる
- test候補が0件なら検証力は弱い

AIに渡す文脈を小さくするほど、見ていない範囲も生まれる。

そのため、削ることと、削った事実を明示することをセットで扱うようにしている。

自分の中での結論

今回の測定では、少なくとも自分のAI初動調査の前処理としては効果がありそうだった。

特に相性がよさそうだったのは、次の用途である。

• repo全体を読む前のContext Pack作成
• test / contract / evidence候補の抽出
• PR / Issue metadataからの横軸クラスタ把握
• tokenを削減しながら読む順序を作ること
• 未確認事項を最初から分けること

一方で、これは自動レビューや品質保証のツールではない。

「AIに最初に何を読ませるか」を決める補助ツールとして使うくらいが、今のところ自分には合っている。

次にやること

次は、測定対象を増やしたい。

特に見たいのは次の3種類である。

• 小規模Web app
• monorepo
• GitLab repo

GitLabの場合は、Merge Request metadataをTSVで渡すことで、同じような横軸clusterに使える見込みがある。

ただし、GitLab実repoでの測定はまだこれからである。

また、今後は「tokenを減らせたか」だけではなく、「AIが本当に読むべきファイルを外していないか」も見ていきたい。

最終的には、導入先repoごとに期待候補をfixture化して、漏れた候補を次の改善に戻す形にしたい。

まとめ

AIにrepo調査を頼むとき、最初からrepo全体を読ませるより、先に読む順序を作った方が安定する場面がありそうだ。

今回の3repo測定では、推定tokenは約18.6万から約4,800まで下がり、Context Packは1repoあたり約1,100から2,200推定tokenに収まった。

ただし、これは品質保証ではない。

自分の中では、Context Packは「AIに渡す最初の地図」に近い。地図に載っていない場所があることも、同時に伝えるものとして扱いたい。

AI開発では、たくさん読ませることよりも、何を読ませたか、何を読ませていないかを分けることが効く場面もあるのだと思う。