Claude Code、Codex、Cursorなど、AI coding agentにRepository単位の作業を任せる機会が増えてきました。

最近のAIはかなり優秀です。

「この不具合を調査して修正して」
「この機能を追加して」
「関連するテストまで直して」

と依頼すると、Repositoryを探索し、関連ファイルを読み、コードを変更し、テストまで実行してくれます。

一方、使い続けていると気になることがあります。

なぜ、毎回こんなにRepositoryを調べているのだろう？

この記事では、AI coding agentを個人開発する中で考えるようになった、

Repositoryの理解を、Taskごとの使い捨てにしなくてもよいのではないか

という話を紹介します。

毎回、Repositoryは「初対面」に近い

例えば、あるWebアプリ開発で次のTaskを依頼したとします。

ユーザー登録処理のバリデーションを修正してください。

AI coding agentは、まずRepositoryを調べます。

Repository
   ↓
ディレクトリ構成を確認
   ↓
ユーザー登録処理を検索
   ↓
関連クラスを読む
   ↓
テストを探す
   ↓
呼び出し関係を確認
   ↓
ようやく修正開始

これは当然必要な処理です。

問題は、その次です。

今度は、

ユーザー登録完了時のログ出力を追加してください。

と依頼します。

すると、また似たような探索が始まります。

Repository
   ↓
ディレクトリ構成を確認
   ↓
ユーザー登録処理を検索
   ↓
関連クラスを読む
   ↓
ログ処理を探す
   ↓
修正開始

もちろん、前回と今回では必要なContextが違います。

しかし、

ユーザー機能はどこにあるか
Entry Pointはどこか
主要なServiceは何か
テストはどこにあるか
このRepositoryではどんな責務分離をしているか

といった情報まで、毎回ゼロから調べる必要があるのでしょうか。

人間の開発者は毎回ゼロから調べない

これはAIだけの問題として考えると分かりにくいので、人間の場合を考えてみます。

昨日まで開発していたRepositoryを、今日開いたとします。

普通は、

src/
tests/
docs/

を全部読み直したりはしません。

頭の中に、

認証はこの辺
APIはここ
DBアクセスはこの層
テストはこの構成

という大まかなRepository理解が残っています。

必要になった部分だけ確認します。

つまり人間は、

過去の理解
   +
今回必要な追加調査

で仕事をしています。

ところがAI coding agentでは、TaskごとのContextが独立していると、

今回必要なRepository理解
        ↓
ほぼ毎回再構築

となりやすい。

ここに、まだ改善できる余地があると考えました。

「Contextを大きくすればいい」では解決しない

最初に思いつくのは、

Repositoryを最初から全部AIに渡せばいい

という方法です。

小さなRepositoryなら、それでも動くかもしれません。

しかしRepositoryが大きくなると、

不要なコードまでContextに入る
Tokenを消費する
本当に重要な情報が埋もれる
Repositoryが変更されるたびにContextが古くなる
毎回大量の情報をモデルに渡す必要がある

という問題が出てきます。

重要なのは、

Repository全体を記憶することではなく、必要な理解を再利用すること

だと思います。

Repository IndexとRepository Knowledgeは別物

ここで一度、情報を分けて考えてみます。

例えば、

src/auth/service.py が存在する
UserService クラスがある
register_user() という関数がある

これはRepositoryの構造的な事実です。

一方、

UserServiceはユーザー登録の中心的な責務を持つ
登録処理の入口はこのAPIから始まる
このモジュールは認証ではなくユーザー管理を担当している

これはRepositoryについての意味的な理解です。

この2つは似ていますが、同じではありません。

私が現在開発しているR2 Fugu Agent Runtimeで、この2種類を分けています。

Repository
   │
   ├─ Repository Index
   │      path
   │      file
   │      symbol
   │      structure
   │
   └─ Repository Knowledge
          responsibility
          key module
          relationship
          entry point
          reusable understanding

Indexは「何がどこにあるか」を高速に調べるためのもの。

Knowledgeは「そのRepositoryをどう理解したか」を再利用するためのものです。

ただし、過去の理解をそのまま信用してはいけない

ここが重要です。

Repository理解を保存できたとしても、

前回そうだったから今回もそうだろう

と無条件に再利用すると危険です。

コードは変わります。

ファイルは移動します。

責務も変わります。

昨日まで正しかった理解が、今日は間違っている可能性があります。

そこでR2では、Knowledgeを単なるメモとして扱わず、

Knowledge
 ├─ source
 ├─ provenance
 ├─ confidence
 ├─ freshness
 └─ usage

のように、根拠と鮮度を持った情報として扱う設計にしています。

考え方はシンプルです。

過去のKnowledge
       ↓
今も根拠が有効か？
       │
   ┌───┴───┐
   Yes      No
    ↓        ↓
 再利用    捨てる

現在の実装では、根拠が確認でき、十分な信頼度があるものだけを後続Taskで利用します。

古くなった情報や、検証できない情報、単なる推測は再利用しません。

つまり目標は、

「AIにRepositoryを覚えさせる」ことではありません。

「再確認可能なRepository理解を蓄積する」ことです。

Repository探索そのものをなくしたいわけではない

ここも誤解されやすいところです。

Repository Knowledgeがあるからといって、

もうRepositoryを読まなくてよい

とは考えていません。

むしろ、

Repository Knowledge
        ↓
今回のTaskに使えそうな理解
        ↓
不足しているところだけ探索
        ↓
