AIは「一気書き」をしていない——コーディングエージェントの内側を解剖する
Claude CodeやCursorに大きなタスクを投げると、何十ものファイルが読み書きされ、テストが走り、エラーが直り、いつの間にか数千〜数万行のコードが出来上がっている。
「すごい」という感動の前に、冷静に一つの疑問が浮かぶはずだ。LLMのAPIには1回の生成で返せる出力上限（max_tokens）がある。数千〜数万トークン程度、Pythonコードに換算すれば数百〜千数百行が限界だ。なぜその壁を超えて、破綻なく巨大なシステムが構築できるのか。
答えは「超高性能なAIが一気に書いている」ではない。むしろ逆で、泥臭く地道なループの積み重ねだ。
AIは「天才的な一気書き」をしていない
誤解の核心は、「1回の出力量」と「作業全体の累積量」を混同していることにある。
元記事ではこの構造を明快に図示している。
コンテキストウィンドウ（1回で読める量：数十万〜100万 tokens）
出力上限（1回で書ける量：数千〜数万 tokens）
作業全体の成果物（ループを回すことで理論上の上限なし）
人間が「1行のミスもなく最初から完璧な1万行を書く」ことをしないのと同じだ。エージェントも「少し読む → 最小限の差分を書く → コマンドを実行して確かめる」というループを何十回、何百回と繰り返すことで、結果として巨大な成果物を積み上げている。
この「ループを成立させる設計」こそが本質で、そこに4つの具体的な工夫が組み込まれている。
エージェントを支える4つの工夫
① 差分編集（str_replace）で出力量を削る
数百行のファイルを少し修正するたびにファイル全体を再生成していたら、出力トークンはあっという間に尽きる。実用的なエージェントがcreate_fileではなく文字列置換ツール（str_replace）やunified diffパッチを好んで使う理由はここにある。「変更前の数行」と「変更後の数行」だけを出力すれば、1ターンの出力はわずか数十トークンで済む。
実際の動作トレースを見ると、既存ファイルに1関数を追加するタスクでのモデルの出力トークンは各ターン50〜350トークン程度に抑えられている。全体で見ると小さい。
② grep・findで入力（コンテキスト）を節約する
コンテキストウィンドウが100万トークンあっても、リポジトリ全体を丸ごと読み込めばすぐにパンクする。エージェントはgrep、find、ls、行数指定のread_fileを駆使して「いま編集したい周辺のコードだけ」をピンポイントでロードする。広く読まず、必要な箇所だけ読む。
③ ファイルシステムを「外部記憶」として使う
モデル自体はAPIを叩くたびにリセットされる、ステートレスな存在だ。長時間の作業では後述するコンパクション（履歴圧縮）が走り、過去の詳細なやり取りは忘れられる。そのため、エージェントはTODO.mdやPROGRESS.md、アーキテクチャ設計書といった実ファイルをディスク上に作り、それを自分の外部記憶として読み書きする。
「AIが記憶している」のではなく、「AIがファイルに書いて、都度読み直している」のが実態だ。
④ 検証ループ（自律修復）が規模を支える最大の要因
コードを書いた直後にコンパイラ、リンタ、テストコマンド（pytestやnpm test）を実行し、そのエラー出力を受け取って自ら修正する。「一発で正しく書く必要がない」からこそ、大規模な作業が破綻せずに前進する。
1発で完璧に書けなくていい、という設計が、むしろスケールを可能にしているのは逆説的で面白い。
モデルとハーネスの役割分担——誰が何を決めているのか
「AIが全部自分で考えて動いている」という理解は半分しか正しくない。実態はモデル（頭脳）とハーネス（手足・作業環境）の分業だ。
元記事の整理を借りると：
| 領域 | モデル（LLM） | ハーネス（実行基盤） |
|---|---|---|
| 判断 | 次に何をするか決める | 判断しない。モデルの要求通り動く |
| 実行 | 一切実行しない（文字列を出力するだけ） | 実際にファイルを書き換え、OSコマンドを叩く |
| 記憶 | 生まれつき記憶を持たない | 過去の会話ログを保持し、毎ターン頭から渡し直す |
| 制約 | 学習で培われた「行儀の良さ」 | 危険なコマンドのブロック、ターン数上限 |
モデルが止まるタイミングも決まっている。外部情報が必要になった時（例：read_fileのツール呼び出しJSONを出力した時点でハーネスがstop_reason: tool_useを検知）か、全タスク完了と判断した時（stop_reason: end_turn）の2パターンだ。
コンテキストの蓄積問題も重要だ。実際のトレースを見ると、4ターンのタスクでも入力トークンはTurn 1の約2,000から Turn 4の約7,000へと雪だるま式に増えていく。50ターンを超えると入力が10万〜15万トークンに達し、ハーネスによるコンパクション（要約圧縮）が自動発動する。
コンパクションが走ると、過去の詳細なコード本文は文脈から消去される。だからこそエージェントは次の作業の前に、再びread_fileでディスクから最新状態を読み直す必要がある。記憶の欠落を、ファイルの再読み込みで補完する設計だ。
強化学習が「分割して進める」癖を焼き付けた
「差分で書く」「テストで確認する」「小分けにする」——こうした振る舞いは、プロンプトで細かく指示しているからだけではない。モデルの訓練、特に環境フィードバックを用いた強化学習（RL）によって骨の髄まで染み付いている。
訓練は三段階だ。
- 事前学習：世界中のコード・Gitコミットログ・PRレビューを学習。「少しずつ修正する文化」を獲得。
- SFT（教師あり微調整）：「課題 → ツール呼び出し → 結果確認 → 回答」の軌跡を学習。ツール呼び出しの文法を身につける。
- 環境での強化学習（核心）：サンドボックス内で実際にエージェントループを何万回も自律実行し、テスト通過やタスク完了を「報酬」として最適化。
強化学習の中で何が起きているかは、元記事の試行パターンが端的に示している。
- 試行A：1,500行のファイルを1発で生成しようとする → 出力上限でJSONが途中で壊れ、テスト全滅 → 0点
- 試行B：コードを書き、テストを実行せずに「完了」と宣言 → 実は構文エラー → 0点
- 試行C：ファイルを読む → 骨組みを作る → 1関数ずつ差分編集 → テストでエラー発見 → 修正 → 全テスト通過 → +1.0点
何十万回という試行錯誤を経て、「一度に全部書こうとすると自滅する」「小さく刻んでテストしながら進む」という行動パターンに強烈なプラス報酬が与えられ続けた。その結果として、こまめな分割・差分編集・テスト実行がモデルの「自然な選択」として現れるようになった。
ここからは見方の話：この構造が示すこと
技術的な解説として読むと「なるほど」で終わるが、少し引いて見ると、この話はもう少し大きなことを示している。
「AIが全部考えている」という幻想の解体
エージェントの品質は、モデルの知能だけでは決まらない。元記事が明言しているように、「いくらモデルの知能が高くても、ハーネスのツール設計やコンテキスト管理が拙ければ、エージェントは自律的に作業を継続できない」。
Claude CodeとCursorで同じモデルを使ったとして、出てくる結果が異なるのはここに理由がある。ハーネスの設計が、エージェントとしての実力を大きく左右する。製品評価をするとき、「モデルが何か」だけでなく「ハーネスがどう設計されているか」を見る習慣をつける価値がある。
コンパクションは「記憶喪失」リスクを内包している
長時間のエージェント作業で静かに進むのが、コンパクションによる文脈の欠落だ。過去の詳細なやり取りが圧縮・消去されたあとのエージェントは、ある意味で記憶を失った状態から再出発する。
これが実務で問題になるのは、「なぜこのコードがこう書かれているのか」という文脈がコンパクション後に失われるケースだ。エージェントがTODO.mdやPROGRESS.mdを残してくれれば補完できるが、それもエージェントの設計・プロンプト次第だ。長時間作業を任せる場合、「外部記憶に何を残させるか」を明示的に設計しておく必要がある。
強化学習が生んだ「癖」は、万能ではない
検証ループでエラーを自律修復する仕組みは強力だが、「テストが通ること」を報酬としている以上、テストが間違っていたり、テストカバレッジが不足していたりする場合は無力だ。エージェントはテストを通過させることに最適化されているのであって、「ビジネス要件を正しく満たすこと」に最適化されているわけではない。
検証ループを信頼するためには、ループの中で走る「テスト自体の品質」が問われる。ここは人間が設計し続けるべき領域だ。
実務的な示唆——開発者・プロダクト担当が今考えるべきこと
エージェントに長時間タスクを任せるなら、外部記憶の設計を明示せよ
TODO.mdに何を書かせるか、PROGRESS.mdに何を記録させるかを事前に決めておく。コンパクション後に再開する際の「引き継ぎ書」として機能させる意識が必要だ。
差分編集と検証ループを前提に、タスクを渡す粒度を設計せよ
エージェントは小さく刻んで進むのが得意だが、「どう刻むか」の大枠は人間が設計したほうが効率がいい。「1,500行のモジュールを新規作成して」より「まず骨組みを作って、次にAPIメソッドを1つずつ追加して、各追加後にテストを走らせて」という粒度の指示のほうが、エージェントの強みを引き出せる。
次の論点：エラー修正ループの暴走と停止条件
検証ループは強力だが、エラーが解消されない状況で何十ターンもループし続けるリスクがある。ハーネスのターン数上限設計や、「同じエラーが続いた場合に人間に差し戻す」停止条件の設計は、実運用でのエージェント活用が本格化するにつれて必ず問題になる論点だ。「いつ止めるか」を誰が、何をトリガーに決めるのか、まだ業界として答えが出ていない。
まとめ
コーディングエージェントが数万行のコードを書けるのは、超高性能なAIが一気に全部書いているからではない。差分編集・コンテキスト節約・外部記憶・検証ループという4つの工夫を組み合わせ、何十回・何百回のループを積み重ねた累積の結果だ。そしてその「ループをうまく回す振る舞い」は、強化学習によってモデルに焼き付けられている。
モデルとハーネスを分けて理解する視点が、エージェント活用の精度を上げる。「AIがやってくれる」ではなく、「モデルが判断し、ハーネスが実行し、ファイルが記憶する」という三層の役割分担として見ると、どこが信頼でき、どこを人間が設計すべきかが明確になる。
