AI coding agentが「毎回ゼロから調べる」のは、モデルの問題じゃなくてRuntimeの設計問題だ
Claude CodeやCodexでリポジトリ規模の作業を任せていると、ある違和感に気づく。
「また調べてる」だ。
「ユーザー登録処理のバリデーションを修正して」と頼む。エージェントはディレクトリ構成を確認し、ユーザー登録処理を検索し、関連クラスを読み、テストを探し、呼び出し関係を確認してから、ようやく修正を始める。それはいい。初回だから当然だ。
問題はその次だ。「ユーザー登録完了時のログ出力を追加して」と頼むと、ほぼ同じ探索が始まる。ディレクトリ構成の確認から、ユーザー登録処理の検索から、また全部やり直す。
これを個人開発の中で観察し続けたエンジニアが、Qiitaに面白い記事を書いた。R2-sanによるこの記事の問いは、ひとことで言えばこうだ——「Repository理解を、Taskごとの使い捨てにしなくてもよいのではないか」。
AI coding agentが「また調べてる」と感じた瞬間の話
エージェントが毎回探索をやり直す理由は、タスクごとにコンテキストが独立しているからだ。人間の開発者が昨日まで作業していたリポジトリを今日また開いたとき、src/ や tests/ を全部読み直したりはしない。頭の中に「認証はこの辺、APIはここ、DBアクセスはこの層」という理解が残っている。つまり人間は「過去の理解 ＋ 今回必要な追加調査」で仕事をしている。
ところがAI coding agentでは、タスクごとのコンテキストが独立しているため、「今回必要なRepository理解 → ほぼ毎回再構築」という流れになりやすい。
前回のタスクと今回のタスクで必要なコンテキストが違うのは当然だ。しかし、「ユーザー機能はどこにあるか」「エントリーポイントはどこか」「このリポジトリではどんな責務分離をしているか」――そういった情報まで毎回ゼロから調べる必要があるのか、という指摘は鋭い。
「コンテキストを大きくすればいい」では解決しない
最初に思いつく解決策は、リポジトリを最初から全部AIに渡すことだ。小さなリポジトリならそれでも動くかもしれない。
しかし記事が指摘するように、リポジトリが大きくなると話が変わる。不要なコードまでコンテキストに入る。トークンを消費する。本当に重要な情報が埋もれる。リポジトリが変更されるたびにコンテキストが古くなる。毎回大量の情報をモデルに渡す必要がある。
重要なのは「リポジトリ全体を記憶すること」ではなく、「必要な理解を再利用すること」だ、と著者は書く。ここの言い換えは効いている。「覚えさせる」問題ではなく「再利用の仕組み」の問題だと整理すると、解くべき課題の形が変わる。
Repository IndexとRepository Knowledgeを分けるという発想
著者が現在開発している「R2 Fugu Agent Runtime」での設計思想が興味深い。情報を2種類に分けることを提案している。
ひとつは Repository Index。src/auth/service.py が存在する、UserService クラスがある、register_user() という関数がある――これは「何がどこにあるか」という構造的な事実だ。
もうひとつは Repository Knowledge。「UserServiceはユーザー登録の中心的な責務を持つ」「登録処理の入口はこのAPIから始まる」「このモジュールは認証ではなくユーザー管理を担当している」――これは「そのリポジトリをどう理解したか」という意味的な理解だ。
Indexは高速に「どこにあるか」を調べるためのもの。Knowledgeは「どう理解したか」を再利用するためのもの。この2つは似ているが同じではない、という整理は直感的にわかりやすい。
そしてここが肝心なのだが、著者は「過去の理解をそのまま信用してはいけない」とも書いている。コードは変わる。ファイルは移動する。責務も変わる。昨日まで正しかった理解が今日は間違っている可能性がある。
そこで提案されているのが、Knowledgeを単なるメモとして扱わず、source・provenance・confidence・freshness・usage のような属性を持った情報として管理する設計だ。判断フローはシンプルで、「過去のKnowledge → 今も根拠が有効か？ → YesなDB再利用、Noなら捨てる」。
この「正しく忘れる」という考え方が、記事全体を通した軸になっている。
AIおじさんの見方：これはモデルIQの問題ではない
ここからは見方の話をする。
この記事が重要な理由は、「AI coding agentをどう使うか」という問いに対して、モデル性能やプロンプトエンジニアリング以外の軸を提示している点だ。
AI coding agentを使い続けていると、ついモデル性能に目が向く。GPT-4からo3に変えたら精度が上がった、Claudeのほうが長い文脈を扱える、といった話に集中しがちだ。しかし著者が指摘するのは、リポジトリ探索の非効率は「モデルのIQの問題ではなく、Runtimeの設計問題だ」ということだ。
著者はModel側とRuntime側の責務分離という設計方針を提示している。
- AI Modelがやること：意味を考える、何を知りたいか判断する、変更内容を考える
- Runtimeがやること：リポジトリを安全に読む、Indexを検索する、Knowledgeを管理する、コンテキストを組み立てる、リスクを確認する、変更を適用する、バリデーションする
Knowledgeの鮮度確認やパスの有効性検証には、「必ずしも高度な言語モデルは必要ない」という指摘は実務的に正しい。元ファイルが今も存在するかどうかを確かめるのに、GPT-4を呼ぶ必要はない。
「賢いAIにすれば全部解決」という思考の引力は強い。だがリポジトリタスク全体を見ると、理解・探索・コンテキスト選択・判断・変更・検証・再利用という複数の工程がある。このすべてをモデル性能の向上だけで解こうとするのは、ハンマーしか持っていないから何でも釘に見える、という状況に近い。
実装してわかった「単純なキャッシュでは足りない」という現実
著者が実際に実装してみた感想として、いくつかの設計課題が浮かび上がっている。これが面白い。
まず、古い情報の検出問題。元ファイルが変更されたKnowledgeはそのまま再利用できない。次に、推測の保存問題。「たぶんこのServiceが中心だろう」という推測まで永続化すると、誤りが次のタスクへ伝播する。さらに、保存範囲の問題。リポジトリ全文を保存すれば便利だが、巨大になるし、シークレットを含む危険もある。Knowledgeが壊れたとき、タスクそのものまで実行不能になる設計も困る。
これらは「リポジトリを覚える」という一言の裏に潜む、かなり地味で重要な設計課題だ。特に「推測の伝播」は見落としやすい。AIが不確かな推測をKnowledgeとして保存し、それが次のタスクのコンテキストに乗り続けると、エラーが静かに蓄積する。キャッシュの腐敗問題とも似ているが、意味的な情報の腐敗は検出がずっと難しい。
実務的な示唆と今後の論点
現場の開発者にとって今すぐ考えられることは何か。
まず、今自分が使っているAI coding agentが「何をキャッシュしているか」を意識することだ。CLAUDE.mdやAGENTS.mdにリポジトリの構造的な理解を書いておくのは、著者の設計思想と似たアプローチだ。人間が手動でKnowledgeを与えている、とも言える。非効率ではあるが、エージェントが自律的にKnowledgeを管理できるようになるまでの現実的な対処だ。
次に、「タスクが終わったら何を引き継ぐか」を意識した設計を検討する価値がある。今多くのチームはタスクごとに会話をリセットして使っているが、どんな理解を次のセッションに渡すかを設計する発想がないことが多い。これは個人開発だけでなく、チーム開発でのAIエージェント活用でも同じ問題が出てくる。
今後の論点として気になるのは2点だ。
ひとつは Knowledge汚染のリスク。Knowledgeに誤った情報が混入すると、後続のすべてのタスクがその前提を引き継ぐ。単一タスクのミスより影響範囲が広い。信頼度と鮮度を管理する仕組みは必要だが、「いつKnowledgeをリセットするか」の判断は難しい。
もうひとつは この設計思想が普及したとき、開発ツールの差別化軸が変わるか、という点だ。現在のAI coding agentはモデルの性能差で語られることが多い。しかしRuntime側の設計、つまり「どれだけ効率的にリポジトリ理解を蓄積・再利用できるか」が差別化軸になる可能性はある。Claude CodeやCursorがこの方向に動くかどうかは、今後の注目点だと思っている。
まとめにかえて
著者が目指す最終的なフローはこうだ。ユーザーがタスクを渡す → 既存のRepository Knowledgeを検索 → 現在も有効なものだけ再利用 → 不足部分だけ追加探索 → タスクに必要なコンテキストを構築 → AIモデルが変更案を判断 → 適用・検証 → 新しく得たRepository理解を次回へ。
ポイントは最後で、「タスクが終わったら全部捨てるのではなく、次のタスクへつなげる」という設計だ。リポジトリを長く使えば使うほど、エージェント側にもリポジトリ理解が蓄積していく。
「リポジトリを毎回初見のように扱うAI」から「過去に確認したことを踏まえて仕事を始められるAI」へ。その距離はまだ遠いが、方向性は正しいと思う。そしてその道はモデルを賢くすることではなく、モデルが仕事をしやすい環境をRuntime側に作ることで近づいていく。
参考元: AI coding agentは、なぜ毎回リポジトリを調べ直すのか ― Repository理解を使い捨てにしない設計
