AIでPull Requestの説明文を作るときは、先に「今回の差分」「変更が必要な理由」「実際に行った検証」を分けて渡します。差分にない意図や、実行していないテストを自然な文章で補わせないことが重要です。完成基準は文章量ではなく、reviewerが根拠へ戻り、変更の必要性と残る未確認を判断できることです。
この記事はPR説明の草案作成と照合を扱います。コードレビューやREADME作成とは別の成果物です。以下の仕様・差分・テストは架空例で、実repositoryのPR作成、Copilot操作、テスト実行、投稿は行っていません。
目次
比較対象を固定し、事実を三つに分ける
まずbase branch、head branchまたはcommit、対象ファイルを確定します。作業中の差分や前のPRの変更が混ざると、説明とreview画面が一致しません。GitHubのPR比較はbase/headの関係を持つため、branch比較の資料（新しいタブで開く）も確認し、実際のFiles changedと同じ範囲を使います。
表は横にスクロールできます
| 情報 | 根拠の例 | AIへ許す扱い |
|---|---|---|
| 起きていた問題 | issue・再現条件・担当者の確認 | 確認済みの条件だけを要約 |
| 最終的な変更 | 対象diffと関連実装 | ファイルと処理を結び説明 |
| 変更理由 | 要件・設計判断・人の説明 | diffから意図を推測しない |
| 検証 | command・対象commit・結果 | 実行済み/未実施を分ける |
| 制約・戻し方 | 影響範囲・運用計画 | 不明なら未確認と記す |
private codeや顧客データをAIへ入力できる環境かも確認します。secret、個人token、不要なlog全文を渡さず、生成に必要なファイルと仕様に絞ります。PR説明へ内部情報をそのまま転載しないようにします。
最終変更の前後を一つの具体例で書く
架空例として、検索欄を空にしても以前の検索結果が残る画面を考えます。以下は説明用の事実カードで、実装・動作確認済みの報告ではありません。
表は横にスクロールできます
| 項目 | 架空の入力 |
|---|---|
| 問題 | 検索欄を空にした後も旧結果が表示される |
| 最終差分 | 空入力の分岐で表示中の結果を初期状態へ戻す |
| 要件 | 空入力では検索結果を表示しない |
| 検証 | テストはまだ実行していない |
| 未確認 | 入力を素早く切り替えた場合の応答競合 |
この情報から書けるのは「空入力で旧結果が残る問題に対し、空入力分岐で表示状態を初期化する」という説明です。「全検索で性能改善」「競合を完全解決」「テスト成功」とは書けません。実装に途中で別案があっても、最終差分を中心に説明します。
AIへの依頼例は次です。
添付の最終diffと事実カードだけを根拠にPR説明案を作ってください。問題の条件、変更後の挙動、根拠ファイル、実行済み検証、未実施、影響と未確認に分けます。理由が入力にない場合は推測せず質問事項へ回してください。テストの追加と実行成功を混同しないでください。各主張に根拠ファイルまたは記録を対応付けてください。
依頼文を長くするより、入力の事実と未確認を揃える方が有効です。AIへ渡していない仕様や実行結果は、人が資料を追加するまで確定させません。
GitHub Copilotのsummaryは草案として使う
GitHub公式のPR summary手順（新しいタブで開く）は、PRの説明欄やcomment欄で生成し、内容を確認して追加contextを加える流れを案内しています。利用条件はアカウントと現行資料で確認します。同資料ではCopilot Freeでは利用できないとされています。
公式資料は、既存のPR説明の内容を生成に考慮しない点も注意しています。すでに書いた理由や検証記録がある場合は退避し、生成文への置換で失わないようにします。既存の説明を無条件に空にしたり、生成直後に投稿したりする必要はありません。
Copilot以外のAIへ差分を渡す場合も、参照できた範囲と人が補うcontextを分けます。GitHubのCopilot利用上の制約（新しいタブで開く）は、もっともらしくても不正確な出力があり得ることと、人による確認の必要性を説明しています。
実行済み検証と、追加したテストを区別する
テストファイルがdiffにあることは、テストを実行して成功した証拠ではありません。逆に既存テストだけを実行した場合、今回の変更専用の再現テストを追加したと書きません。対象commitや実行時の差分が説明対象と一致するかも確認します。
表は横にスクロールできます
| 観測した事実 | 書ける表現 | 書かない表現 |
|---|---|---|
| test ファイルを追加、未実行 | テスト追加・実行未実施 | テストPASS |
| unit testを実行し成功 | 対象commandと結果 | 実機や本番まで確認済み |
| browserで一経路を確認 | 条件・画面・結果 | 全環境で問題なし |
| 外部接続がなく未確認 | 未確認の接続と必要条件 | 接続成功を推測 |
架空例の検証欄なら「未実施。空入力と入力切替の確認が必要」と書きます。後から実行したら、実際のcommand、条件、結果へ更新します。失敗した検証も隠さず、今回の変更に関係するかと残る問題を分けます。
主張ごとにdiffと根拠へ戻る
生成後は、問題条件、変更挙動、影響範囲、検証結果を一文ずつ照合します。根拠のない主張は削除するか、確認待ちへ戻します。文章を少し弱めるだけで事実に変えることはできません。
表は横にスクロールできます
| 確認対象 | 照合先 | 不一致なら戻す場所 |
|---|---|---|
| 何が変わるか | 最終diff・仕様 | 差分読解・要件確認 |
| なぜ必要か | issue・人の判断 | 変更理由の入力 |
| どこまで確認したか | 実行記録 | 検証欄 |
| 影響・制約 | 関連実装・運用条件 | 未確認と担当者 |
| 戻せるか | 変更種別・復旧計画 | 運用設計 |
戻し方も、すべてを「revertすれば戻る」としません。DBや外部状態を変更するなら、コードの差し戻しとは別の復旧条件があります。今回の差分にその影響があるかを確認し、根拠がない場合は戻し方未検討と明示します。
追加commitの後に説明を更新する
レビュー中に修正したら、説明が現在の差分と一致するかを再確認します。取りやめた変更、古い検証結果、以前のファイル pathが残りやすい箇所です。新しい差分を見ずに文言だけを整えないようにします。
完成した説明は、問題と結果を先に示し、reviewerが見るべき変更、検証、制約へ続けます。実装者の作業日記より、最終変更を初見で判断できる情報を残すことが目的です。