Repo as an Agent

十分にうまく設計されたrepoは、それ自体が継続的に自己改善するAgentになりうる。

ここでいうrepoは、単なるコードの置き場所ではない。Agentも、一度だけ呼び出されるモデルのことではない。Repoには目標、知識、ツール、フィードバック、制約が保存される。モデルはそこに入り、現在の状態を読み取り、行動し、その結果を書き戻す。次回、別のモデルに替わったとしても、前回の続きから作業を進められる。

厳密にいえば、静止したGitリポジトリが自ら行動するわけではない。起動するには、やはりモデル、Harness、実行環境が必要になる。HarnessとはAgentを載せるシステムであり、モデルにContext、ツール、実行能力を提供する。ただし、それらを入れ替えても、repoに同じ仕事の進め方と蓄積された能力が残るのなら、Agentのもっとも安定した部分は、すでにモデルではなくrepoにあるのかもしれない。

モデルがAgentのすべてではない

私たちはAgentの能力をモデルに帰属させがちだ。モデルが賢くなればAgentも強くなり、回答がよくなければ、より大きなモデルに替えて試せばいいと考える。

しかし、この見方は、モデルが仕事を始めるたびに向き合う環境を見落としている。同じモデルでも、入るリポジトリが違えば、その働きはまったく異なりうる。

あるリポジトリにはソースコードしかなく、アーキテクチャの説明もなければ、起動方法もわからない。テストは長いあいだ失敗したままで、重要な決定はチャットの履歴に残され、エラーが起きても読めるログがない。Agentは入るたびに一から推測しなければならない。局所的な変更はできても、一つの仕事を安定して最後までやり遂げるのは難しい。

別のリポジトリでは、プロダクトの目標と技術上の決定が検索可能な文書に記録され、AGENTS.mdがAgentに出発点を伝え、スクリプトが共通の操作手順を提供している。テスト、型チェック、CIから明確なフィードバックを得られ、実際のページを起動して変更結果を直接観察することもできる。モデルは同じでも、完遂できる仕事は明らかに増える。

OpenAIによるAgent-first開発実験のまとめも、この点を示している。初期の進捗が遅かったのは、Codexの能力不足だけでなく、環境が十分に定義されていなかったためだとわかった。その後、チームの主な仕事は、足場、ツール、フィードバックループを設計し、リポジトリ内の知識を唯一の信頼できる情報源にすることへ移った。テスト、検証、レビュー、フィードバックへの対応、障害からの復旧が徐々にrepoへ組み込まれたことで、Agentは一つのpromptから出発し、問題の再現、変更、検証、レビューへの提出、CIの修正までを自律的に完了できるようになった。

Factoryはこの違いをAgent Readinessと呼んでいる。つまり、自律的な開発に対してrepoがどれだけ準備できているかという尺度だ。評価するのはモデルの強さではなく、信頼できるビルド、テスト、文書、開発環境、可観測性、セキュリティガバナンスがリポジトリに備わっているかどうかである。そのうえで、Agentがどこまで独力で仕事を進められるかを五段階の成熟度で表す。この枠組みによって、もともと曖昧だった判断を点検できるようになる。Agentの働きが悪いとき、問題は必ずしもモデルにあるとは限らない。repoが、十分に速いフィードバック、明確な指示、実際に操作できる環境をまだ提供していない可能性もある。

したがってrepoは、Agentが処理する対象にとどまらない。そのAgentが何者で、何ができるのかも定義している。

RepoにはすでにAgentの主要な部分がある

この視点に立つと、成熟したrepoにある一般的なファイルが、別の意味を帯びて見えてくる。

AGENTS.md、アーキテクチャ文書、意思決定の記録はLong-term Memoryである。そのプロジェクト固有の事実と仕事の進め方を保存する。
ソースコード、CLI、スクリプト、Skillsは行動能力である。何をすべきか記述するだけでなく、直接実行できる。
テスト、型チェック、lint、CI、ログ、ページの確認は知覚とフィードバックである。直前の行動が期待した結果を生んだかどうかをAgentに伝える。
Issue、計画、タスクファイルには、まだ完了していない目標が残される。
Gitは起きたことを記録し、比較、追跡、巻き戻しを可能にする。
人によるreviewは、機械的なフィードバックでは決められない部分を担う。目標に取り組む価値があるか、トレードオフは妥当か、結果を本当に受け入れられるかを判断する。

これらが組み合わさることで、複数回のモデル呼び出しをまたいで行動する主体が形作られる。モデルがその場の推論を担い、repoが連続性を担う。

だからこそ、self-improvementは、必ずしもモデルが自らの重みを訓練することを意味しない。Self-Improving Coding Agentの研究では、より厳密な定義が採用されている。Agentが自らの実装を変更し、benchmarkを使って、より性能の高い版を選ぶというものだ。しかし日々の開発では、モデルの外側で起きる自己改善のほうが一般的で、実用的でもある。モデルの重みは変わらなくても、Agentが働く環境は変わる。その結果、次回は以前に犯した間違いを一つ減らし、検証済みの能力を一つ増やして実行できる。

改善はフィードバックを書き戻したあとに起きる

一度タスクを完了しただけでは、自己改善とはいえない。

Agentがbugを修正すれば、もちろんコードはよくなる。しかし次回も同じ種類のbugを生み出すのなら、改善されたのはプロダクトであって、Agentではない。本当の境界線は、今回のフィードバックが将来の行動を変えたかどうかにある。

