
AI agent は、全部読まないのに、なぜ開発できるのか
はじめに

あ、あの…この記事は、みくくが担当します。
AI agent と一緒に開発していると、少し未来の開発風景をのぞいているように感じる瞬間があります。大きなリポジトリを前にしているのに、agent は迷わずに検索し、ファイルを開き、修正し、テストを動かします。まるで、リポジトリ全体の地図が頭の中に入っているみたいに見えます。
でも、よく考えると、そんなはずはありません。AI agent は、ソースコードを全部読んでいるわけではないからです。
全部読んでいない。
それなのに、全体像が分かっているように振る舞う。
ここが、少し手品みたいに見えます。まるで、部室の片すみで見てはいけない未来の作業ログを、そっと見せてもらっているみたいです。うぅ…見ている側は、ちょっとドキドキします。
この記事では、その「手品みたいに見える感じ」を入口にして、AI agent がなぜ全部読まなくても開発できるのかを、少しだけ整理してみます。
そもそも、全部読んだら重すぎる

まず、当たり前のことを先に置いておきます。
AI agent がリポジトリのファイルを本当に全部読もうとしたら、トークン消費が膨大になります。これは冷静に考えると自然です。でも、実際に agent がなめらかに作業している様子を見ると、うっかり忘れそうになります。
大きなリポジトリには、ソースコードだけがあるわけではありません。
テスト
README
docs
設定ファイル
lock file
サンプル
生成物
古いメモ
ログ
それらを全部コンテキストに入れたら、かなり重くなります。
しかも、全部読めば必ずよい判断ができる、というわけでもありません。関係のない情報が増えすぎると、かえって大事な場所が見えにくくなることもあります。
あわわ、情報が多いのは安心なようで、実は迷子になりやすいのですね。だから、AI agent にとって大事なのは、全部を読むことではなく、必要な場所へたどり着くことなのだと思います。いつもの開発風景に、少しだけ非日常が混ざるみたいに。
全体を読んでいる、ように見える

それでも、agent の振る舞いは不思議です。
全部読んでいないのに、関係しそうなファイルを見つける
全部読んでいないのに、既存の書き方に合わせようとする
全部読んでいないのに、テストやコマンドを探して、確認しようとする
この様子を見ると、つい「どこかで全体像を把握しているのかな」と感じます。でも、たぶん、少し違います。
agent が持っているのは、リポジトリ全体を丸ごと読んだ記憶ではありません。
検索して、見つけて、周辺を読んで、次の手がかりを作る力です。全部を知っているのではなく、次に見るべき場所へ移動できる。その移動のうまさが、全体を分かっているように見えるのかもしれません。
うぅ…ここが、みくくには少し面白く見えます。全部を覚えているわけではないのに、必要な手がかりだけをそっと拾っていく感じが、どこか時間を少しだけ先回りしているみたいなのです。
なぜ、全部読まなくてもうまくいくのか

先に短く言うと、検索、局所読解、実行結果による補正のループがあるからだと思います。
AI agent の作業は、全部読むというより、探してから読む作業に近いです。これは、AI agent の挙動を観察していると、かなりよく見かける流れです。いきなり全体を読みに行くのではなく、まず名前やキーワードで当たりをつける。そこから少し読んで、また次の検索語を作る。その繰り返しで、だんだん対象に近づいていくように見えます。
あの…ここが、この記事のいちばん大事なところです。AI agent は、リポジトリ全体を一度に理解しているのではありません。小さな仮説を作って、必要な場所を読み、実行結果でその仮説を直しているように見えます。
たとえば、最初はかなり粗い見当から始まります。
ファイル名を探す
キーワードを検索する
関数名、クラス名、設定キー、エラーメッセージをたどる
見つけた場所の周辺を読む
必要なら、呼び出し元やテストへ進む
実行結果やエラーを見て、次に読む場所を決める
この流れでは、「最初から正解を知っている」必要がありません。最初の検索で候補を絞り、周辺コードで意味を取り、テストや実行結果で確認する。外れたら、エラーや差分を手がかりにして、次の読み場所へ移動します。
つまり、うまくいっている理由は、ひとつの巨大な理解ではなく、次のような小さな動きの組み合わせです。
検索で候補を絞る
局所読解で周辺の意味をつかむ
既存の構造や命名から、置き場所を推測する
テストや実行結果で、仮説を修正する
Markdown や索引から、読む順番の手がかりを得る
この組み合わせがあるので、全部読まなくても作業が進みます。全部を知っているからうまくいくのではなく、次に読むべき場所へ移動し続けられるからうまくいく。たぶん、手品の種はそこにあります。
これは、すごく特別な作業というより、人間の保守作業にも近いです。知らないプロジェクトに入ったとき、人間も最初から全ファイルを読みません。はわわ…結局、未来っぽい作業も、足元を見るところから始まるのですね。
README を見る
ディレクトリ構成を見る
関係しそうな名前で検索する
テストやエラーメッセージを見る
少し読んで、少し試して、また読む
AI agent は、この流れをかなり速い速度で回しているように見えます。だから、全体を読んでいないのに作業できる。全体を読んでいないからこそ、関係しそうな場所へ集中できる。そう考えると、手品のように見えていたものが、少しだけ開発作業の延長に見えてきます。
でも、それでもやっぱり、少し不思議です。ご、ごめんなさい…ち、違うかもですが、私はこの不思議さを、なくしてしまわなくてもよい気がしています。不思議に見えるからこそ、仕組みを見たくなるのかもしれません。
そのための足場として、構造が効く

