この記事のゴール
AIコーディング支援を使っていて、こんな経験はないでしょうか。
「このバグ直して」ってリポジトリごと渡したのに、全然関係ないファイルをいじってくる。
「この機能どこで実装されてる？」って聞いたら、それっぽいけど微妙にズレた答えが返ってくる。
小さなToyプロジェクトだと天才なのに、仕事の本物のコードベースになった途端に急に頼りなくなる。
あの感じ…ありますよね。
正直に言いましょう。あれ、AIが賢くないからじゃないんです。
こっちが地図を渡してないから、なんですよね。
この記事では、「コードベースをAIに丸ごと渡す」のをやめて、コードベースを“地図”に変換してから任せるという発想と、その具体的な手順を書きます。明日、自分のリポジトリでそのまま試せるコードとプロンプトを厚めに入れました。AI開発にまだ慣れていない方でも読み進められるように、専門用語は出すたびに噛み砕きます。
ゴールはひとつ。「巨大なコードがこわくなくなる」。それだけです。
1. 「コードを丸ごと渡したのに、見当外れ」——あの感覚の正体
まず、よくある失敗の場面を思い出してみましょう。
あなたは、初めて触る5,000ファイルくらいの中規模リポジトリに配属されました。「決済まわりのバグを直したい」。とりあえずこうします。
grep -rn "checkout" .
# → 217件ヒット。controller, service, util, test, 設定ファイル…どれが本筋か分からない
200件以上のヒット。どれが本丸で、どれがただの命名のかぶりなのか、ぱっと見では分かりません。これ、人間でも迷子になる「grep地獄」ですよね。
で、思うわけです。「AIに全部読ませたら一発じゃない？」と。
でも、5,000ファイル全部をチャットに貼ることはできません。仮に貼れたとしても、AIはどこが重要で、どこが脇道かを教えてもらっていないので、結局あなたと同じように迷子になります。
ここで大事な気づきがひとつあります。
情報を見つけることと、理解することは、全然違う。
grepは「情報を見つける」のは得意です。でも「このコードベースがどう成り立っているか」を理解するのは、また別の話なんですよね。そして今のAIに足りていないのは、たいてい後者のほうです。
2. なぜ巨大・レガシーなコードでAIは急に下手になるのか（3つの壁）
AIが大きなコードで弱る理由は、わりとシンプルです。3つの壁にまとめられます。
① 窓の壁（コンテキスト長は有限）
AIが一度に読める文章の量（これを「コンテキストウィンドウ＝AIの作業机の広さ」と思ってください）には上限があります。机がどれだけ広くなっても、数千ファイルのコードを丸ごと広げることはできません。
② 構造の壁（依存関係は行間に書いてない）
仮に全部読めたとしても、ファイルAの関数がファイルBを呼び、その設定はファイルCにある…みたいな「つながり」は、1ファイルを眺めただけでは見えません。アーキテクチャ（全体の構造）は、コードの“行間”に隠れているんです。
③ 暗黙知の壁（コードに書いてない事情）
「この処理がここに置いてあるのは、3年前の障害対応の名残」みたいな、コードのどこにも書いていない知識。チームの頭の中にだけある“暗黙知（tribal knowledge）”ですね。AIはここに一番アクセスしづらい。
比喩で言うと、こういうことかなと。
初めての街に来た観光客に、分厚い電話帳を渡しても目的地には着けない。
必要なのは、路線図と「観光案内所はここ」という1枚の地図。
AIに「電話帳（＝全コード）」を渡しても迷うのは、当たり前なんですよね。渡すべきは地図のほうです。
3. 発想を変える：「全部渡す」から「地図を渡す」へ
ここ数年、AIまわりは「コンテキストウィンドウを大きくする競争」で盛り上がってきました。机をどんどん広くする方向ですね。でも、現場の手触りとしては、そこじゃない気がしてて。
実際、2026年のAIコーディングの流れは、はっきり変わってきています。「より大きい窓に丸投げ」から、「永続的で構造化された“コードベースの地図（repo map）”をAIに参照させる」 方向へ。いくつか実在のツールを挙げておきます（どれも考え方の参考になります）。
- Aider（オープンソースのCLIエージェント）の repo map：Tree-sitter（＝コードを文法的に解析して、関数やクラスといった“部品”を取り出す道具）でリポジトリ全体からシンボル（クラス名・関数名・呼び出しの形）を抜き出し、今のタスクに関係しそうな順に並べて、コンパクトにAIへ渡します。全ファイルを読み込まずに、多ファイル編集に強い。
- Repomix：リポジトリ全体を、AIが読みやすい構造化テキスト（1枚にまとめたパック）に変換するツール。
- ctags / Tree-sitter：「どこに何が定義されているか」のシンボル索引を作る、昔からある定番。
共通しているのは、「コードをそのまま渡す」のではなく、「コードから“索引と地図”を作って渡す」 という発想です。大手の開発組織でも、巨大なパイプラインの暗黙知を、AIにナビゲーション用のガイドとして書き起こさせる、といった取り組みが出てきています。
僕はこれを、ひとことで「整地（せいち）」と呼んでいます。
更地のジャングルにAIを放り込むんじゃなくて、先に道を通してから歩かせる。地ならしをするのは、ちょっと地味な作業です。でも、ここをやるかやらないかで、AIの働きは別物になる気がします。
4. コードベースの地図は「3層」でできている
では、地図ってどう作るのか。難しそうに聞こえますが、ざっくり3層に分けると、一気に作りやすくなります。
- 俯瞰マップ：上空から見た全体図（ディレクトリ構成・規模・入口）
- ルータ表：「○○したいなら、ここを見ろ」という道案内表
- フロー追跡：ある1機能を、入口から出口まで一本でたどった図
順番に、コードとプロンプトで作っていきましょう。
4-1. 俯瞰マップ —— まず「上空写真」を1枚作る
いきなりコードを読ませる前に、機械的に集められる事実を1枚にまとめます。ここはAIじゃなくて、ふつうのコマンドの仕事です。
#!/usr/bin/env bash
# repo-overview.sh — コードベースの「上空写真」を1枚に出力する
set -euo pipefail
OUT="repo-overview.txt"
{
echo "# Directory tree (depth 2, ディレクトリのみ)"
# gitが追跡しているパスから、上位2階層のディレクトリだけ抽出
git ls-files | awk -F/ '{print $1"/"$2}' | sort -u | head -80
echo
echo "# 言語別の規模（行数）"
# clocが無ければ: git ls-files | xargs wc -l などでも代用可
cloc --quiet . 2>/dev/null || echo "(cloc未インストール: スキップ)"
echo
echo "# エントリポイント候補（main / index / app / server 等）"
git ls-files | grep -Ei '(^|/)(main|index|app|server|cli)\.[a-z]+$' | head -40
echo
echo "# 主要シンボル索引（ctags: 関数・クラスの定義位置）"
# -R 再帰, --languages で対象言語を絞ると軽い
ctags -R --fields=+n -f - . 2>/dev/null | awk '{print $1"\t"$2}' | head -120
} > "$OUT"
echo "wrote $OUT"
これで「ディレクトリ構成・言語別の規模・入口らしきファイル・主要な関数の定義位置」が1枚のテキストになります。全コードじゃなくて、この“目次”だけをAIに渡すのがポイントです。
そのうえで、最初の要約をお願いします。
▼ プロンプト例①：俯瞰要約をつくる
あなたは、このコードベースに今日初めて参加したシニアエンジニアです。
添付の repo-overview.txt（ディレクトリ構成・規模・エントリポイント・シンボル索引）だけを根拠に、
初見の開発者向けに以下を日本語でまとめてください。推測した箇所は「推測」と明記すること。
1. このプロジェクトは何をするものか（1〜2行の仮説）
2. アーキテクチャの俯瞰（層・主要モジュール・想定される責務）
3. 処理の入口（エントリポイント）はどれか、根拠とともに
4. 「最初に読むべきファイル」トップ5と、その理由
5. この情報だけでは分からない点（追加で見たいファイル名）
ポイントは最後の「分からない点を聞く」ところ。AIに「知らないことを知らないと言わせる」ことで、次に何を渡せばいいかが見えてきます。
4-2. ルータ表 —— 「○○したいなら、ここ」を作る
俯瞰の次は、道案内表です。英語圏では "where to look for X"（Xを探すならどこ）と呼ばれたりします。これが地図のいちばん実用的な部分かなと。
▼ プロンプト例②：ルータ表をMarkdownで作らせる
先ほどの俯瞰と、私が追加で貼るファイル（ルーティング定義・ディレクトリ一覧）を根拠に、
「やりたいこと → 最初に見るべき場所」の対応表を、Markdownの表で作ってください。
- 列は: やりたいこと / 関連ディレクトリ・ファイル / 入口の関数やルート / 補足
- 行は、実務でよくある作業を最低10個（例: 認証を直す, APIを1本追加する,
決済フローを追う, DBスキーマを変える, ログを足す, テストを追加する 等）
- 各行に、根拠が無い場合は「未確認」と書くこと。事実と推測を混ぜないこと。
出てきた表は、その場限りにせずファイルに保存して資産化します。たとえば docs/atlas/repo-map.md のような場所に置いて、Gitにコミットしておく。こうすると、次に来た人も、次に動くAIも、同じ地図を再利用できます。AIが毎回ゼロから探索しなくて済むので、地味にトークンも時間も節約できるんですよね。
4-3. フロー追跡 —— 1本の機能を、入口から出口まで
最後は、ある1機能を、入口から出口まで一本でたどる地図です。バグ修正や機能追加の前に、これが一番効きます。
ただ、ここでAIに「決済フロー全部読んで」と丸投げすると、また迷子になります。なので、たどる材料を機械的に集めてから渡します。
#!/usr/bin/env bash
# trace-symbol.sh — ある関数の「呼び出し元・呼び出し先」候補を集める
# 使い方: ./trace-symbol.sh createCheckout
set -euo pipefail
SYM="${1:?関数名やシンボル名を引数で渡してください}"
echo "## 定義箇所（definition 候補）"
git grep -nE "(function|def|fn|const|class)\s+${SYM}\b" || true
echo
echo "## 使用箇所（呼び出し元の候補）"
git grep -nE "\b${SYM}\s*\(" || true
echo
echo "## 近接する重要キーワード（同じファイル内のimport/route定義）"
git grep -lE "\b${SYM}\b" | while read -r f; do
echo "### $f"
grep -nE "^(import|from|require|route|app\.(get|post|put|delete))" "$f" | head -10 || true
done
この出力（＝「この関数はどこで定義され、どこから呼ばれ、どんなimportと一緒にいるか」）をAIに渡して、こうお願いします。
▼ プロンプト例③：機能フローを一本でたどらせる
添付は、関数 createCheckout に関する grep 結果（定義・呼び出し元・近接import）です。
この材料だけを根拠に、「ユーザーが決済ボタンを押してから、決済が確定するまで」の
処理フローを、呼び出し順に並べてください。
- 各ステップに「ファイル:行 / 関数名 / 役割（1行）」を付ける
- 材料に存在しないステップは創作しないこと。欠けている箇所は「ここは材料に無いので要確認」と書く
- 最後に、このバグ（決済が二重に走る）を調べるなら最初に疑うべき箇所トップ3を挙げる
ここまで来ると、AIは「全体のどこを、どの順でいじればいいか」を、根拠つきで答えられるようになります。最初の grep 地獄とは、もう別世界ですよね。
5. ただし——AIが描いた地図を、そのまま信じてはいけない
ここ、いちばん大事なところです。声を大にして言いたい。
AIが作った地図を、検収せずに信じない。
理由は3つあります。
- ハルシネーション（もっともらしい嘘）：AIは、存在しない依存関係や、それっぽいけど実在しない関数を、平気で“それらしく”書くことがあります。地図が間違っていると、その上の作業が全部ズレます。
- 地図の陳腐化：一度作った地図は、コードが変われば古くなります。半年前の路線図で歩いたら、廃線になった駅に着く、みたいなことが起きる。
- 機密の流出：社内コードを安易に外部サービスへ貼るのは、規約・セキュリティの観点でアウトな場合があります。何を外に出していいかは、人間が必ず線を引く。
地図を検収するための、もう1本プロンプトを足しておくと安全です。
▼ プロンプト例④（検収用）：根拠を全部出させる
あなたが作成したルータ表・フロー図について、各行・各ステップに
「根拠となるファイル:行」を付け直してください。
- 実際の grep 結果や貼られたコードに根拠がある項目だけ「確認済」とする
- 根拠が無い、または推測で書いた項目は、すべて「未確認」と明記する
- 「未確認」の項目について、確認するために私が次に調べるべきコマンド（grep等）を提案する
そして人間がやることは、シンプルです。ルータ表の上位5項目だけ、実物のコードと突き合わせる。 全部を検証する必要はありません。よく使う入口だけ正しければ、地図は十分に「使える」ものになります。
6. 人間がやること、AIに任せること
ここで、役割をはっきり線引きしておきましょう。AI時代のエンジニアは「実装する人」から「コードベースの地図を設計し、その正しさを保証する人」へ、少しずつ重心が移っている気がします。
| フェーズ | 人間が握る（設計・判断） | AIに任せる（生成・抽出） |
|---|---|---|
| 何を地図化するか | 対象範囲・優先順位を決める | 候補の洗い出しを手伝う |
| 俯瞰マップ | 機械抽出のコマンド設計／結果の取捨選択 | 索引からの要約・初見向け説明 |
| ルータ表 | 「実務でよくある作業」リストの妥当性判断 | 表のドラフト作成 |
| フロー追跡 | どの機能を追うか決める／材料の準備 | 呼び出し順の組み立て |
| 検収 | 上位項目を実物と突き合わせる | 根拠（ファイル:行）の提示 |
| 暗黙知 | 「なぜこうなっているか」を言語化する | 言語化を質問で引き出す |
| 機密境界 | 何を外に出すか決める | （触らせない） |
そして、いちばん効くのは、作った地図を“その場限り”にしないことです。docs/atlas/repo-map.md や CONTRIBUTING.md にコミットして、チームの資産にする。次に入る新人も、次に動くAIエージェントも、同じ地図の上を歩けます。暗黙知が、少しずつ「書かれた知識」に変わっていく。これって、けっこう尊い変化だと思うんですよね。
7. まとめ：最初の一歩は、たった5分でいい
長く書いてきましたが、明日いちばん最初にやることは、これだけでいいと思います。
READMEとディレクトリ一覧だけをAIに渡して、「やりたいこと → どこを見ればいいか」の表を作らせる。
たったこれだけ。git ls-files | head -100 の結果と README を貼って、プロンプト例②を投げるだけです。5分で、あなたのコードベースに小さな地図が1枚できます。
そこから、規模に応じて俯瞰マップ・フロー追跡・検収を足していけばいい。最初から完璧な地図はいりません。1枚の道案内表から始めればいいんです。
最後に、もう一度だけ。
AIが大きなコードで見当外れになるのは、AIのせいじゃない。地図を渡してないだけ。
そして、その地図を設計して、正しさを保証するのは——まだしばらく、僕たち人間の仕事なんですよね。
今日も、いい整地を。