この記事は「AIエージェントを工程に入れる」シリーズの第0回です。
Claude Code、Codex、Cursor、Gemini CLI のような coding agent を、単なるコード生成ツールではなく、開発工程に組み込むための考え方を整理します。
この記事の想定読者は、Claude Code、Codex、Cursor、Gemini CLI などを使って、既存リポジトリの調査、実装、テスト、PRレビュー、障害調査を進めているエンジニアです。
一般的な「AI活用術」ではなく、開発工程の話をします。プロンプトの小技よりも、仕様、変更範囲、テスト、review、eval、sandbox、AGENTS.md / CLAUDE.md に関心がある人向けです。
Claude Code や Codex を触ると、最初はかなり驚きます。
自然言語で頼むと、ファイルを読み、コードを書き、テストを走らせ、エラーを見て直す。以前なら半日かかった作業が、数分で形になることもあります。
ただ、しばらく使うと別の問題にぶつかります。
速い。たしかに速い。けれど、方向を間違えると速く間違える。テストが薄いまま「できました」と言う。既存の設計を見落とす。小さな修正のはずが、関係ないファイルまで触る。レビューしてみると、表面は整っているのに、肝心な前提がずれている。
ここで多くの人は、こう考えます。
「やっぱりAIはまだ信用できない」
半分は正しいです。何も考えずに任せるなら、信用しない方がいい。
でも、もう半分は違います。問題は、AIが使えないことではありません。AIに仕事を渡す工程がないことです。
人間に仕事を頼むときでも同じです。いきなり「いい感じに全部やって」と言えば、相手が優秀でも事故ります。目的、制約、判断基準、確認方法、失敗したときの戻し方が必要です。
AIエージェントも同じです。
違うのは、AIエージェントは人間よりずっと速く動くことです。だから工程が弱いと、失敗も速く広がります。逆に、工程が強いと、速さがそのまま武器になります。
この記事では、その工程を4つに分けます。
Plan 作らせる前に、仕事を設計する
Work 小さく作らせ、実行結果を見ながら進める
Review 出てきたものを、人間と別の仕組みで検品する
Compound 一度の学びを、次の仕事が楽になる形で残す
この4つは、CLAUDE.md / AGENTS.md / evals / sandbox のような実務の部品と、かなりきれいにつながります。
この記事の目的は、Claude Code と Codex の比較ではありません。
どちらが強いかは、モデルや時期で変わります。大事なのは、どのエージェントを使っても崩れない仕事の流れを作ることです。
まず、「AIに作らせる」から離れる
最初に捨てたい考え方があります。
それは、AIエージェントを「コードを書いてくれる人」とだけ見ることです。
もちろん、コードは書けます。むしろそこが目立つので、最初は誰でも「書かせる」ことに意識が向きます。
でも、実務で価値が出るのは、コードを書く瞬間だけではありません。
- 何を作るべきか決める
- 既存のコードを読む
- 変更範囲を絞る
- 仕様の曖昧さを見つける
- テスト観点を出す
- 実装する
- エラーを読んで直す
- diff を説明する
- レビューで論点を圧縮する
- 失敗を次回のルールに変える
この全体が仕事です。
AIエージェントを使うというのは、この中のどこか一つを丸投げする話ではありません。仕事全体の流れを組み直す話です。
ここを間違えると、「AIに全部任せる」か「AIは信用できない」の二択になります。どちらも雑です。
実務では、もっと地味な使い方になります。
作らせる前に調べさせる。
大きな変更を小さく分ける。
実行結果を見ながら進める。
別の視点でレビューさせる。
うまくいった手順を残す。
失敗したパターンを次のルールにする。
この地味な積み重ねが、AIエージェントを「便利な一発芸」から「仕事の一部」に変えます。
全体像：Plan、Work、Review、Compound
まず全体像を置きます。
この流れのポイントは、最後が「完了」ではなく「Compound」になっていることです。
普通の開発では、タスクが終わるとそこで終わりがちです。
でもAIエージェントを使うと、同じ種類の失敗が何度も起きます。
- 毎回、テストを書き忘れる
- 毎回、既存の命名規則を外す
- 毎回、UI文言が少し硬い
- 毎回、DB migration の影響範囲を見落とす
- 毎回、型は通るが仕様と違う
- 毎回、README 更新を忘れる
この「毎回」を放置すると、人間が毎回同じ注意をすることになります。AIを使っているのに、人間のレビュー負荷だけが増えます。
Compound は、ここを変える考え方です。
一度起きた失敗を、次回の入力に戻す。
一度うまくいった手順を、再利用できる形にする。
一度作った判断基準を、AGENTS.md、チェックリスト、テスト、eval、skill、subagent、prompt template に落とす。
これができると、1回の作業が次の作業を少し楽にします。
一つひとつの仕事が、次の仕事を簡単にする。Compound の考え方は、ここにあります。
Plan：作らせる前に、仕事を設計する
AIエージェントでいちばん差が出るのは、実装前です。
コードを書かせる前に、どれだけ仕事を小さく、検証可能な形にできるか。ここでほぼ決まります。
agent に渡す仕様は、かなり実務的に考えた方がいいです。巨大な仕様を一気に投げるのではなく、AIが迷わないだけの情報を渡す。大きな仕事は小さく分ける。最初は read-only mode で計画だけ出させる。構造、スタイル、テスト、境界を明確にする。
これは、普段の使い方にそのまま落とせます。
最初の依頼で、いきなりこう書かない方がいいです。
検索機能を追加してください。
これだと、AIは勝手に不足分を埋めます。検索対象、UI、状態管理、API、テスト範囲、既存設計との関係を、かなりの部分で推測します。推測が当たれば速いですが、外れれば後始末が重くなります。
最初は、こう頼む方が安定します。
まだ実装しないでください。
このリポジトリを読んで、検索機能を追加する場合に
どのファイルを確認すべきか、どの設計に合わせるべきか、
どんな実装案がありそうかを整理してください。
出してほしいもの：
- 現在の画面構成
- 状態管理の場所
- 既存の検索・フィルタ処理があるか
- 変更候補ファイル
- リスク
- 必要なテスト
コード変更はまだしないでください。
ここで大事なのは、「作業」ではなく「観察」を頼んでいることです。
AIエージェントは、頼めばすぐ作り始めます。だから人間側が止めます。まず読む。次に計画する。最後に小さく作る。
Planで決めること
Plan では、少なくとも次を決めます。
| 項目 | 決めること |
|---|---|
| 目的 | 何ができれば完了か |
| 非目的 | 今回やらないこと |
| 入力 | どの資料、どのファイルを見るか |
| 変更範囲 | 触ってよい場所、触らない場所 |
| 判断基準 | 何をもって「良い」とするか |
| テスト | どのテストを足すか、どれを走らせるか |
| 停止条件 | 不明点が出たらどこで止まるか |
「非目的」は特に効きます。
AIは親切なので、つい周辺まで直します。小さなUI修正のつもりが、コンポーネント構造まで整理し始めることがあります。悪意はありません。でも、実務では困ります。
だから、やらないことを明示します。
今回は検索欄の追加だけを扱います。
APIの仕様変更、DB schemaの変更、デザインシステムの更新はしないでください。
必要に見えても、提案に留めてください。
この一文だけで、事故はかなり減ります。
Planで詰まるところ：前提が毎回消える
Plan が安定しない原因の一つは、前提が毎回消えることです。
昨日のレビューで決めた命名規則。先週の障害調査で分かった危ない依存関係。チームで避けることにした実装パターン。前回の作業で「次から必ず確認しよう」と決めたテスト観点。
人間なら、こういうものを何となく覚えています。けれど agent のセッションは、基本的には毎回リセットされます。AGENTS.md や CLAUDE.md に書いていないもの、project memory に残っていないもの、手元のチェックリストに入っていないものは、次の Plan に戻ってきません。
ここで memory layer が出てきます。
たとえば GPS、Walrus Memory、Minimi のような道具は、「AIに何でも覚えさせるための記憶ツール」として見ると少し浅いです。Plan の文脈では、役割はもっと具体的です。
過去の判断を、次の Plan に戻すための部品です。
repo rules、past lessons、よくある失敗、レビューで毎回直している点を、次の作業の入口に戻せるか。ここが見どころです。
だから、こういうツールを評価するときも、「記憶できますか」では足りません。
- 古い記憶をどう捨てるか
- 間違った記憶をどう直すか
- リポジトリ単位でルールを分けられるか
- agent が Plan を作る前に、その文脈を自然に読めるか
- 人間が確認しないまま危ないルールが混ざらないか
このあたりを見ます。
Plan の精度は、プロンプトの文章力だけでは決まりません。Plan の前に、どんな前提が戻ってくるかで決まります。
良いPlanは、実装を急がない
Plan の段階でほしいのは、立派な設計書ではありません。
「この仕事は、どこを触ればよくて、どこが危ないのか」が分かるメモです。
たとえば、こういう出力なら十分です。
実装方針：
1. ProductList.tsx に検索入力を追加する
2. 既存の category filter と同じ state 管理に合わせる
3. filterProducts() に name / sku の部分一致を追加する
4. 既存の sort 処理の前に filter を適用する
5. ProductList.test.tsx に3ケース追加する
リスク：
- category filter と検索条件の組み合わせ
- 大文字小文字の扱い
- 空文字のときに全件表示されるか
不明点：
- sku も検索対象に含めるか
- 日本語の表記ゆれを吸収する必要があるか
これなら人間が判断できます。
ここで「sku は対象外」「表記ゆれは今回は不要」と返せば、Work に進めます。
Work：小さく作らせ、実行結果を見ながら進める
Plan が通ったら、Work に入ります。
Work で大事なのは、小さく作らせることです。
AIエージェントは、長いタスクもこなせます。ただ、長いタスクほど、途中の判断が増えます。判断が増えると、勝手な補完も増えます。
だから最初は、次のように区切ります。
方針はOKです。
まず ProductList.tsx と filterProducts() だけ変更してください。
テストはまだ追加しないでください。
変更後、diff の要点と、次に追加すべきテストを説明してください。
一気に全部ではなく、薄く一歩進める。
その後でテストを足します。
次に ProductList.test.tsx にテストを追加してください。
必要なケース：
- 空文字なら全件表示
- 商品名で部分一致
- category filter と検索条件を同時に使う
テストを追加したら、関連テストだけ実行してください。
失敗した場合は、原因を説明してから修正してください。
ここで、実行して失敗を見ながら直す考え方が効いてきます。
AIに「書いて終わり」にさせない。実行する。失敗を見る。原因を読む。修正する。もう一度走らせる。
このループがあるだけで、AIの出力はかなり仕事に近づきます。
大事なのは、失敗したときにすぐ修正させるだけでなく、原因を説明させることです。
テストが失敗した場合は、すぐ修正せずに、
まず失敗原因を1段落で説明してください。
その後、最小の修正案を出してください。
これを入れると、AIが場当たり的な修正をしにくくなります。
Workで詰まるところ：実行環境が近すぎる
Work に入ると、問題はプロンプトではなく実行環境になります。
agent にテストを走らせる。ビルドさせる。ローカルサーバーを立てさせる。ログを読ませる。ここまでは自然です。
ただ、ローカルPCで自由にコマンドを打たせると、agent は自分の作業環境に近すぎます。ファイル、環境変数、認証情報、SSH鍵、ブラウザのログイン状態、社内ネットワーク。人間が普段あまり意識していないものに、agent が触れる可能性があります。
ここで sandbox や remote execution environment が出てきます。
Boxes.dev や AppWizzy のような道具は、「Claude Code / Codex をもっと便利に使う」ためだけのものではありません。Work の段階で、agent をどこで動かすかを分けるための部品です。
自分の作業機で動かすのか。
一時的なVMで動かすのか。
クラウド上の隔離環境で動かすのか。
ネットワークを切った環境で動かすのか。
secrets をそもそも入れない環境で動かすのか。
この設計をしないまま agent の実行権限を広げると、便利さと同じ速度で事故の半径も広がります。
DotBGE のような local-first encryption 系の道具も、この文脈で見ると分かりやすいです。agent がファイルに触るなら、どのファイルを見せるのか、どのデータは暗号化しておくのか、どこまでローカルに閉じるのかが問題になります。
Work の段階で見るべき問いは、「この agent は賢いか」ではありません。
この agent は、失敗しても被害が広がらない場所で動いているか。
この問いを立てると、sandbox 系のツールが自然に出てきます。
Workで見たいもの
Work の終わりには、次を出させます。
最後に、以下を短くまとめてください。
- 変更したファイル
- 変更内容
- 実行したテスト
- 未確認のこと
- 人間に見てほしい点
このまとめは、後の Review にそのまま使えます。
AIに作らせるだけだと、人間は差分を追うところから始める必要があります。AIに「レビューの入口」を作らせると、人間は判断に集中できます。
Review：人間は、全部を読むより「見る場所」を決める
AIエージェントを使うと、作業量は増えます。
これは意外かもしれません。自動化するのに、なぜ増えるのか。
理由は簡単です。作れる量が増えるからです。
自動化が進むほど、人間の仕事が消えるとは限りません。むしろレビュー、判断、調整が増える。この感覚は、AI coding agent を使うとすぐ分かります。
AIはたくさん作れます。だから、人間はたくさん判断することになります。
ここで必要なのは、全部を根性で読むことではありません。見る場所を決めることです。
Reviewで見るべき5点
私は、最低限この5つを見ます。
| 見る点 | 確認すること |
|---|---|
| 目的 | 最初の目的を満たしているか |
| 範囲 | 関係ない変更をしていないか |
| テスト | 本当に失敗しうるケースを押さえているか |
| 既存設計 | 既存の流儀から外れていないか |
| 失敗時 | エラー、空状態、権限、境界条件を見ているか |
この5つをそのままレビュー依頼にできます。
このdiffをレビューしてください。
観点：
1. 最初の目的から外れていないか
2. 変更範囲が広がりすぎていないか
3. テストが実装の都合に寄りすぎていないか
4. 既存の設計・命名・責務分担に合っているか
5. 空状態、エラー、権限、境界条件の見落としがないか
問題がある場合は、重大度順に指摘してください。
修正案は、最小変更を優先してください。
これは別のエージェントに投げてもいいです。
たとえば、Claude Code で実装し、Codex で diff review する。Codex で実装し、Gemini に長い文脈で第三者レビューさせる。どの組み合わせでも構いません。
重要なのは、実装した同じ流れのまま「問題ないよね？」と聞かないことです。
同じ文脈に浸かっていると、AIも人間も前提を疑いにくくなります。レビューは、少し距離を置いた方が効きます。
「AIが書いたコード」をそのまま受け入れない
たとえば SQLite の AGENTS.md は、この点でとても示唆的です。
AIが生成したコードをそのまま受け入れるわけではない。一方で、再現可能なテストケースを含むバグ報告は受け入れる。つまり、AIの参加を完全に拒むのではなく、どの形なら価値があり、どの形は危ないかを分けています。
これは実務でも使える考え方です。
AIが書いたコードを、そのまま本番に入れる必要はありません。
でも、AIに次をやらせる価値はあります。
- 再現手順を作る
- 失敗するテストを書く
- 変更候補を出す
- diff の論点を整理する
- 既存コードの読み取りメモを作る
- review checklist を作る
つまり、AIの出力を「完成品」としてではなく、「人間が判断しやすくする材料」として使う。
この距離感があると、AIエージェントはかなり使いやすくなります。
Reviewで詰まるところ：人間の目が追いつかない
agent が作る量が増えると、Review の問題はすぐに変わります。
最初は「AIが書いたコードを人間が見る」で済みます。けれど、PR が増え、修正案が増え、複数 agent が並行で動くようになると、人間は全部を丁寧に見ることができません。
ここで必要になるのは、「AIにもう一度レビューさせる」だけではありません。
どの作業が走ったのか。
どのプロンプトで、どのファイルを触ったのか。
どのテストが通り、どこで失敗したのか。
どの変更を人間に上げるべきか。
CI に入る前に止めるべき差分はどれか。
ここで trace や CI に入る前の検証が出てきます。
PromptLayer のような道具は、AIの実行履歴、プロンプト、コスト、ワークフローを追う位置に入ります。Review の材料を残すためです。
Chunk sidecars のような仕組みは、AIが作った差分を CI に入れる前に検証する位置に入ります。人間が全部を見る前に、明らかに危ないものや雑なものを止めるためです。
Linear Diffs のような PR review workflow も同じ文脈です。diff をただ表示するのではなく、人間が見るべき変更をどう整理するかが問題になります。
この段階まで来ると、Review は「読む作業」ではなく「分診」に近づきます。
全部を読むのではなく、見るべきものを上げる。
機械で落とせるものは落とす。
人間が判断すべきものだけ残す。
AI生成コードの量が増えるほど、この層が必要になります。
Reviewはevalに近づいていく
小さな個人開発なら、人間の目視レビューで足ります。
でも、同じ種類の作業が増えてくると、レビューはだんだん eval に近づきます。
traces、evals、Codex を使って agent を改善する流れも、この延長にあります。LLMやagentの品質は、雰囲気ではなく、実データ、失敗例、評価セット、回帰テストで見ていく。
これは大げさな話ではありません。
たとえば、社内FAQ bot でも、coding agent でも、毎回同じ確認をしているなら、それは eval にできます。
- 回答に根拠URLが含まれるか
- 存在しないAPIを使っていないか
- 変更対象外のファイルを触っていないか
- migration を変更したら rollback もあるか
- セキュリティ境界を越えていないか
- 既存のテストを消していないか
最初はチェックリストでいいです。
チェックリストが安定してきたら、テストやスクリプトにする。さらに必要なら eval にする。
Review は、人間の気合いから、少しずつ仕組みに移していくものです。
Compound：一度の失敗を、次の成功に変える
ここがこの流れのいちばん大事な部分です。
AIエージェントを使っていると、失敗は必ず起きます。
失敗が問題なのではありません。同じ失敗が何度も起きることが問題です。
たとえば、AIがまたテストを浅く書いたとします。
その場で「もっとちゃんとテストして」と言えば、今回は直るかもしれません。でも次回また起きます。
Compound では、その失敗を次回の仕組みに入れます。
今後、このプロジェクトでUIの状態変更を扱うときは、
正常系だけでなく、空状態、複数条件の組み合わせ、リセット操作を
最低1ケースずつテスト候補に入れてください。
これを AGENTS.md に入れる。あるいは project memory に入れる。あるいは review prompt のテンプレートに入れる。
大事なのは、「今回の注意」で終わらせないことです。
Compoundの置き場所
学びを残す場所はいくつかあります。
| 置き場所 | 向いているもの |
|---|---|
AGENTS.md |
リポジトリ全体のルール、コマンド、禁止事項 |
CLAUDE.md |
Claude Code 向けの作業方針、プロジェクト文脈 |
| project memory | 長期的な好み、繰り返す判断 |
| checklist | review 観点、作業前確認 |
| prompt template | よく使う依頼文 |
| skill / plugin | 手順として再利用したい作業 |
| test / eval | 機械的に判定したい品質基準 |
どれが正解という話ではありません。
短い注意なら AGENTS.md。
毎回使う依頼ならテンプレート。
何度も起きる失敗ならテスト。
複雑な作業手順なら skill。
品質判定なら eval。
こう考えると整理しやすいです。
Compoundで詰まるところ：学びが次回に戻らない
Compound でいちばん難しいのは、学びを残すことではありません。
残した学びが、次回の作業に戻ってくることです。
AGENTS.md にルールを書いても、長くなりすぎれば読まれにくくなります。project memory に保存しても、古い判断が混ざれば邪魔になります。skill にしても、agent が必要なタイミングで呼べなければ意味がありません。
ここで、memory や作業手順を次回に返す道具がもう一度出てきます。
Walrus Memory や GPS は、単に文脈を保存する道具としてではなく、過去の作業結果を次の Plan に戻す部品として見る。Recursi のような道具は、作業の中で得た手順や修正パターンを次に返す仕組みとして見る。
つまり、ここでも評価軸は「便利そうか」ではありません。
- 前回の失敗が次回の Plan に出てくるか
- review で直したことが次回のチェックリストに入るか
- テスト不足が次回の spec に反映されるか
- agent が勝手に悪いルールを増やさないか
- 人間が memory や skill を棚卸しできるか
このあたりを見ます。
Compound は、記憶の量ではありません。学びが次の工程に戻る経路です。
悪いCompound、良いCompound
悪い例は、抽象的すぎるルールです。
品質に気をつけてください。
これはほとんど効きません。何をすればいいか分からないからです。
少し良くすると、こうなります。
実装後は必ずテストしてください。
まだ弱いです。どのテストを、どの範囲で、失敗したらどうするかが曖昧です。
もっと良いのは、こういう形です。
UIコンポーネントを変更した場合：
- 既存の関連テストを先に確認する
- 状態が変わる操作を最低1ケース追加する
- 空状態またはエラー状態がある場合は、その表示も確認する
- テストを実行し、失敗した場合は原因を説明してから修正する
AIに効くルールは、精神論ではなく手順です。
手順を skill として分けるのも、このためです。調査、計画、実装、原因切り分け、レビュー、次回への反映を分ける。作業の種類ごとに、必要な入力と出力を決める。
人間が毎回思い出していたことを、エージェントが引ける形にする。
それが Compound です。
Claude Code と Codex はどう使い分けるか
ここまで読んで、「では Claude Code と Codex はどちらを使えばいいのか」と思うかもしれません。
私の答えは、固定しない方がいい、です。
モデルや製品の得意不得意は変わります。今日の最適解が、来月も同じとは限りません。
ただ、役割として分けるなら、次のように考えると使いやすいです。
| 役割 | 向いている使い方 |
|---|---|
| Claude Code | 複雑な文脈の整理、設計相談、既存コードの読み解き、長めの計画 |
| Codex | 実装、修正、diff review、反復実行、並列タスク |
| Gemini など大文脈モデル | 第三者レビュー、長い資料の確認、抜け漏れ探し |
| 人間 | 目的、優先順位、許容リスク、最終判断 |
これは絶対ではありません。
大事なのは、ツールの役割分担より、工程の役割分担です。
Plan は誰がやるのか。
Work はどこまで任せるのか。
Review は何を見るのか。
Compound はどこに残すのか。
この4つが決まっていれば、使うエージェントが変わっても崩れにくい。
逆に、ここが決まっていないと、どのエージェントを使っても「速いけど怖い」で止まります。
実例：小さな機能追加を4段階で回す
ここで、具体例を置きます。
既存の管理画面に、商品検索機能を追加するとします。
1. Plan
最初の依頼です。
まだ実装しないでください。
管理画面の商品一覧に検索機能を追加したいです。
まず既存コードを読んで、実装計画だけ出してください。
確認してほしいこと：
- 商品一覧画面のコンポーネント
- 商品データの取得方法
- 既存のフィルタやソート処理
- 状態管理の方法
- 関連テスト
出力してほしいこと：
- 変更候補ファイル
- 実装方針
- リスク
- 必要なテスト
- 不明点
今回はまだファイルを変更しないでください。
ここで出た計画を人間が見ます。
検索対象が商品名だけでいいのか、SKUも含めるのか。サーバー側検索か、クライアント側フィルタか。大規模データを想定するか。
こういう判断は、人間がした方がいいです。
2. Work
計画を絞ったら実装します。
方針はOKです。
今回はクライアント側で商品名のみ検索します。
SKU検索、API変更、ページネーション変更はしないでください。
まず実装だけ行ってください。
変更後、diff の要点を説明してください。
次にテストです。
関連テストを追加してください。
必要なケース：
- 検索文字列が空なら全件表示
- 商品名の部分一致で絞り込める
- 既存のカテゴリフィルタと同時に使える
テストを実行し、失敗した場合は原因を説明してから修正してください。
3. Review
実装後、別の視点でレビューします。
この変更をレビューしてください。
観点：
- 当初の目的に合っているか
- 変更範囲が広がっていないか
- 既存の設計に合っているか
- テストが実装の都合に寄りすぎていないか
- 空状態や境界条件の見落としがないか
重大度順に指摘してください。
修正案は最小変更を優先してください。
ここで人間も見るべきです。
AIレビューは便利ですが、最終判断ではありません。特に、仕様の優先順位、ユーザー体験、今やらない判断は、人間が持つべきです。
4. Compound
最後に、今回の学びを残します。
今回の作業から、次回以降も使えるルールを抽出してください。
対象：
- AGENTS.md に追加すべきルール
- review checklist に追加すべき観点
- テストテンプレートにできるもの
抽象論ではなく、このリポジトリで再利用できる具体的な文にしてください。
出てきたものを、そのまま入れずに人間が見ます。
たとえば、次のようなルールなら使えます。
一覧画面にフィルタや検索を追加する場合：
- 既存のソート・カテゴリフィルタとの組み合わせを確認する
- 空文字の場合に全件表示されるテストを追加する
- API仕様変更が必要に見える場合も、まず提案に留める
これで、次の一覧画面の変更が少し楽になります。
この「少し楽になる」を積み上げるのが、Compound です。
コード以外の技術作業にも同じ流れを使う
ここまで機能追加の例で書きましたが、この4段階はコードを書く場面だけに限りません。
技術者の日常には、コード以外にも agent と相性のよい作業があります。
- 既存リポジトリの調査
- 障害原因の切り分け
- PR の事前レビュー
- ライブラリ更新の影響調査
- RFC や設計メモの下書き
- migration 手順の確認
- ログや trace の読み取り
- セキュリティ観点の棚卸し
たとえば、障害調査ならこうです。
Plan
まだ修正しないでください。
このエラーログと関連コードを読んで、
原因候補を整理してください。
出してほしいもの：
- 直接のエラー原因
- 関係しそうなファイル
- 最近の変更で怪しい箇所
- 再現に必要な条件
- 追加で確認すべきログ
推測と事実を分けて書いてください。
Work
まず再現テストだけ作ってください。
本体コードはまだ修正しないでください。
テストが失敗することを確認したら、
失敗ログを短く説明してください。
Review
この再現テストをレビューしてください。
観点：
- 本当に今回の障害を再現しているか
- 実装の詳細に寄りすぎていないか
- 既存の正常系を壊していないか
- より小さい再現ケースにできないか
Compound
今回の障害から、次回同じ種類の問題を早く見つけるための
チェック項目を作ってください。
置き場所は AGENTS.md か runbook を想定します。
抽象論ではなく、このリポジトリで使える具体的な文にしてください。
これなら、コード修正に入る前に再現条件と判断材料がそろいます。
AIエージェントにいきなり修正させるのではなく、まず調査、次に再現、最後に修正。技術作業では、この順番がかなり効きます。
このシリーズで扱うこと
この記事は入口です。
ここから先は、各論を分けて深く書きます。
第1回：AIエージェントに渡す仕様書の書き方
大きな依頼を壊さず、小さく渡す方法を扱います。
扱うこと：
- 良い spec と悪い spec
- read-only plan
- 非目的の書き方
- 変更範囲の指定
- テスト条件
- 仕様が長すぎるときの分割
第2回：AIエージェントの仕事をどう検品するか
AIが出した成果物を、どうレビューするかを扱います。
扱うこと：
- diff review
- human review
- AIによる一次判定
- eval
- traces
- 回帰テスト
- 「なんとなく良い」から抜ける方法
第3回：一度の失敗を次の成功に変える
memory と学びの戻し方を扱います。
扱うこと：
- 失敗をルールに変える
-
AGENTS.md/CLAUDE.md - project memory
- skill
- subagent
- review checklist
- SQLite の AGENTS.md が示す「受け入れるAI成果物」と「受け入れないAI成果物」
第4回：AIエージェントに実行させる前に
Sandbox、権限、ファイル境界を扱います。
扱うこと：
- process sandbox
- VM
- filesystem boundary
- egress control
- credentials を渡さない設計
- コード実行の危険
- agent horror stories
第5回：MCPとToolsをどう考えるか
外部ツール接続を扱います。
扱うこと：
- MCP の役割
- 何でもつなぐ危険
- read-only tool と write tool
- 権限スコープ
- 監査ログ
- ツールが増えたときの管理
第6回：既存リポジトリ調査と障害調査で使う
コードを書く前の調査、再現、切り分けを扱います。
扱うこと：
- read-only 調査
- 変更前の仮説整理
- 再現テスト
- ログと trace の読み方
- 先に runbook を作らせる
- 修正前レビュー
第7回：Codex App / Desktopを技術作業台として使う
Codex App を、技術者がローカル作業・レビュー・画面確認を進める作業台として扱います。
扱うこと：
- project
- thread
- files
- Appshots
- ローカルファイルを見せる
- UI崩れやエラー画面を見せる
- CLI版との使い分け
第8回：実戦テンプレート集
毎回使える依頼文をまとめます。
扱うこと：
- 調査だけ頼む
- 実装計画だけ頼む
- 小さく実装させる
- テストを追加させる
- diff review
- 失敗原因の説明
- AGENTS.md 更新
- 次回用チェックリスト化
これは stock される記事にします。読者がそのまま貼って使える形にします。
第9回：AIエージェント導入の判断基準
最後に、チームや個人がどこから始めるべきかを扱います。
扱うこと：
- どの作業から始めるか
- 任せてよい作業、まだ任せない作業
- コスト
- review 負荷
- 事故時の戻し方
- 小さく始める導入順
まとめ
Claude Code や Codex を使う力は、良いプロンプトを一回書く力ではありません。
もちろん、プロンプトは大事です。でも、それだけでは足りません。
実務で差がつくのは、仕事を工程に分ける力です。
作らせる前に計画する。
小さく作らせる。
検品する。
失敗を次回のルールに変える。
Plan、Work、Review、Compound。
この4つを回せるようになると、AIエージェントは単なる「速いコード生成」ではなくなります。
仕事のやり方そのものが変わります。
そして、ここから先の本題は、モデル選びではありません。
どんな仕様を渡すか。
どんな境界を作るか。
どんなレビューを通すか。
どんな失敗を残すか。
どんな作業を次回から楽にするか。
AIエージェント時代の開発力は、たぶんこのあたりに移っていきます。