プルリクエスト説明文の整理

PRの説明文を書く際、多くの人は「何を変えたか」だけを書いてしまいます。しかし、ファイル一覧やdiffはすでに画面上に表示されています。レビュアーが本当に知りたいのは「なぜこのアプローチを選んだのか」であり、それがないとレビューは「これ、なぜこうしたのですか？」という質問から始まり、余計な時間がかかってしまいます。

役割を「レビュアーの時間を節約するエンジニア」としたのは、文章量を適切にコントロールするためです。指定しないと変更ファイルごとに1段落ずつ説明するような長文が生成され、誰も最後まで読まなくなってしまいます。文脈の「背景を知らず、今日初めて見る」という一文は、社内特有の略語や前提の省略を防ぎます。

形式の5つの小見出しがこのプロンプトの骨組みです。特に「特に見てほしいポイント」と「今回は対応していないこと」が重要です。前者はレビューの焦点を絞り、後者は「これはなぜ直していないの？」という手戻りの質問を未然に防ぎます。小見出しごとに行数を指定しているのも同じ理由です。

「でっち上げないでください」という指示は、ChatGPTでPull Requestの説明を作る際に特に必要です。「パフォーマンスが〇％向上した」や関連Issue番号といった、それらしい内容が勝手に追加されがちで、そのまま投稿するとレビュアーが事実だと誤認してしまいます。代わりに「作成者への確認事項」という枠を設けることで、不明点を推測で埋めずにそこへ逃がすようにしています。

確認手順を変数として受け取り前方に配置したのは、レビュアーが最も気にするのが「これ実際に動かしてみた？」だからです。何をどう確認したかが1行あるだけで、レビュアーが同じ手順をなぞったり、漏れているテストケースを指摘したりしやすくなります。

ファイル名を1行ずつ説明しただけのリストが出力されます。読んでもdiffを見ているのと大差がなく、背景がわからないためレビュアーは結局チャットで質問する羽目になります。どこを重点的に見るべきかも不明なため、レビューが誤字脱字の指摘だけで終わったり、中身を見ずにApproveボタンだけが押されたりします。