レビューしやすい Pull Request の書き方: 小さな PR、良い説明、Stacked PR でレビュアーを速くする

「良い PR はレビュアーへの贈り物。悪い PR はレビュアーに押し付ける宿題。」

プロローグ — 作成者がレビュー遅延をコントロールする

「なぜ自分の PR はいつもマージが遅いのか?」多くのエンジニアはこの答えをレビュアーに求めます。レビュアーが忙しい、優先度が低い、チームが遅い。一部は事実です。しかし最大の変数は別の場所にあります。PR のレビュー遅延 (review latency) は、ほとんど作成者が決めています。

レビュアーが PR を開いたとき、目にするのが 800 行の diff に説明 1 行 (「機能追加」) なら、その PR は「後で」に回されます。レビュアーも人間で、大きな認知負荷を要求する作業は自然に後ろに押しやられます。逆に 120 行の diff に「何を・なぜ・どう検証したか」が明確に書かれていれば、レビュアーはコーヒーを待つ 5 分でそれを終えます。

この記事は コードレビューのやり方 についての記事ではありません。それはレビュアーの技術で、レビューエチケット・マージキュー・レビュー優先順位は受け取る側の話です。この記事は PR の書き方 — 作成者がレビュアーの仕事を簡単で速くするためにできるすべて、についての記事です。

良い PR は交渉ではなく配慮

PR を「自分のコードを通す関門」と見る人と、「レビュアーと一緒にコードを検証する場」と見る人は、まったく違う PR を作ります。前者は diff を大きくし、説明を短く書き、質問に防御的に答えます。後者は diff を小さく切り、十分なコンテキストを書き、レビュアーにどこから見るべきかを案内します。

配慮は抽象的な美徳ではありません。測定可能な行動です — PR を小さく切ること、説明に検証方法を書くこと、フォーマット変更を分離すること、セルフレビューを先に回すこと。この記事はその行動のリストです。

この記事で扱う内容:

1章 · 小さな PR が勝つ理由

PR 作成のすべてのアドバイスの中で、最も効果が大きい 1 つを選ぶなら 小さくしろ です。他のすべての技術はこの上に積み重なります。

1.1 レビュー品質は PR サイズに反比例する

レビュアーの集中力は無限ではありません。diff が大きくなるほど、1 行あたりに注ぐ注意力は減ります。だから大きな PR では逆説が生まれます — 変更が多いほど、各変更は検証されなくなります。

500 行の PR に付いた「LGTM」はレビューではなく降参です。作成者が本当に望むのが検証なら、検証可能なサイズで渡さなければなりません。

1.2 認知の崖

PR サイズとレビュー品質の関係は線形ではありません。ある点を超えると急激に落ちる 崖 (cliff) があります。正確な数字はチームとコードベースによって違いますが、経験的にその崖はおおよそ 200 〜 400 行の間にあります。

崖の下では、レビュアーは PR 全体を頭の中に一度に収められます。崖の上ではそれが不可能になり、レビュアーは PR を「断片で」読み始めます。断片で読むと、断片どうしの相互作用 — 最もバグが隠れる場所 — を見落とします。

目標はシンプルです。すべての PR を崖の下に置くこと。 作業が大きければ作業を切るのであって、PR を大きくするのではありません。

1.3 小さな PR の複利効果

小さな PR はレビュー品質を上げるだけではありません。

• 速いフィードバック — 小さな PR は速くレビューされ、速くマージされ、速くデプロイされます。間違った方向なら早く気づきます。
• 簡単なロールバック — 問題が起きたとき、戻す単位が小さい。800 行のどこが問題かを探す代わりに、80 行の PR 1 つを戻します。
• 少ないコンフリクト — 小さな PR は長く生きないので、main から離れる時間がありません。リベース地獄が減ります。
• 明確な履歴 — git log が「機能追加」のような巨大コミットではなく、意味単位の変更記録になります。

小さくすることはコストではなく投資です。切るのにかかる 10 分が、大きな PR が作る数日の遅延を防ぎます。