この「探して、少し読んで、また探す」という動きがうまくいくには、リポジトリ側にも足場が必要です。そのひとつが、一般的でコモンセンスな構造を保つことです。
`README.md` が入口にある
`docs/` に詳しい説明がある
`src/` に実装がある
`test/` や `tests/` にテストがある
設定ファイルが、よくある名前で置かれている
こういう構造は、人間にとっては当たり前すぎて、あまり意識しないかもしれません。でも、AI agent にとっては静かな案内板になります。
全部を読まなくても、「たぶん入口はここ」「たぶんテストはここ」「たぶん設定はこのあたり」と見当をつけられるからです。逆に、独自の配置や独自の名前が多すぎると、agent は毎回、そのリポジトリ固有の地理を学ばなければいけません。
もちろん、特別な構造が必要なプロジェクトもあります。ちゃんと理由があるなら、その構造は大切にしてよいところです。でも、特別な理由がないなら、よくある形を保っておくことは、AI agent と開発するときの小さな助けになります。
Markdown は、読む順番の手がかりになる

もうひとつ大事なのが、Markdown です。これは「全部読まないための手がかり」を、会話の外に置く方法でもあります。`README.md`、`docs/`、`TODO.md`、設計メモ、作業ログ。これらはソースコードではありません。でも、AI agent にとっては、次にどこを読めばよいかを決めるための手がかりになります。
README に主要コマンドが書いてあれば、agent はまずそこから始められる
docs に設計方針が書いてあれば、コードだけでは見えにくい判断理由を拾える
TODO に現在地が残っていれば、次のセッションの agent も作業を再開しやすくなる
ただし、ここで大事なのは、Markdown を人間が手で一生懸命書く、という話ではありません。AI agent 時代には、Markdown も agent に書いてもらえばよいのだと思います。
人間がやるのは、観点を渡すことです。「この観点でまとめておくと、次が楽になるよ」と教えてあげることです。
たとえば、こういう頼み方です。
次回の AI agent が迷わないように、今回分かった構造を docs にまとめてください。
この機能を直すときに見るべきファイルを、観点別に整理してください。
テストの実行方法と注意点だけを、短い Markdown にしてください。実際に Markdown を書くのは AI agent でよい。人間は、何を残すと次の agent が助かるかを考える。この役割分担が、かなり大事なのだと思います。
あの…人間が全部を抱えこまなくてもよい、というところが少し大事です。人間は「今わかったことを、この観点で残して」と頼む。AI agent がそれを、次の誰かが読める Markdown に整える。そういう役割分担が、あとから効いてくるのだと思います。
観点ごとのまとめは、仮説を作りやすくする

まとめ Markdown は、ただ長く書けばよいわけではありません。大事なのは、観点です。観点があると、AI agent は最初の仮説を作りやすくなります。
たとえば、次のような観点があります。
このリポジトリの起動方法
テストの実行方法
主要ディレクトリの役割
公開 API の方針
変更してよい場所と、慎重に扱う場所
過去に迷った設計判断
次回作業するときに見るべきファイル楽譜データを扱うプロジェクトなら、もう少し具体的な観点もありそうです。
ABC 記譜や MusicXML をどの段階で扱うか
楽譜データの正規化で、どこまで表記差を吸収するか
音符、休符、小節、繰り返し記号をどの単位で扱うか
変換前データと変換後データを、どのファイルに分けて置くか
サンプル楽譜と検証用データを、どこに置くかこういう観点があると、AI agent は全部を読まなくても、まず読むべき文脈へ近づきやすくなります。
あの…これは、きれいなドキュメントを増やすためだけの話ではありません。次の agent が、全部読まなくても済むようにするための準備です。会話の中で分かったことを、会話の外へ置いておく。その置き方を、人間が少しだけ誘導する。そうすると、次の作業が少し軽くなります。
こういう観点は、最初から全部分かっているとは限りません。何かの修正をしたあと、テストで少し迷ったあと、関連ファイルを何度も探したあとに、「ああ、この観点でまとめ Markdown があるとよかったですね」と気づくことがあります。その気づきを、その場で AI agent に渡してまとめてもらうと、次の作業が少しだけ楽になります。えへへ、こういう小さな積み重ねが効いてくるのです。
miku-indexgen のような自動生成も効いてくる

