プルリクエストの書き方｜レビューされやすい説明文とテンプレート

よいプルリクエスト（PR）とは、レビューする人が「何を・なぜ・どう確認すればいいか」を、コードを読む前に理解できるPRです。説明文が空のPRや、数千行の変更が1つにまとまったPRは、レビューに時間がかかり、見落としも増えます。

PRのテンプレートを紹介する記事は多くありますが、この記事では、テンプレートに加えて、直す前と後の説明文の例、PRの大きさの目安と分け方、出す前のセルフレビュー、そしてAIで書いたコードを含むPRの出し方まで解説します。

プルリクエストの早見表

タイトルの付け方

一覧で見たときに、PRを開かなくても何の変更かがわかるタイトルにします。コミットメッセージと同じプレフィックス（feat:・fix:・refactor: など）を付けると、チームで揃えやすくなります。

説明文に書く5つの項目

最も大切なのは 1. 目的・背景 です。コードを読めば「何を変えたか」はわかりますが、「なぜそう変えたのか」はコードには書かれていません。ここがあると、レビューする人は「この目的に対して、この変更で十分か」という視点で見られます。

説明文：直す前と後

直す前

CSV出力を追加しました。確認お願いします。

直した後

## 目的
経理チームから、注文一覧を毎月Excelで集計したいという要望があり、
画面の検索結果をCSVでダウンロードできるようにします。（#123）

## 変更内容
- 注文一覧画面に「CSVダウンロード」ボタンを追加
- `GET /api/orders/export` を追加（検索条件は一覧画面と同じ）
- 件数が多い場合に備え、1万件ごとに分けて読み込むように実装

## 確認方法
1. 注文一覧で期間を指定して検索
2. 「CSVダウンロード」を押す
3. Excelで開き、文字化けがなく、検索結果と件数が一致することを確認
- 単体テスト：`OrderCsvExporterTest` を追加（空・1件・1万1件のケース）

## 影響範囲
- 既存の画面・APIの動作に変更はありません
- DBの変更はありません

## レビューしてほしい点
- CSVの文字コードをBOM付きUTF-8にしています（Excelでの文字化け対策）。
  Shift_JISにすべきか、ご意見をいただけると助かります
- 権限のチェックは既存の一覧APIと同じ仕組みを使っています

## 対象外
- 帳票（PDF）の出力は別のPRで対応します（#130）

直した後の説明文なら、レビューする人は目的を理解したうえで、確認の手順どおりに試し、迷った点について意見を返すことができます。

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

リポジトリに .github/pull_request_template.md を置くと、GitHubでPRを作るときに自動で入力されます。

## 目的
<!-- なぜこの変更が必要か。関連するチケット：#番号 -->

## 変更内容
-

## 確認方法
<!-- 動作確認の手順、追加・変更したテスト -->
1.

## 影響範囲
<!-- 影響する機能、DB・設定の変更、リリース時の注意点。なければ「なし」 -->

## スクリーンショット
<!-- 画面の変更がある場合：変更前 / 変更後 -->

## レビューしてほしい点
<!-- 特に見てほしい箇所、迷った箇所 -->

## チェックリスト
- [ ] セルフレビューをした
- [ ] テストを追加・更新し、CIが通っている
- [ ] 不要なログ出力やコメントアウトしたコードを消した
- [ ] 秘密の情報（パスワード、APIキーなど）が含まれていない
- [ ] AIで生成したコードは、内容を理解し、動作を確認した

GitLabでは .gitlab/merge_request_templates/ にファイルを置くと、同じように使えます。

PRの大きさの目安と分け方

PRは小さいほど、早く、正確にレビューされます。GoogleのコードレビューのガイドでもPR（変更）を小さく保つことが勧められており、数百行を超えると、レビューの質が落ちやすくなります。

「リファクタリング」と「機能の追加」を1つのPRに混ぜないのが、特に効果の大きいルールです。動作を変えない変更と、動作を変える変更が混ざると、レビューする人がどこを注意して見ればいいかわからなくなります。

出す前のセルフレビュー

PRを作ったら、レビューを依頼する前に、自分で差分を1回読み直します。

自分で読み直すだけで、レビューで指摘される内容の多くを事前に直せます。レビューする人の時間を、本当に議論が必要な点に使ってもらうための準備です。

スクリーンショットと動画

画面の変更があるPRでは、変更前と変更後のスクリーンショットを並べて付けます。

操作の流れが大切な変更（入力して保存する、など）は、短い動画やGIFにすると、レビューする人がアプリを起動しなくても確認できます。

ドラフトPRを活用する

大きく作り込んでから方向性の違いに気づくより、早めにドラフトで相談する方が、手戻りが小さく済みます。

AIで書いたコードを含むPR

AIのコーディング支援を使うと、短時間で大量のコードができます。PRを出すときは、次の点に気をつけます。

• 自分で理解したコードだけを出す：「AIが書いたので、よくわかりません」という状態のコードは、レビューする人に負担を押し付けることになります
• 確認した範囲を書く：「テストケースはAIで作成し、観点と期待値は自分で確認した」のように、何をどこまで確認したかを書く
• 小さく分ける：AIは一度にたくさん書けるため、PRが大きくなりがちです。目的ごとに分けて出す
• AIに説明文の下書きを作らせるのもあり：差分からPRの説明文の下書きを作らせ、目的や背景は自分で書き足す

レビューコメントへの返し方

コメントには、直したのか、直さないのか、なぜかが伝わるように返します。すべてのコメントに返事をすると、レビューする人が確認しやすくなります。

よくある質問

Q. 説明文を書く時間がもったいないと感じます。 A. 説明文があるとレビューが早く終わり、質問のやり取りも減るため、結果的にマージまでの時間は短くなることが多いです。テンプレートを使えば、書く時間も数分で済みます。

Q. レビューする人が見つからない、なかなか見てもらえません。 A. PRを小さくする、説明文で「どこを見てほしいか」を明確にする、の2つが効果的です。チームで「PRは1営業日以内に一度は見る」などのルールを決めておくのもおすすめです。

Q. マージの方法（マージコミット・スカッシュ・リベース）はどれがいいですか？ A. チームで1つに揃えることが大切です。1つのPRを1つのコミットにまとめたいならスカッシュがよく使われます。

まとめ

• よいPRは、何を・なぜ・どう確認すればいいかがコードを読む前にわかる
• 説明文は 目的・変更内容・確認方法・影響範囲・レビューしてほしい点 の5つ
• 最も大切なのは 「なぜ」（目的・背景）
• PRは小さく。リファクタリングと機能の追加は分ける
• 出す前にセルフレビュー、画面の変更には変更前後のスクリーンショット
• AIで書いたコードは、理解して確認した範囲を書いて出す

株式会社RJCでは、チームで気持ちよく開発するための工夫を、実際のプロジェクトの中で仲間と磨いています。こうした知識を共有しながら、日々学び合っています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。