「コードを書いて」と頼むと、ファイルを読み、コマンドを実行し、結果を確かめてから返答する。その一連の作業は、どんな部品でできているのでしょうか。
この連載は、Codex のソースコードを手掛かりに、Coding Agent の仕組みを30の小さな章で読み解くシリーズです。 一つの図で流れをつかみ、要点を読んでから、実際のコードへ進みます。
この連載で目指すこと
目標は、リポジトリの全ファイルを覚えることではありません。ユーザーの入力がどこへ渡り、モデルが選んだ操作がどう実行され、結果がどのように次の判断へつながるかを、自分の言葉で説明できるようになることです。
読み終えたとき、次の三つを手元に残すことを目指します。
- 部品の地図：画面、Core、Model、Tools、履歴が、それぞれ何を担うか。
- 処理を追う方法：観察した動作やエラーから検索し、型と関数の境界をたどる方法。
- 正しさを確かめる視点：成功と失敗、状態の寿命、テスト、API の約束を分けて考える習慣。
これは責務を整理した概念図です。矢印をたどりながら、各章で状態・権限・失敗時の回復を少しずつ書き加えていきます。
こんな人に向いています
Coding Agent を日常的に使いながら、その中で何が起きているのか知りたい人。大きなオープンソースのコードを読む入口が欲しい人。自分のアプリでモデルとツールをつなぐ設計を考えたい人に向けています。
図と説明は最初から順に読めます。手を動かす章では、ターミナル、Git、基本的なプログラミングの知識が役立ちます。Rust の細かな文法を最初から網羅する必要はありませんが、型・enum・関数の入出力を、その都度確認しながら進めましょう。
目的に合わせて読み始める
| 知りたいこと | 読む章 | まず確かめること |
|---|---|---|
| 手元で動かし、全体の入口を知りたい | Day 01–05 | 実行ファイル、主要な責務、入力と状態の単位 |
| モデルが何度も判断できる理由を知りたい | Day 06–09 | Agent Loop、通信、履歴、Compaction |
| ツールの実行と制約を知りたい | Day 10–16 | 実行経路、Approval、Sandbox、MCP、画面との接続 |
| 小さな変更やバグ調査を試したい | Day 17–23 | テスト、alias の演習、Issue、Git の履歴 |
| 状態や API の境界を深く読みたい | Day 24–30 | 修正の前提、到達可能性、失敗注入、契約と互換性 |
初めてなら Day 01 → Day 02 → Day 03 の順がおすすめです。「動かす → 地図を作る → 一つの入力を追う」という土台ができます。概要だけ先につかみたい場合は Day 30 の全体地図 を眺め、気になった部品の章へ戻っても構いません。
一章の読み方
- 図でつかむ：箱の役割と矢印の方向を確認します。
- 3つのポイントで理解する：何を入力し、何を変え、何を返すのかを読みます。
- ソースで確かめる：検索語を使い、定義と呼び出し元を一つずつ開きます。
- 30秒で復習する：要点を見ずに説明し、分からない境界だけ読み直します。
読む速さより、一つの動作と一つのコードの対応が分かることを大切にしてください。各章の「小さく試す」は学習用の提案です。書かれているコマンドや操作は、実行する目的と作業場所を理解してから使います。
全30章の目次
Day 01–05｜動かす。地図をつくる。
- Day 01｜ソースから動かすと、コードに意味が生まれる
- Day 02｜Coding Agent を、6つの役割に分けてみる
- Day 03｜一つの入力を、モデルとツールの往復まで追う
- Day 04｜Op と EventMsg — お願いと報告を分ける
- Day 05｜Session・Task・Turn — 状態の寿命を見分ける
Day 06–09｜判断と記憶をつなぐ。
- Day 06｜Agent Loop — 結果を受け取り、もう一度判断する
- Day 07｜Model Client — 応答を少しずつ受け取る仕組み
- Day 08｜Context と History — 保存した情報と渡す情報
- Day 09｜Compaction — 長い会話を、続けられる形にする
Day 10–16｜道具と画面をつなぐ。
- Day 10｜Tools — 名前付きの要求を、実装へ届ける
- Day 11｜exec — コマンドが OS のプロセスになるまで
- Day 12｜apply_patch — 変更の意図を、ファイルへの差分にする
- Day 13｜Approval — 方針と、一回の判断を分ける
- Day 14｜Sandbox — 許可を、実際の制約に変える
- Day 15｜MCP — 外部の道具を、同じ作業の輪につなぐ
- Day 16｜TUI と App Server — 画面と処理の間にある橋
Day 17–23｜試す。調べる。確かめる。
- Day 17｜テスト — 変更した一行を、振る舞いで確かめる
- Day 18｜小さな改造 — alias は既存の処理へつなぐ
- Day 19｜コントリビューション — 差分を、伝わる問題分析へ
- Day 20｜Issue から読む — 成功時と失敗時の差を探す
- Day 21｜git の履歴 — 一行の変更から、設計の理由をたどる
- Day 22｜git bisect — 変化した地点を、半分ずつ絞る
- Day 23｜回帰テスト — 関数名より、利用者に届く結果を守る