2章 · 1 PR = 1 アイデア

小さくすることと同じくらい重要なのが 1 つだけ入れること です。サイズが小さくても、2 つの無関係な変更が混ざるとレビューは難しくなります。

2.1 「混在 PR 禁止」ルール

最も一般的で最も有害なアンチパターンは リファクタリングと振る舞いの変更を 1 つの PR に混ぜること です。

レビュアーが変更された関数を見ます。名前が変わり、位置が移動し、インデントが違い、そしてその中で if 条件が 1 つ変わっています。レビュアーはもう質問できません — 「この振る舞いの変更は意図されたものか、それともリファクタリング中のミスか?」ノイズがシグナルを覆いました。

ルールはシンプルです。

1 つの PR は 1 つのアイデアだけを入れる。リファクタリングと振る舞いの変更を絶対に同じ PR に入れない。

順序も決まっています。リファクタリングが先、振る舞いの変更が後。 リファクタリング PR は「振る舞いは同一、構造のみ変更」と宣言できるので、レビュアーは速く流し見できます。その後、振る舞いの変更 PR がきれいな土台の上に小さな diff で入ってきます。

2.2 何が「1 つのアイデア」か

最後の行が核心です。「1 つのアイデア」は「1 つのファイル」でも「1 つのコミット」でもありません。機能とそのテストは 同じアイデア なので一緒に行きます。一方、機能と無関係なタイポは小さくても 別のアイデア なので分離します。

2.3 「ついでに」は警告音

PR を作っていると誘惑が来ます — 「このファイルを見るついでに、あの死んだコードも消そう」「ここに来たついでに、あの変数名も直そう」。この「ついでに」こそが、混在 PR が生まれる瞬間です。

原則: 「ついでに」が浮かんだら止まり、それを別の PR またはチケットにする。 良い発見を捨てろという話ではありません。その発見を 別のレビュー可能な単位 に移せという話です。

3章 · PR 説明 — 最も重要な成果物

PR で最もよく使われ、最も手間をかけられないのが 説明 (description) です。多くの作成者は diff に 2 時間かけ、説明に 20 秒かけます。これは逆です。

3.1 説明は diff が答えられないものを答える

diff は 何が (what) 変わったかを見せます。diff が決して見せられないのは なぜ (why) です。そしてレビューの中心的な質問はほぼ常に「なぜ」です — 「なぜこうしたか」「なぜ別の方法ではないか」「なぜ今か」。

説明がなければレビュアーは「なぜ」を推測しなければならず、推測は外れ、外れた推測の上に付いたレビューコメントは作成者とレビュアー両方の時間を燃やします。

3.2 良い PR 説明の 6 つの要素

この 6 つのうち、「スコープ外」 が最もよく抜け、最も効果が大きいです。「この PR は X をやりません — それは後続 PR です」という 1 行が、レビュアーが書こうとしたコメント 5 つを先に防ぎます。

3.3 レビュアーのための読みガイド

大きな変更が避けられないとき (例: 自動生成ファイルが含まれるとき)、説明に 読む順序 を書きます。

## レビューガイド
- 核心ロジックは `src/auth/session.ts` です。ここから見てください。
- `src/generated/*` は codegen の成果物です。流し見でかまいません。
- `package-lock.json` の変更は依存関係追加の副作用です。

この 1 ブロックが「diff が 600 行」という事実の体感的な重さを「実際に見るべきは 80 行」に変えます。

3.4 コピーして使う PR 説明テンプレート

以下はそのままコピーして .github/pull_request_template.md として使うか、チーム wiki に固定しておけるテンプレートです。外側のフェンスが 4 つのバッククォートなのは、内側にコードブロックと ## ヘッダーが入っているからです。

## 何 (What)
{この PR が変えるものを 1〜2 文で}

