112. PRの説明文 — 何を・なぜ・どう確認したか

PR の説明文は「何を変えたか」「なぜ変えたか」「どう確認したか」の3点セットで書きます。差分を見れば「何を」はある程度分かりますが、「なぜ」はコードに残りません。背景となる課題やチケットへのリンクを書き、動作確認の手順と結果まで添えると、レビュアーは安心して読み始められます。

画面に関わる変更ならスクリーンショットを貼るのが実務の常識です。文章で説明するより一枚の画像のほうが早く正確に伝わり、変更前後を並べれば差も一目瞭然です。さらに「特にこの設計判断を見てほしい」という注目ポイントを冒頭に書いておくと、レビュアーは限られた時間を重要な箇所に使えます。

説明文を書くことには、もう1つ隠れた効果があります。変更内容を言葉にする過程で自分の差分を見直すため、消し忘れの console.log や無関係な変更に自分で気づけるのです。「説明が書きにくい PR は、変更を詰め込みすぎているサイン」という感覚も、書き続けるうちに身につきます。