メインコンテンツへスキップ
見出し画像

AIが書いたPRを、コード差分だけでレビューしない――「振る舞い変更表」7項目

    コーディングエージェントが数分でPRを作った。テストも通っている。変更ファイルは30個。説明欄には「リファクタリングとエラーハンドリングを改善しました」とある。

    ここから人間のレビューが始まります。しかし最初に知りたいのは、変更された行の数ではありません。

    利用者から見て何が変わるのか。何は変わらないのか。データや権限に影響はあるのか。どの証拠を見れば、その主張を確認できるのか。

    コード差分は、これらの問いへ直接答えてくれません。生成速度が上がるほど、人間は大量の差分から「変更の意味」を復元する作業に追われます。

    この記事では、AIが作ったPRへ添える「振る舞い変更表」を提案します。英語ではBehavioral Change Manifestと呼びます。7項目の表とテンプレートを使い、コードを読む前にレビューの地図を作る方法です。

    対象は、コーディングエージェントを個人利用からチーム運用へ広げたいテックリード、アーキテクト、社内SEです。特定のAI製品には依存しません。

    AIがコードを書くほど、レビューの入口が重要になる

    GitHubは2026年10月5日、AIコードレビューを評価するReviewBenchを公開しました。評価は単なる正解数ではなく、指摘のprecisionとrecall、重大度、カテゴリなどを扱います。

    これは大事な変化です。AIレビューを入れたかどうかではなく、何を見つけ、何を見落とし、どれだけノイズを出すかを測る段階に入ったからです。

    一方、GitHubのCopilot生成物をレビューする公式Docsは、Copilotが作ったPRもマージ前に十分確認するよう求めています。特にGitHub Actionsのworkflow変更は、秘密情報へ触れ得るため注意が必要です。

    つまり、AIが実装し、AIがレビューする仕組みが増えても、最終的な判断責任は消えません。むしろ出力が増えるほど、人間の注意をどこへ向けるかが難しくなります。

    24,014件のagentic PRを分析した研究では、AIエージェント由来のPRについて、変更規模やPR説明とdiffの類似性が調べられています。説明とdiffが近いことは有益ですが、説明を読めば業務上の影響まで理解できる、という意味ではありません。

    「どのファイルを変えたか」と「利用者に何が起きるか」は、別の情報だからです。

    コード差分が答えるのはHow、レビューで知りたいのはWhatとWhy

    差分を読めば、条件式が増えた、APIの引数が変わった、テーブルへ列が追加された、と分かります。これは実装のHowです。

    しかし、レビューで判断したいのは次のようなことです。

    • どの利用者の、どの振る舞いが変わるのか

    • 従来どおり維持すべき条件は何か

    • API、状態遷移、データ、権限へどんな影響が出るのか

    • テスト結果は、どの主張の証拠になっているのか

    • 問題が起きたとき、安全に戻せるのか

    人間がコードを読みながらこれらを推測すると、レビューは遅くなります。推測が外れれば、細部は正しくても目的と異なる変更を通してしまいます。

    PR説明を長くすれば解決するわけでもありません。時系列の作業ログ、変更ファイル一覧、テストコマンドが並んでも、意思決定に必要な情報が埋もれるからです。

    必要なのは要約ではなく、変更の意味を固定する構造です。

    「振る舞い変更表」は7項目で作る

    振る舞い変更表は、コード差分の代わりではありません。コード差分を読む順番と、確認すべき証拠を示す地図です。

    1. 変える振る舞い

    誰が、どの条件で、何をすると、結果がどう変わるのかを書きます。

    「エラーハンドリングを改善」では判断できません。「在庫引当済みの注文をキャンセルしたとき、在庫を解放してから返金要求を送る」のように、観測可能な結果で表します。

    2. 変えない振る舞いと非対象

    変更内容より、こちらが重要な場合があります。

    「未引当注文のキャンセル手順は変えない」「既存APIのレスポンス形式は変えない」「今回は返金失敗時の自動再実行を対象外にする」と宣言します。

    レビューでは、新しい機能が動くことだけでなく、既存の前提が壊れていないことを確認できます。

    3. 接点と状態遷移

    API、イベント、画面、バッチ、テーブル、状態名など、システムの境界で変わるものを書きます。

    単なるファイル一覧ではありません。「注文状態にCANCEL_PENDINGを追加」「キャンセル要求APIは202を返し、完了はイベントで通知」のように、外部から観測できる契約を示します。

    4. データの扱い

    新規データだけでなく、既存データをどう扱うかを記述します。

    列追加、初期値、移行、再計算、保存期間、再処理時の重複防止を確認します。「NULL許容で列を追加」だけでは、既存行がどの振る舞いになるか分かりません。

    5. 権限と外部作用

    誰が実行できるか、外部システムへ何が送られるか、課金・通知・削除など取り消しにくい作用が増えるかを書きます。

    同じコード量でも、ログ文言の変更と返金処理の追加ではレビューの重さが違います。ここを明示すると、人間の注意を高リスク部分へ寄せられます。

    6. 主張と証拠の対応

    「テスト済み」ではなく、どの主張を何で確認したかを対応づけます。

    • 在庫が一度だけ解放される → 同一要求を2回送るテスト

    • 返金失敗で完了扱いにならない → 外部API失敗を注入するテスト

    • 既存レスポンス形式を維持する → 契約テストの結果

    テスト名、CI結果、ログ、スクリーンショット、検証クエリは証拠になり得ます。ただし、証拠がどの主張を支えるのか分からなければ、添付物が増えただけです。

    7. 戻し方と未確定事項

    feature flag、ロールバック手順、データを戻せる条件、監視項目、残っている不確実性を書きます。

    「元のコミットへ戻す」だけでは、すでに新形式で保存されたデータや送信済み通知は戻りません。コード、データ、外部作用を分けて考えます。

    そのまま使えるPRテンプレート

    次のテンプレートをPR本文へ置きます。すべてを長く書く必要はありません。該当しない項目は「なし」とし、その判断理由を一言添えます。

    ## 振る舞い変更表
    
    ### 1. 変える振る舞い
    - 対象者/条件/操作/変化後の結果:
    
    ### 2. 変えない振る舞い・非対象
    - 維持する不変条件:
    - 今回の非対象:
    
    ### 3. 接点・状態遷移
    - API/イベント/画面/バッチ:
    - 追加・変更する状態と遷移:
    
    ### 4. データ
    - スキーマ・既存データへの影響:
    - 移行・再処理・重複防止:
    
    ### 5. 権限・外部作用
    - 実行主体と必要権限:
    - 課金/通知/削除/外部送信への影響:
    
    ### 6. 主張と証拠
    - 主張A → テスト/ログ/検証結果:
    - 主張B → テスト/ログ/検証結果:
    
    ### 7. 戻し方・未確定事項
    - コードの戻し方:
    - データと外部作用の扱い:
    - 未確認事項・追加レビューが必要な点:

    この表は、エージェントに自動生成させても構いません。ただし、生成した本人と同じエージェントが「問題なし」と自己評価しただけでは証拠になりません。リポジトリの実行結果や、人間が確認できる観測値へ接続します。

    記入例:注文キャンセル処理を変更する場合

    以下は架空の業務システムを使った例です。

    変える振る舞い

    在庫引当済みの注文をキャンセルした場合、注文を即時にCANCELLEDへ変更せず、在庫解放と返金要求が受理された後に完了させる。

    変えない振る舞い・非対象

    未引当注文のキャンセルは従来どおり同期処理とする。返金失敗の自動再実行は今回の対象外で、運用手順に従う。

    接点・状態遷移

    注文状態へCANCEL_PENDINGを追加する。キャンセルAPIの入力形式は変えない。完了通知イベントへ処理IDを追加する。

    データ

    既存注文は新状態へ移行しない。処理IDには一意制約を置き、同じ要求の再送で二重返金しない。

    権限・外部作用

    従来のキャンセル権限を持つ利用者のみ実行できる。返金要求という外部作用が追加されるため、金額と送信先を監査ログへ残す。

    主張と証拠

    二重返金しないことは、同一処理IDを再送する統合テストで確認する。途中失敗で完了状態へ進まないことは、在庫解放後に返金APIを失敗させるテストで確認する。

    戻し方・未確定事項

    新規受付はfeature flagで停止できる。CANCEL_PENDINGの注文は旧コードへ戻す前に解消する。外部へ送信済みの返金要求はコードのロールバックでは取り消せない。

    この記入例があると、レビュアーは最初からコードを上から読む必要がありません。二重実行、状態遷移、返金という高リスク領域から確認できます。

    導入は「書かせる」より「レビュー順を変える」

    テンプレートを追加するだけでは形骸化します。運用は次の順序に変えます。

    1. Issueで変更目的と不変条件を決める

    実装前に、変える振る舞いと変えない振る舞いだけは人間が承認します。

    1. エージェントが実装と同時に表を更新する

    最後に記憶から書かせず、設計判断や対象外が変わった時点で更新させます。

    1. CIが形式と証拠リンクを確認する

    高リスク領域で空欄がないか、記載したテストが実行されたかを機械的に確認します。

    1. 人間は表→証拠→差分の順に見る

    まず主張の妥当性、次に証拠、最後に実装が主張と一致するかを確認します。

    1. マージ時に表を変更記録として残す

    後から障害や仕様変更を調べるとき、コミット列より先に変更の意味へ到達できます。

    特に重要なのは4番目です。従来どおり差分から読み始めるなら、表を増やした分だけ作業が増えます。

    この方法が失敗する5つの条件

    実装後に説明をでっち上げる

    コード完成後にエージェントへ表を作らせると、現状の実装を正当化する説明になりがちです。Issueで承認した目的・不変条件と照合します。

    「影響なし」を根拠なく許す

    データ、権限、外部作用をすべて「なし」と書く場合も、なぜそう言えるかを示します。該当ファイルがない、契約テストで変化がない、といった根拠が必要です。

    テスト件数を証拠にする

    「テスト120件成功」は安心材料ですが、今回の変更主張を確認した証拠とは限りません。主張とテストを1対1または1対少数で結びます。

    すべてを高リスク扱いする

    どのPRにも同じ重いレビューを要求すると、結局読み飛ばされます。課金、認証、個人情報、削除、migration、workflowなど、注意を厚くする条件を決めます。

    表とコードのずれを放置する

    レビュー修正で実装が変わったのに表が古いままだと、誤った地図になります。表の更新を変更要求の完了条件へ含めます。

    まず20件で測るなら、時間だけを見ない

    新しいテンプレートを全社へ一斉導入する必要はありません。対象リポジトリを1つ選び、たとえば20件程度のPRで試します。20は効果を断定する数ではなく、運用上の詰まりを見つけるための初期サンプルです。

    確認したいのは次のような指標です。

    • レビュー開始から最初の判断までの時間

    • 「目的が分からない」「影響範囲が不明」という差し戻し回数

    • 表の主張とコードが食い違った件数

    • マージ後に変更理由を調べるまでの時間

    • 高リスク項目で人間レビューが実際に行われた割合

    短くなったかだけでなく、レビューで何を見つけられたかも確認します。速く承認できても、見落としが増えれば成功ではありません。

    コードを読む責任は残す。読む前の迷子を減らす

    AI生成PRのレビューを、AIへ丸ごと渡すか、人間が全行読むか。その二択にする必要はありません。

    人間が担うべきなのは、変更目的、不変条件、許容できるリスクを判断することです。AIは、差分の整理、証拠の収集、表の更新を支援できます。

    その境界を作るのが振る舞い変更表です。

    コード差分はなくなりません。けれど、コードを読む前に「何を確かめるために読むのか」が分かれば、レビューは行数を追う作業から、変更の意味を検証する作業へ変わります。

    次に読む

    このアカウントでは、大企業や長寿命システムで生成AIを使うときに、設計文書、権限、証跡、テスト、レビューをどう「AIへ任せられる状態」に変えるかを扱っています。同じ課題を、ツール紹介ではなく設計と運用の判断基準から追いたい方は、次の記事もフォローして受け取ってください。


    情報確認日:2026年10月11日

     
     
    ユーザー企業の立場から、生成AI活用、社内SE、システム企画・設計を考えます。AIエージェントの権限・検証・運用や設計情報の活かし方を、実務で使える判断基準として整理します。

    あなたへのおすすめ