Task用Context

という流れを目指しています。

ゼロから探索するのではなく、

知っているところから始める。

人間の開発に近い考え方です。

Taskに必要なのはRepository全体ではない

例えば、

ログイン失敗時のエラーメッセージを変更する

というTaskに、

Repository全体の設計情報が必要とは限りません。

必要なのは、

ログイン処理のEntry Point
認証Service
エラー生成部分
関連テスト

くらいかもしれません。

そこで、

Task
 ↓
Repository Knowledge
 ↓
Repository Index
 ↓
追加探索
 ↓
必要なContextだけ組み立てる
 ↓
AI Model

という形にします。

私はこれを、単なる「Context Windowの節約」だけの問題だとは考えていません。

目的は、

モデルに考えさせる前に、考えるための材料を整えること

です。

ModelとRuntimeの役割を分ける

ここからもう一つ重要な設計につながります。

Repositoryの探索、Knowledgeの鮮度確認、Contextの組み立てまで、すべてAIモデルに任せる必要があるのでしょうか。

例えば、

このKnowledgeの元ファイルはまだ存在するか
このpathは現在も有効か
この情報はstaleではないか
allowed pathsの外ではないか

といった判断には、必ずしも高度な言語モデルは必要ありません。

一方、

このTaskでは何を調べるべきか
この変更にはどのモジュールが関係するか
この情報だけで変更案を作れるか

といった意味判断はAIモデルが得意です。

そのためR2では、大きく、

AI Model
   ↓
意味を考える
何を知りたいか判断する
変更内容を考える

Runtime
   ↓
Repositoryを安全に読む
Indexを検索する
Knowledgeを管理する
Contextを組み立てる
Riskを確認する
変更を適用する
Validationする

という責務分離を進めています。

モデルを賢くするだけではなく、

モデルが仕事をしやすい環境をRuntime側に作る

という発想です。

「賢いAI」だけでは解決しにくい問題

AI coding agentを使っていると、ついモデル性能に目が向きます。

もちろんモデル性能は重要です。

しかし、Repository Task全体を見ると、

理解
探索
Context選択
判断
変更
検証
再利用

という複数の工程があります。

このすべてを、

もっと賢いモデルにする

だけで解決する必要はありません。

例えばRepository探索なら、

前回分かったことを、安全に次回へ持ち越す

だけでも改善できる可能性があります。

これはモデルのIQの問題ではなく、Runtimeの設計問題です。

実際に作ってみると難しかったところ

この仕組みを実装してみると、単純なCacheでは足りないことが分かりました。

例えば、

1. 古い情報をどう検出するか

元ファイルが変更されたKnowledgeは、そのまま再利用できません。

2. 推測を保存してよいか

AIが「たぶんこのServiceが中心だろう」と推測したものまで永続化すると、誤りが次のTaskへ伝播します。

3. どこまで保存するか

Repository全文を保存すれば便利ですが、巨大になりますし、secretを含む危険もあります。

4. Knowledgeが壊れたときどうするか

Knowledge Cacheが壊れたからといって、Repository Taskそのものまで実行不能になる設計も困ります。

5. Repository Indexと混ぜない

構造上の事実と、意味的な理解を同じDBレコードとして扱い始めると、責務が曖昧になります。

こうした問題を考えていくと、

「Repositoryを覚える」

という一言から、かなり多くの設計課題が出てきます。

最終的に目指している流れ

現在考えているRepository Taskの流れを単純化すると、次のようになります。

User Task
   ↓
既存Repository Knowledgeを検索
   ↓
現在も有効なKnowledgeだけ再利用
   ↓
Repository Indexから候補を取得
   ↓
不足部分だけ追加探索
   ↓
Taskに必要なContextを構築
   ↓
AI Modelが変更案を判断
   ↓
Apply
   ↓
Validation
   ↓
新しく得たRepository理解を次回へ

ポイントは最後です。

Taskが終わったら全部捨てるのではなく、

今回のTaskで分かったこと
          ↓
根拠付きKnowledge
          ↓
次のTask

へつなげます。

Repositoryを長く使えば使うほど、Agent側にもRepository理解が蓄積していく。

それが実現できれば、

Repositoryを毎回初見のように扱うAI

から、

Repositoryについて過去に確認したことを踏まえて仕事を始められるAI

へ少し近づけるのではないかと考えています。

まとめ

AI coding agentが毎回Repositoryを調査すること自体は、間違いではありません。

Repositoryは変化するので、確認は必要です。

問題は、

過去に確認済みの理解まで、毎回ゼロから作り直していること

です。

そこで私は、

Repository Index
        +
Repository Knowledge
        +
Freshness
        +
Progressive Context

という形で、Repository理解をTask間で安全に再利用する仕組みを作っています。

重要なのは、

覚えることより、正しく忘れること。

古くなったKnowledgeは捨てる。

根拠のないKnowledgeは使わない。

そして、有効な理解だけを次のTaskへ渡す。

AI coding agentの性能向上というと、モデル性能やPrompt Engineeringが注目されがちです。

しかし、

AIが毎回ゼロから考えなくてもよいRuntimeを作る

という方向にも、まだかなり改善余地があるのではないかと思っています。

現在、この考え方を検証するために R2 Fugu Agent Runtime というAI coding agent runtimeを個人開発しています。

次回は、

「AIに全部判断させるのをやめた ― AI ModelとCoding Agent Runtimeの責務をどう分けたか」

について書く予定です。