この記事は「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エージェント時代の開発力は、たぶんこのあたりに移っていきます。