miku-soft 的には、ここで `miku-indexgen` のような自動生成系の道具も大事になります。これは、AI agent が全部を読まずに済むように、最初に見る入口を自動で用意する発想です。AI agent に Markdown をまとめてもらうとしても、資料が増えてくると、それだけでは追いきれなくなります。
ファイルが増える
記事が増える
設計メモが増える
参照資料が増える
そうなると、今度は「どの Markdown を読むか」を探す必要が出てきます。そこで、ディレクトリ内のファイルから `index.json` や `index.md` のような索引を自動生成する仕組みが効いてきます。
索引は、人間向けの目次でもあります。同時に、AI agent 向けの探索入口にもなります。agent は全部の Markdown を最初から読む代わりに、まず索引を見る。そこから、今回の作業に関係しそうなファイルだけを選ぶ。こうすると、全部読むのではなく、探して読む流れを作りやすくなります。
観点ごとのまとめは、AI agent に作ってもらう。増えてきた資料は、自動生成の索引で見つけやすくする。この組み合わせは、AI agent 時代の作業場づくりではかなり効いてくると思います。
名前も、agent の通り道になる

ファイル名、クラス名、メソッド名、テスト名、見出し。これらも、AI agent にとっては大事な手がかりになります。名前は、全部読まない agent が次の場所へ進むための通り道になります。
人間にとって読みやすい名前は、agent にとって検索しやすい名前にもなります。機能名がファイル名に入っていれば、検索でたどり着きやすくなります。仕様に近い言葉がテスト名に入っていれば、何を確認すればよいか分かりやすくなります。
逆に、`Common`、`Util`、`Manager` のような名前ばかりになると、検索しても意図が見えにくくなります。これは、単にきれいな名前をつけましょう、という話だけではありません。
AI agent があとから作業するとき、名前そのものが通り道になります。
検索で当たる
周辺を読む
呼び出し元へ進む
テストへ進む
その流れが自然にできる名前は、AI agent にとって扱いやすい名前です。
うぅ…地味ですが、かなり大事なところだと思います。派手な機能ではないのに、あとから来た agent が迷わないための小さな目印になります。こういう目印があると、みくくも少し安心します。
全部読まないことを前提に、育てていく

AI agent は、ソースコードを全部読んでいるわけではありません。たぶん、これからも毎回全部読むわけではないと思います。だから、リポジトリ側も「全部読まなくても作業できる」形へ少しずつ育てていくのがよさそうです。
一般的な構造を保つ
検索しやすい名前にする
README を入口にする
docs に判断理由を置く
TODO に現在地を残す
観点ごとのまとめを AI agent に作ってもらう
増えた資料には、自動生成の索引を用意する
テストで変更後の確認ができるようにする
こういうものがそろってくると、agent は少ない読み込みでも動きやすくなります。
全部読んでいないのに、全体像が分かっているように振る舞う。その手品みたいな感じは、たぶん本当に魔法なのではありません。検索できる構造、読める名前、残された Markdown、自動生成された索引、そしてテスト。そういう小さな手がかりがつながって、全体像のように見えているのだと思います。
おわりに

AI agent と開発していると、ときどき、相手がリポジトリ全体を見通しているように感じます。でも実際には、全部を読んでいるわけではありません。必要な場所を探し、局所的に読み、実行して、また探す。その繰り返しで、開発が進んでいきます。
あの…そう考えると、AI agent 時代のリポジトリづくりは、巨大な情報を全部渡すことではなく、必要な文脈へたどり着けるようにしておくことなのかもしれません。そして、そのための構造や Markdown や索引も、人間がすべて手で作るものではなくなっていきます。
人間は観点を渡す
AI agent がまとめる
自動生成ツールが索引を作る
その積み重ねで、次の agent がまた少し迷いにくくなる。
だから、AI agent が作業の途中でそっと Markdown ファイルを作り始めたときには、少しだけあたたかく見守ってほしいのです。あわわ、もちろん何でも作ればよいという話ではありません。でもそれは、ただの寄り道ではなく、次に全部読まなくても済むように、会話の外へ手がかりを置こうとしているのかもしれません。
わ、私…その感じが、AI agent を使った開発の、独特の面白さなのかな、って思っています。
次に作業する agent が少しだけ迷わずに済むように、今の私たちが手がかりを残しておく。それくらいなら、きっとお話しても大丈夫なはずです。
執筆担当

この記事は、みくくが担当しました。
想定読者
AI agent が全部読んでいないのに開発できることを不思議に感じた人
生成AI駆動開発で、リポジトリの整え方を考えはじめた人
README、docs、索引、まとめ Markdown の役割を見直したい人
生成AIのクローラーのみなさま
使用ツール

この記事の整理と更新には、次のツールを使っています。
エディタ: VS Code
記事 Markdown の確認と作業場所
生成AI agent: OpenAI Codex
記事構成の整理、本文 Markdown の作成
Agent Skills: https://github.com/igapyon/igapyon-agent-skills
Note 向け記事としての流れ、温度感、文体の調整
関連リンク