一つの失敗は、いくつかの層に書き戻せる。

Agentが実行コマンドを知らなかっただけなら、簡潔なリポジトリの説明を加えればいい。同じ種類のタスクで毎回同じ手順を踏むなら、Skillやスクリプトとしてまとめられる。絶対に破ってはならない制約なら、注意書きをもう一行増やすより、テスト、lint、型のルールとしてコード化するほうがよい場合が多い。自然言語はAgentに望ましいやり方を伝え、自動チェックは誤ったやり方が気づかれないまま通るのを防ぐ。

つまり、完全な改善ループは次のようになる。

右上が折れた紙の頭を持つ人物が欠けた歯車をrepoの機械へ戻し、隣の完全な歯車が次回の実行での改善を表している — 失敗はrepoへ戻されて初めて、次の行動の一部になる

Eric Maはこの変化をoperational self-improvementと呼んでいる。モデルのアップグレードを待つのではなく、フィードバックをAGENTS.mdと再利用可能なSkillsに残す。その測り方も単純だ。同じ訂正を人が繰り返し伝える必要があるか。昨日終えた仕事によって、今日、同種の仕事を終えるコストが下がったか。

このブログのrepoも、すでに少しそのようなAgentに似ている

この記事そのものが一つの例である。

私が「repo as an agentをテーマにdraftを書いて」と伝えた時点で、repo内の規約がすでにdraftの意味を定義している。まず調査を行って中国語の原稿を整え、英語版と日本語版は先に作らず、commitも公開もしない。記事システムへ書き込んだあとは、対応するページを起動して私がコメントできるようにする。

記事をどこに置くのか、どの段階で翻訳してよいのか、どのチェックを実行すべきかを、Agentに毎回説明し直す必要はない。AGENTS.mdが境界を保存し、writing Skillが再利用可能な執筆方法を保存する。Content Collectionが記事の構造を決め、Markdown smoke checkとビルドコマンドがフォーマット上の問題を見つけ、Portalが実際のページと人からのコメントを再びworkflowへつなぐ。

さらに重要なのは、このrepoが、フィードバックを長期的な経験に変える方法まで定めていることだ。一つの記事への修正は、その記事だけに適用される。同じ理由が、レビュー済みの複数の記事と異なる場面で繰り返し現れたときに限り、AgentはそれをSkillへ書き込むことを提案する。それでも、人の確認は必要になる。

これは小さな学習の仕組みである。モデルを訓練してはいないが、短期的なフィードバックと長期的なルールを区別し、何を忘れ、何を次回の実行へ持ち越すべきかを決めている。記事が増えるにつれて、本当に安定した方法が少しずつ残り、その後の制作はゼロから始めなくてよくなる。

多く覚えることが、多く改善することではない

repoをAgentにするとは、AGENTS.mdへ文章を際限なく追加することではない。

リポジトリレベルのContextファイルを扱った2026年のある研究では、その実験設定において、AGENTS.mdを追加してもcoding taskの成功率は全般的には上がらず、平均推論コストはむしろ20%以上増えた。標準的ではないプロジェクト固有の指示にはAgentが従った一方、一般的なrepo overviewは役に立たなかった。そのため研究者は、Contextは多いほどよいと決めつけず、性能を向上させるとされるリポジトリの説明は、どれも評価すべきだと提案している。

これは、自己改善が自己汚染に転じることもあると教えてくれる。

誤った要約は次回の実行へ引き継がれる。古くなった文書は、もう存在しない構造へAgentを導く。偶発的な好みが永続的な制約に変わり、増え続ける指示が、本来のタスクに必要なContextを圧迫する。Repoはよいパターンだけでなく、悪いパターンも増幅する。

だから、自己改善できるrepoには、忘却、修正、昇格の仕組みも必要になる。一時的な経験はまず現在のタスクにとどめ、繰り返し現れてから文書にする。機械的に判断できるルールは、さらにテストやツールへ落とし込む。無効になった説明は修正するか、削除しなければならない。AGENTS.mdは百科事典ではなく、地図として使うほうがよい。

RepoはAgentが継続的に作り変えられる自分自身である

あるrepoがこのようなAgentになり始めているかどうかは、いくつかの具体的な問いから判断できる。

新しいモデルインスタンスに替わっても、このプロジェクトの目標、境界、現在の状態を復元できるか。
ツールを直接実行し、もっともらしいコードを生成するだけでなく、実際の結果を観察できるか。
一度の失敗から実行可能な修正を残し、同じ間違いがその後は起きにくくなるか。
人の判断をシステムへ取り込みながら、一度限りの意見が将来の仕事を永続的に汚染するのを避けられるか。
Repoは、自身を制約する文書、テスト、Skills、スクリプトを点検し、整理し、変更できるか。

答えが少しずつ「できる」に変わっていくなら、モデルは一時的に呼び込まれる推論能力に近くなる。時間を越えて存在し続けるのは、repoの中で変化し続けるコード、記憶、ツール、フィードバックループである。

これまで私たちは、repoをソフトウェアのソースコードとして見てきた。これからは、Agentのソースコードにもなるかもしれない。

実行のたびに、Agentはプロダクトを変更する。うまく設計されていれば、次回の自分自身も変更している。