## なぜ (Why)
{この変更が必要な理由。関連 issue: #123}

## どう (How)
{取ったアプローチとその理由。検討して捨てた代替案があれば 1 行}

## 検証方法 (How to verify)
- [ ] {レビュアーがたどれる確認ステップ}
- [ ] {追加した/修正したテスト}
- [ ] {手動確認の手順 — あれば}

```bash
# 再現/検証コマンド — あれば
npm test -- src/auth
```

## スコープ外 (Out of scope)
- {今回やらないこと — そしてどこで扱うか}

## スクリーンショット (UI 変更時)
| 変更前 | 変更後 |
| --- | --- |
| {img} | {img} |

## レビューガイド (diff が大きいとき)
- {どこから見ればよいか}
- {流し見でよいファイル}

すべての欄を埋める必要はありません。UI 変更がなければスクリーンショット欄は消します。しかし 何・なぜ・検証 の 3 欄はどんな PR にも残します。この 3 欄がレビュー遅延の 90% を減らします。

3.5 タイトルも説明である

PR タイトルは git log に永遠に残ります。「fix」「update」「wip」のようなタイトルは 6 ヶ月後に何の情報も与えません。

• 悪い: update
• 悪い: バグ修正
• 良い: auth: セッション期限切れ時のトークン自動更新を追加
• 良い: fix: 空のカートで購入ボタンを無効化

ルール: タイトルは「この PR がマージされると何が変わるか」を 1 行で言う。 プレフィックス (auth:, fix:) で領域と種類をシグナルするとさらに良いです。

4章 · 読める diff の作り方 — コミット衛生

PR を小さく、1 アイデアにしても、その中のコミットがめちゃくちゃならレビューは依然として難しい。diff は 読まれるように 構成されなければなりません。

4.1 論理的コミット

レビュアーは PR を 2 つの方法で見ます — diff 全体を一度に、またはコミットを 1 つずつ。後者が可能になるには、コミットが 論理的単位 でなければなりません。

良い履歴ではレビュアーはコミットを 1 つずつたどり、「この変更がなぜこの順序で起きたか」を理解できます。各コミットはそれ自体でビルド・テストを通過するのが理想です。

4.2 フォーマット変更は別に

自動フォーマッター (Prettier, gofmt, black など) を回すと、意味のない行が diff を埋め尽くします。これらの行が本物の変更を覆います。

原則: フォーマット・名前変更のような機械的変更は別コミット、できれば別 PR に分離する。 「ファイル全体のフォーマット」コミット 1 つは、レビュアーが git diff -w (空白無視) で 1 秒で流し見できます。しかしそれが振る舞いの変更と同じコミットに混ざると、レビュアーは 1 行ずつ見なければなりません。

4.3 レビュー前の履歴整理

PR を上げる前に、作業中に積もった wip / fix / oops コミットを整理します。

# 作業ブランチで: 直近 5 コミットを論理単位に再構成
git rebase -i HEAD~5

# または全部まとめて論理的に切り直す
git reset --soft main
git add -p   # 意味単位で選んで入れる

注意: すでにレビューが始まった PR では、軽率に履歴を作り直しません (4.3 後半と 7章参照)。整理は 最初のレビュー依頼前に 終えるのが原則です。

4.4 1 行の無関係な変更を混ぜない

diff に import の順序だけ変わった行、使われていない空白が消えた行が混ざっていると、レビュアーは毎回止まって「これは意図されたものか?」を判断しなければなりません。エディタが自動で作った変更は、コミット前に git add -p でふるい落とします。

5章 · Stacked PR / stacked diff

作業を小さく切りたいのに変更どうしが互いに依存することがあります。PR 2 が PR 1 のコードの上でしか動かない場合です。このとき Stacked PR が答えです。

5.1 Stacked PR とは

Stacked PR は PR を一列に積むこと です。各 PR は main ではなく すぐ下の PR のブランチ をベースにします。

main
 └─ PR 1: auth 型を追加          (base: main)
     └─ PR 2: トークン検証ロジック   (base: PR 1)
         └─ PR 3: 自動更新 UI を接続  (base: PR 2)

レビュアーは PR 1 から順に見ます。各 PR は小さく、1 アイデアだけを入れ、diff は すぐ下の PR との差分だけ を見せます。800 行の単一 PR が 200 行の PR 4 つになります。

5.2 いつ Stack を使うか

Stack は 依存関係があるときだけ 使います。独立した変更をわざわざ積むと、下の PR が止まったとき上の PR も一緒に止まります。

5.3 Stack 運用の現実

Stack の最大のコストは ベース PR が変わると上のすべての PR をリベースしなければならないこと です。

# PR 1 がレビュー反映で変わった → PR 2 を PR 1 の上に再リベース
git checkout pr-2-branch
git rebase pr-1-branch

# Stack 全体の更新はツールの助けを借りるほうがよい
# (Graphite, Sapling, spr など Stack 専用ツール)

手で Stack を管理するとリベースがすぐ地獄になります。Stack をよく使うチームは Stack 専用ツール (Graphite, Sapling, spr, ghstack など) の導入がほぼ必須です。ツールが Stack 全体のリベース・再提出を一度に処理してくれます。

5.4 Stack が使えないときの次善策

Stack ツールがない、またはチームが Stack に慣れていない場合、次善策は 1 つの PR の中で論理的コミットでステップを分けること です (4.1 参照)。レビュアーに「コミット単位で見てください」と説明に書きます。Stack ほどきれいではありませんが、巨大な単一 diff よりはるかに良いです。

6章 · レビュー依頼前のセルフレビュー

レビュー依頼ボタンを押す前にやるべきことが 1 つあります。自分の PR をレビュアーの目で一度見ること。

6.1 なぜセルフレビューが効くのか

作業中はコードを「書く人」の視点に閉じ込められています。PR を上げて diff 画面で見直すと 視点が変わります。 エディタでは見えなかったものが diff ビューで見えます — 置き忘れた console.log、コメントアウトしたコード、デバッグ用のハードコード、消していない TODO、抜けたエラー処理。

レビュアーがこれを捕まえてくれることを期待してはいけません。それはレビュアーの注意力を 些細なもの に使わせ、本来 設計 を見る余力を奪います。

6.2 セルフレビューチェックリスト

レビュー依頼前に、GitHub/GitLab の「Files changed」タブを開いて 1 行ずつ見ます。

• デバッグの痕跡がない (console.log, print, コメントアウトしたコード, ハードコードされた値)
• 無関係な変更が混ざっていない (フォーマット, import 順序, 偶然の空白)
• すべての新しい分岐にテストがある
• エラー・エッジケースが処理されている (空の値, null, 失敗パス)
• PR 説明の「検証」欄を自分が実際にたどれる
• diff が崖の下か — でなければ切れるか
• コミット履歴が論理的か
• レビュアーが最初に出会う行が最も重要な行か

最後の項目が微妙です。diff の中で 最も重要な変更が最もよく見えるように ファイル順序やコミット順序を調整できます。

6.3 セルフレビューは時間を節約する

セルフレビューに 5 分を使えば、レビューの往復が 1 回減ります。レビューの往復 1 回は通常 半日から 1 日 です (レビュアーが再び時間を取るまでの待機を含む)。5 分対半日。これより利回りの高い投資はまれです。

7章 · レビューフィードバックへの良い返し方

PR を上げるとコメントが付きます。ここで作成者の態度が、次の PR のレビュー速度まで決めます。

7.1 すべてのコメントに応答する

レビューコメントは 2 つのどちらかで終わるべきです — 反映したか、反映しなかった理由を説明したか。 無応答で残ったコメントは、レビュアーに「自分の意見が無視された」というシグナルを与えます。

7.2 防御せず理解せよ

レビューコメントを攻撃として受け取ると応答が防御的になります。防御的な応答はレビュアーを疲れさせ、次回その作成者の PR を丁寧に見たくなくさせます。

コメントが間違っているように見えるときでさえ、最初の反応は 「なぜレビュアーはこう見たのか」 です。レビュアーが誤解したなら、その誤解自体が情報です — コードがそう誤読されるほど不明確だという意味だからです。コードを明確に直すか、コメントを追加します。

7.3 レビュー反映コミットをどう積むか

すでにレビューが始まった PR では 新しいコミットで反映する のが基本です。address review feedback のようなコミットを追加すると、レビュアーは「1 回目のレビュー以降に何が変わったか」だけを別に見られます。すでに見た部分を見直す必要がありません。

マージ直前、チーム規約に従ってこれらのコミットを squash できます。核心は レビューが進行中の間は履歴を保存 し、マージ時点で整理 することです。レビュー途中で force-push で履歴を作り直すと、レビュアーが自分のコメントのコンテキストを失います。

8章 · Draft PR と準備完了のシグナル

PR には 2 つの状態があります — 「まだ見ないで」と「もう見て」。この 2 つを明確にシグナルしないとレビュアーの時間が無駄になります。

8.1 Draft PR の用途

Draft PR は「コードは上がったが、まだレビュー依頼ではない」という明示的なシグナルです。使う場合:

• CI を先に回してみたいとき — ビルド・テスト結果だけ先に確認
• 方向への早期フィードバックがほしいとき — 「全体を見ないで、このアプローチが正しいかだけ見てください」と明示
• 作業が進行中だとチームに見せたいとき — 重複作業の防止

Draft の核心は レビュアーの期待を管理すること です。Draft に「方向だけ見てください」と書けば、レビュアーは変数名やテストの抜けを指摘しません — それはまだ見る段階ではないからです。

8.2 「準備完了」を明確にシグナルせよ

Draft を「Ready for review」に切り替えること自体がシグナルです。しかしそれだけでは足りないことがあります。

• Draft で受けた早期フィードバックを反映したら、何を変えたか をコメントで残します。
• レビュー依頼時に 誰に 依頼するかを明確にします — 「誰でも」は通常「誰も」になります。
• PR が他の PR やデプロイに ブロッキング なら、その緊急性を書きます。

8.3 Draft を放置するな

古い Draft PR はノイズです。何日も止まっている Draft は、チームに「この作業は生きているか死んでいるか」を迷わせます。Draft は アクティブな作業 のときだけ開いておき、止まったら閉じるか状態をコメントで残します。

9章 · AI 時代の PR 作成

2026 年、PR 作成の風景が変わりました。コードのかなりの部分を AI エージェントが生成し、PR 説明も AI が下書きできます。しかし核心の原則は変わっていません — むしろより重要になりました。

9.1 AI が得意なこと: 説明の下書きとセルフレビュー

AI は PR 作成の特定の部分で優れています。

• PR 説明の下書き — diff を入力として渡すと「何を・どう」を要約してくれます。ただし 「なぜ」 は人間だけが知っています — AI 下書きの「なぜ」欄は作成者が必ず書き直します。
• セルフレビューの補助 — 「この diff で置き忘れたデバッグコード、抜けたエラー処理、テストのない分岐を見つけて」は AI が得意な作業です。6章のチェックリストを AI に 1 回目として回させられます。
• コミットメッセージの整理 — 論理的コミットに再構成するとき、メッセージの下書きをしてくれます。

9.2 AI ができないこと: 責任とコンテキスト

AI が決して代わりにできないことがあります。

• 「なぜ」の本当のコンテキスト — この変更がどんなビジネス的・技術的決定から出たかは、人間の頭の中だけにあります。
• レビューされていない出力への責任 — PR に上げたコードは、AI が書いたものでも人間が書いたものでも、作成者が保証するコード です。

9.3 絶対にやってはいけないこと: レビューされていないエージェント出力のダンプ

AI 時代の最も有害なアンチパターンはこれです — エージェントが生成したコードを作成者が読みもせずに PR として上げること。

これはレビュアーに「自分が見ていないコードをあなたが見てください」と言うのと同じです。レビューの社会的契約が壊れます。レビュアーは「作成者が一度検証したコード」を検証すると仮定しているのに、その仮定が偽になると、レビュアーは作成者がやるべきだった 1 回目の検証まで背負うことになります。

ルール: AI が生成したコードも、人間が書いたコードとまったく同じ PR の基準を通過しなければならない。 小さく切り、1 アイデアだけを入れ、作成者がセルフレビューを回し、作成者がすべての行を理解して保証する。AI は diff を速く作ってくれるだけで、レビュー可能にする責任 は依然として作成者のものです。

9.4 AI 時代に小さな PR がより重要になった理由

AI はコードを 速く、大量に 作れます。これは小さな PR の原則をより重要にします — 生成速度が速くなるほど、それをレビュー可能な単位に切る規律がなければレビュアーはより速く溺れます。

AI は作成速度を上げただけで、レビューの帯域幅を上げていません。その差を埋めるのが作成者の PR 作成技術です。

エピローグ — 良い PR はレビュアーへの贈り物だ

PR のレビュー遅延は作成者がコントロールします。レビュアーが遅いのではなく、レビュー不可能な PR が遅いのです。小さく切り、1 アイデアだけを入れ、説明に「なぜ」と「検証」を書き、diff を読めるように構成し、上げる前にセルフレビューを回せば — 同じレビュアーが同じコードを何倍も速く承認します。

これはレビュアーへの好意であり、結局は作成者自身のための行動です。速いレビューは速いマージで、速いマージは速いフィードバックで、速いフィードバックは間違った方向を早く捕まえます。良い PR を書く技術は協業スキルであると同時に、自分の作業のサイクルを短くする技術です。

レビュー可能な PR チェックリスト

1. サイズ — diff が認知の崖の下 (おおよそ 200〜400 行未満)
2. 1 アイデア — リファクタリングと振る舞いの変更を混ぜていない
3. 何 — PR 説明が変わったものを 1〜2 文で要約する
4. なぜ — この変更が必要な理由が書かれている (AI 下書きなら人間が書き直した)
5. 検証 — レビュアーがたどれる確認ステップがある
6. スコープ外 — 今回やらないことが明示されている
7. ビジュアル — UI 変更ならスクリーンショットが付いている
8. コミット衛生 — コミットが論理的単位で、フォーマットが分離されている
9. セルフレビュー — 「Files changed」を 1 行ずつ見て、デバッグの痕跡がない
10. シグナル — Draft/準備完了の状態とレビュー対象者が明確

避けるべきアンチパターン

• 巨大 PR — 800 行に「機能追加」1 行。LGTM は降参であってレビューではない
• 混在 PR — リファクタリング + 振る舞いの変更 + タイポが 1 つの diff に。シグナルがノイズに埋もれる
• 「ついでに」 — 無関係な変更をこっそり挟まない。別 PR/チケットに
• 空の説明 — 「なぜ」と「検証」なしに diff だけを投げない
• フォーマット混入 — 自動フォーマッターの結果を振る舞いの変更と同じコミットに混ぜない
• 防御的な応答 — レビューコメントを攻撃として受けない。誤解はコードが不明確だという情報
• レビュー中の force-push — レビューが進行中のときに履歴を作り直さない
• エージェント出力のダンプ — 自分が読んでいない AI コードを PR として上げない

次回予告

次回は 「レビュアーの技術 — 速く、親切で、厳格なコードレビューのやり方」 です。今回が PR を 書く 側の技術だったなら、次回は PR を 読む 側の技術です。何を先に見るか、どのコメントが役立ちどのコメントがノイズか、承認と変更依頼の基準線をどこに置くか — そして AI レビューボットと人間レビュアーの役割をどう分けるかを扱います。

良い PR を書くのにかかる 10 分は、レビューの往復 1 回の半日を防ぎます。その 10 分はレビュアーへの贈り物であり、未来の自分への投資です。