エージェントループまるごと入門
ある朝のターミナル。あなたはたった一行こう書いて、コーヒーを取りに席を立つ。
$ claude "tests/ が全部緑になるまで直しておいて"戻ってくると、画面ではこんなことが起きている。
● Bash(pnpm test) ⎿ 3 failing
● Read(src/parser.ts)
● Read(tests/parser.test.ts)
● Edit(src/parser.ts)
● Bash(pnpm test) ⎿ 1 failing
● Edit(src/parser.ts)
● Bash(pnpm test) ⎿ all green
直しました。空配列の境界条件を 2 箇所修正しています。人間が打ったコマンドは最初の 1 行だけ。 あとはぜんぶ、機械が 自分で考え、自分でファイルを読み、自分で書き換え、自分でテストを流し、自分で「直った」と判断して 止まった。
ChatGPT は 答える だけだった。 このターミナルの中の何かは、動いている。
その「何か」の正体を、本書は最後まで追いかける。
この本でやること
2024 年から 2026 年にかけて、「コーディングエージェント」という言葉が日常になった。 Claude Code、Cursor、Codex、Devin、Aider、OpenHands ── ロゴも UI も会社も違うが、不思議なことに やっていることはどれも、よく似ている。
なのに体感はずいぶん違う。
- 同じ Claude 系モデルを使っているのに、Devin と Claude Code は「動き方の癖」が違う
- Cursor の Agent モードと Claude Code は、文脈の切れ方や粘り方が違う
- 同じプロダクトでもバージョンが上がると、別物のように振る舞いが変わる
裏には何が住んでいるのか。 本書の立場はひとつだ。
コーディングエージェントの賢さの大半は、LLM ではなく、その外側で回っている “ループ” が握っている。
どんな道具を渡すか。ループをどこで止めるか。どこまで覚えさせ、どこを忘れさせるか。誰に承認を求めるか。 これらは LLM の中身ではなく、LLM の “外側” を設計する仕事 だ。
同じ LLM を使っても、外側の設計判断が違えば、まるで別人格 のエージェントになる。 本書はその「外側の設計学」を一冊にまとめる。
本書のスコープ ── プロダクトに依らない “ループ”
世の中には「Claude Code の本」「Cursor の本」「Devin の本」と、プロダクトを軸にした解説がすでにある。 本書はそれらと 意図的にスコープを切る。
- 下の層（LLM そのもの） は掘らない。トークン予測の仕組みや Transformer の中身は、自然言語処理の専門書に任せる
- 上の層（プロダクト固有のコマンド・UI） も主役にしない。Claude Code の
/compactや Cursor の.cursorrulesは 例として 引くが、本書のゴールではない - 真ん中の 「ループ」 ── これが本書の主役だ
ループ層の概念は どのプロダクトにも共通 していて、しかも 来年のエージェントにも残る ものが多い。骨格を一度腑に落としてしまえば、新しいプロダクトが出るたびに「で、要は何が違うんだっけ」を自分で読み解けるようになる。
章マップ
本書は 序章 + 全10章 + 終章 + 付録 で構成する。10 章を 4 つの部に束ねた。
各章で扱う中身を一行で並べておく。
| 章 | たどり着く理解 |
|---|---|
| 第1章 | LLM は “続きを書く機械” ── そこから “動く” までの距離 |
| 第2章 | LLM・道具・ハーネスの 三角形 が、ループの最小単位 |
| 第3章 | think → act → observe ── ReAct の系譜と現代の三拍子 |
| 第4章 | ループはいつ止まるのか ── 自然停止・上限・人間介入の三本柱 |
| 第5章 | テキスト機械が 関数を呼ぶ からくり ── JSON Schema による契約 |
| 第6章 | 良い道具とは何か ── description・権限・並列呼び出し |
| 第7章 | 有限の “机の広さ” ── コンテキストウィンドウと文脈量の物理 |
| 第8章 | CLAUDE.md / AGENTS.md / .cursorrules の正体 ── 圧縮と外部記憶 |
| 第9章 | Plan mode・TodoWrite・サブエージェント ── 骨組みと分岐 |
| 第10章 | 三大病（早すぎる終了・無限ループ・幻のツール呼び）と HITL 設計 |
基本は 順読推奨。階段で上る構成にしてある。第5章以降は、興味の強い章から参照する形でも読めるよう、章ごとに導入を厚めに書いてある。
三つの「合言葉」
本書を読みながら、頭の片隅に置いておくと迷子にならない合言葉が三つある。
① 「LLM は変わっていない。変わったのは外側だ」
ChatGPT も Claude Code も中身の LLM は同じ系列。 動くようになったのは、外側にループと道具を巻きつけた瞬間 から。 「最新モデルがすごい」というニュースを見るたびに、LLM が伸びたのか、それともハーネスが伸びたのか を区別する癖をつけるとよい。
② 「賢さは、設計判断の総量で決まる」
道具をどう作るか、停止をどう決めるか、文脈をどう持たせるか。 派手な機能ではなく、地味な設計判断の積み重ね がエージェントの体感を決める。 本書は各章で「ここはどう設計してもよかったが、こう設計された」を繰り返し示す。
③ 「最後は LLM が判断する。だから危うい」
ループの停止も、道具の選択も、計画の良し悪しも、最終的には LLM が判断する。 そして LLM の判断は、人間ほど安定しない。 だからこそハーネス側で 構造的に囲い込む 仕事が要る ── その正面からの議論は第10章で扱う。
こんな人向け
- Claude Code / Cursor / Codex を業務で使っているが、中で何が起きているか気持ち悪い 人
- 「LLM は同じはずなのに、なんでこのプロダクトはこう動くんだ?」が気になる人
- 自分で軽いエージェントを書いてみたいが、最小構造が掴めていない人
- チームに導入したいが、停止条件・権限・サブエージェントの設計判断 をどう説明するか悩んでいる人
逆に「Transformer の中身」「最新 LLM の評価ベンチマーク」を求めている人向けではない。 本書は LLM の “外側” を設計する人 のための、なるべく腑に落ちる教科書として書いた。
前提知識
- ターミナルでコマンドを打った経験
- Git のだいたいの感覚（branch、PR、commit）
- ChatGPT などの LLM を一度は触ったことがある
数式は出てこない。コード例は Python の擬似コード相当 で読める範囲に抑える。
本書のスタンス
私はこの本を「使い方マニュアル」ではなく 「設計の地図帳」 として書いた。 来年の Claude Code や Cursor の挙動は、コマンド名から変わっているかもしれない。 だが 「エージェント = LLM + 道具 + ループ」「think → act → observe」「コンテキストウィンドウ」「サブエージェント」「停止条件」 といった骨格は、もっと長く生き残る。
骨格を腑に落とした読者は、来年出る新しいエージェントを、自分の頭で読めるようになる。 それがこの本の願いだ。
それでは始めよう
最初の章で問うのは、最も素朴な質問 ── 続きを書くだけの機械が、なぜファイルを書き換えたりテストを流したりできるのか だ。
ここから 10 章をかけて、その「なぜか」をひとつずつ解いていく。