生成コードのレビュー観点：差分を読むときのチェック

普段のコード編集は、AIエージェント（主に Codex）に任せています。どの作業をどのエージェントに任せているかは AIコーディングエージェントの使い分けメモ にまとめました。実装そのものは速いし、定型的な変更なら自分で打つよりよほど手早い。一方で、コミットと push は今も自分の担当です。エージェントが返してきた差分を読み、問題があれば差し戻し、問題がなければ自分でコミットする。この「読む」工程を雑にすると、速さの分だけ変な変更が混ざる確率が上がります。

この記事は、その差分レビューで実際に見ている観点を整理したものです。特定のツールの使い方ではなく、生成されたコードを読むときの実務論として書きます。

差分は「全体像」から読む

いきなりコードの細部から読み始めると、変更の目的を見失いがちです。自分の読み方はだいたい次の順番です。

1. 変更ファイルの一覧を見る：想定していたファイルだけが触られているか。ここで既に「なぜこのファイルが変わっているのか分からない」ものがあれば、その時点で要注意です
2. 変更量の大きいファイルから読む：行数の多い変更ほど、設計判断が含まれています。小さい変更は後回しで構いません
3. テストの差分を読む：実装とセットでテストがどう変わったか。実装だけ変わってテストが無傷なら、それはそれで疑う材料です
4. 細部（命名、スタイル）：最後にざっと。細部の好みは、動くかどうかより優先度が低いはずです

読み方の要点：最初に見るのは「何が書いてあるか」ではなく「何が変わったか」の地図です。地図の段階で違和感があれば、細部を読む前に差し戻した方が早い。

観点別のチェック

観点ごとに、自分が差分の中で探しているものをタスクリストにしました。毎回全部を完璧に見るわけではありませんが、最低でも上から3つは目を通します。

• スコープ外の変更がないか：頼んだ修正と関係のないリファクタリング、整形、コメントの書き換えが混ざっていないか
• 重複実装になっていないか：既存に似た処理があるのに、新しい関数やユーティリティが増えていないか
• エラー処理が省略されていないか：正常系だけ通して、失敗時の扱いが消えていないか
• 命名と書き方が既存の規約に合っているか：そのファイル・そのプロジェクトの流儀から浮いていないか
• 依存が増えていないか：新しいライブラリの追加は本当に必要か。標準機能や既存の依存で済まないか
• テストが「通ること」だけを狙っていないか：期待値を実装に合わせて書き換えるなど、テストの意味を消す変更がないか（テストを書かせるときの頼み方側の注意は AIにテストを書かせるときの注意点 に分けました）

順番にも理由があります。スコープ外変更と重複実装は、放置すると後から効いてくる種類のノイズです。頼んでもいないリファクタリングが混ざると、そのコミットの目的がぼやけるし、将来その変更を戻したくなったときに巻き戻しが効かなくなります。重複実装はもっと静かに効きます。同じ役割の処理が2か所にあると、次の修正で片方だけ直して「直したはずなのに直っていない」が起きる。AIは既存コードを全部把握して書いているわけではないので、ここは人間の側で見ておく価値が高いところです。

エラー処理の省略は、生成コードで一番よく見るパターンだと感じています。正常系のコードは気持ちよくスラスラ出てくるのに、例外や失敗時の分岐は「省略されがち」。元のコードにあった try-catch やバリデーションが、書き直しの過程でひっそり消えていることがあります。消えた防御は、動いている間は誰にも気づかれません。

危ないサインの早見表

読んでいて「ん？」となるサインには、だいたい型があります。

サイン	疑うこと
変更ファイルが想定よりずっと多い	スコープ外のリファクタリングや自動整形が混ざっている
テストの期待値だけが書き換わっている	実装の不具合を、テスト側を直して「通した」可能性がある
既存と似た名前の新しい関数が増えた	既存実装を探さずに新規実装した重複の可能性
エラー処理やバリデーションの行が減った	正常系に寄せて防御を落とした可能性
依存パッケージが追加された	標準機能や既存の依存で済む話を、導入で解決した可能性
コメントが「丁寧に」大量追加された	中身の変更をごまかす水増し、または頼んでいない整形

表のサインは「見つけたら即差し戻し」ではなく、「そこを重点的に読む」ための目印です。たとえば依存の追加が本当に必要な場面もあります。大事なのは、追加された理由を自分が説明できるかどうか。説明できない変更は、まだコミットする段階にない、という判断にしています。

判断のものさし：「この変更はなぜ入ったのか」を自分の言葉で言えるかどうか。言えない変更が混ざっていたら、その部分だけ切り分けて確認します。

差し戻すときの指示の書き方

レビューの結果、直してほしい点があったときの伝え方にも、効く書き方と効かない書き方があります。自分の経験では、次の3点を入れた指示が一番戻りが安定しました。

1. 場所を具体的に指す：「○○ファイルの△△関数の分岐」のように、ファイルと対象を特定する。「全体的に直して」はほぼ効きません
2. 観点を言葉にする：「スコープ外の変更が混ざっているので、今回の修正に必要な変更だけに戻して」のように、なぜダメかではなく「何をどう戻すか」を書く
3. やってほしくないことを先に書く：「依存は追加しない」「既存の関数は再利用する」「テストの期待値は変えない」のような禁止事項を冒頭に置くと、再生成時のブレが減ります

逆に、「もっと良い感じに」「きれいに」といった感想ベースの指示は、だいたい別の場所が変わって戻ってきます。AIへのレビュー指示は、人間へのレビューコメントよりも、むしろ機械的に書いた方がうまくいく印象です。

読むコストとの付き合い方

正直なところ、差分を毎回きっちり読むのは面倒です。でも、生成が速くなった分、ボトルネックは「書く」から「読む」に移っただけだと思っています。読む工程を省いたら、それはレビューをしていないのと同じで、問題が本番や将来の自分に先送りされるだけです。

全部を精読する代わりに、自分は「地図→大きな変更→テスト」という順番と、上のチェックリストで範囲を絞っています。それでも読み切れない規模の変更が返ってきたら、変更自体を小さく区切って頼み直す。差分が大きいこと自体が、レビューの観点ではひとつのサインです。

エージェントに任せる範囲が広がるほど、「最後に読んで判断するのは自分」という工程の価値は上がっていくはずです。速く書けるようになった分、読む側の型を持っておく。それが今のところの自分の落としどころです。