Pull Requestの説明文は、差分の目的、境界、確認方法、残るリスクをレビュー担当へ渡す案内図です。 レビュー担当は差分を読めても、なぜ変更したか、何を意図的に変えなかったかはコードだけでは分かりません。
なぜ必要か
説明がないPRでは、レビュー担当がIssue、コミット、画面を行き来して目的を推測します。その結果、重要な仕様漏れより命名や整形へ注意が偏ることがあります。説明文に利用者への影響と確認手順があれば、レビューを「コードを読む作業」から「変更が目的を安全に満たすか確かめる作業」へ変えられます。
良い説明文は差分を言い換えるのではなく、差分からは読み取れない判断を補います。
登場人物と対象
作成者、レビュー担当、QA、運用担当、将来履歴を読む保守担当が関わります。対象はソースコードだけでなく、画面差分、API・DB互換性、設定、テスト、リリースと戻し方です。関連Issueを閉じる場合は、受け入れ条件との対応も示します。
作成の流れ
- Issueを一文で要約し、このPRの目的を固定する。
- 利用者から見える変更と内部変更を分ける。
- 対象外と後続PRを明示する。
- 自動・手動確認を再現可能な手順で書く。
- 権限、データ、互換性、性能などのリスクを書く。
- Files changedを自分で読み、説明と差分を一致させる。
テンプレート
## 目的
どの問題を解決するか
## 変更内容
- 利用者から見える変更
- 内部の主な変更
## 変更しないもの
今回の範囲外
## 確認方法
1. 実行手順
2. 期待結果
## リスク・確認してほしい点
互換性、権限、データ、迷った設計
UI変更では変更前後の画像と代替テキスト、API変更ではリクエスト・成功・失敗、DB変更では移行順と後方互換性を追加します。画像だけに依存せず、何が変わったかを文章でも説明します。
PRパターンの比較
| 変更 | 説明で重視すること | 主な証拠 |
|---|---|---|
| 不具合修正 | 再現条件と原因 | 回帰テスト |
| UI変更 | 操作・状態・アクセシビリティ | 前後画像と操作確認 |
| API変更 | 契約と互換性 | リクエスト例・テスト |
| リファクタリング | 動作を変えない境界 | 既存テスト |
| 依存更新 | 変更点と移行影響 | 公式リリースノート |
具体例
「バリデーションを修正」では不足です。「空白だけの課題名が保存される問題を修正し、入力前後の空白を除いた結果が空なら送信せず案内を表示する。既存の有効入力は同じ結果になる」と書けば、境界と非変更範囲が分かります。確認には空文字、空白、有効値、通信失敗を含めます。
確認手順には操作だけでなく、成功時に何が見えるかを書きます。
ケーススタディ：支払期限の表示を直すPR
請求画面で、支払期限が利用者の地域によって一日前に見える不具合を考えます。差分は日付文字列を組み立てる関数とテストの十数行だけです。しかし説明が「日付表示を修正」だけなら、レビュー担当は、保存値が誤っていたのか、表示時の変換だけが誤っていたのか、過去の請求にも影響するのかを推測しなければなりません。
判断は、まず不具合が観測される条件を固定するところから始めます。テスト環境のタイムゾーンを日本時間と協定世界時に切り替え、同じ請求データを開きます。保存された期限が 2026-08-01 のままなのに、協定世界時として日時へ変換した画面だけ 2026-07-31 と表示されるなら、原因と修正範囲を表示層へ絞れます。次に、日付だけを表す値を日時として扱わず、そのまま年月日へ整形する案と、API契約を日時へ変更する案を比べます。後者は利用側すべてへ波及するため、このPRでは前者を選び、APIと保存済みデータは変更しないと明記します。
このPRの失敗条件は「対象画面で正しく見えたか」だけではありません。別タイムゾーンで日付が再びずれる、請求一覧と詳細で表示が一致しない、日時を持つ作成日の表示まで変わる、過去データの移行が必要なのに説明がない、という状態も失敗です。観測方法として、二つのタイムゾーンで境界日の画面を確認し、一覧と詳細の表示を比較し、日付専用関数の自動テスト結果を記録します。スクリーンショットにはテスト用請求番号だけを使い、氏名や住所は含めません。
悪い説明は「タイムゾーンのバグを修正しました。テスト済みです」です。これでは入力、期待結果、非変更範囲が分かりません。良い説明は「日付のみの支払期限を協定世界時の日時へ変換していたため、日本時間以外で前日表示になる問題を修正した。保存形式とAPI契約は変更しない。日本時間と協定世界時で期限が8月1日と表示され、一覧・詳細が一致することを確認した。作成日時は従来どおり時刻変換する」と書きます。レビュー担当は説明を読んだ時点で、日付と日時の境界、確認すべき画面、回帰の候補を把握できます。
説明文を完成させる判断手順
ケースが違っても、最初に「誰の、どの操作で、何が期待と違うか」を一文にします。次に、観測した事実と推測を分け、原因を裏づけるテストやログを示します。その後、採用した修正と見送った修正の境界を決め、受け入れ条件を正常系、境界、失敗系へ分けます。最後に、各条件へ自動テスト、手動操作、画面画像、メトリクスなど適切な証拠を対応させます。
説明を書き終えたら、差分に存在しない効果を主張していないか、確認していない環境を「確認済み」としていないかを点検します。原因がまだ仮説なら断定せず、「この入力で再現し、この変更後は再現しない」と観測可能な範囲で書きます。これにより、説明文が成果の宣伝ではなく、レビュー可能な検証記録になります。
差分を読む順番を案内する
大きめのPRでは、型・API契約、実装、テストの順など、理解しやすい順番を書きます。
自分で先に確認する
PR作成後にFiles changedを読み、不要ファイル、デバッグログ、秘密情報、意図しない整形を確認します。
生成物やロックファイルが変わった場合は、その理由を確認します。大規模な整形と機能変更が混ざっていれば、履歴を壊さない範囲で分割を検討します。レビュー前にCI結果を確認し、失敗を既知として出す場合は理由と対応予定を書きます。
よくある誤解
コミット一覧を貼るだけでは説明になりません。Draft PRも説明不要ではなく、未完了点と相談したい判断を書けば早期レビューに使えます。また、PRが小さければ背景不要というわけではありません。数行の権限変更は影響が大きいことがあります。
注意とベストプラクティス
- トークン、Cookie、顧客データをログや画像へ載せない。
- チェックしていない項目をチェック済みにしない。
- 自動生成文を差分と照合し、誤った説明を残さない。
- 互換性を壊す変更には移行順と利用側への影響を書く。
- レビューしてほしい箇所をファイル・論点単位で示す。
デバッグ・確認方法
説明文だけを読んだ第三者が、目的、対象外、確認方法を言えるか確認します。関連Issueの条件とテストを照合し、リンク、コマンド、画面手順を実際に試します。PRの差分統計ではなくFiles changedを読み、意図しないファイルがないか確認します。
実践演習：レビューを開始できるか試す
差分を見ていない人へ説明文だけを渡し、「利用者に何が変わるか」「対象外は何か」「最初にどのファイルを見るか」「どう確認するか」「注意するリスクは何か」を答えてもらいます。答えられない項目は説明へ追加します。
確認手順はクリーンな状態から実行します。既存データやログイン状態に依存するなら前提を書き、失敗状態を作る安全な方法も示します。DB更新や外部送信がある場合、検証環境とテストデータを明記します。
最後にIssueの完了条件を一つずつPRの変更またはテストへ対応させます。対応しない条件は対象外として合意するか、PRを未完了として扱います。複数の独立目的が見つかったら分割を検討します。
マージ後にも役立つ説明
PR説明はレビュー中だけでなく、将来 git blame や検索から変更理由を調べる入口になります。そのため、「今日」「この前」のような相対表現を避け、Issue、設計記録、移行手順へ恒久的なリンクを付けます。外部サービスの一時ログだけに根拠を置かないようにします。
レビューで方針が変わった場合は、重要な結論をコメントだけに残さず説明文へ反映します。マージ時点の本文が最終的な差分と一致していれば、後から変更理由を追いやすくなります。
まとめ
レビューしやすいPRは、目的、利用者への変化、非変更範囲、再現可能な確認、残るリスクを差分の前に共有します。 自分で差分を読み直し、説明と実装を一致させてからレビューへ渡します。
