PRを作成する上で意識していること
はじめに
こんにちは、エンジニアのさきたゆです。
今回は、PR（Pull Request）のやりとり（質問・修正依頼の往復）を減らして、マージまでの時間を短縮するために意識していることを共有します。
最近はAIにPRの作成を任せることも増えましたが、最終的には人間が責任を持つべきです。
あたりまえのことも多いですが、あらためて重要だなと感じたので記事を書きました。
特に「PRの粒度（小ささ）」を軸にしつつ、粒度だけでは解決しきれない部分も含めて、私が普段セットでやっている工夫をまとめています。
背景
チーム開発をしていると、PRを出したあとに以下が起きがちです。
- 変更差分が大きくてレビューが大変
- 変更の意図（Why）が伝わらず質問が発生する
- 考慮漏れが見つかって修正依頼が入り、やりとりが増える
といった理由で、PR上のコミュニケーションが1往復以上発生してマージまで時間がかかることがありました。
「やりとり自体が悪い」というより、往復が増えるとリードタイムが伸びて開発テンポが落ちやすいので、少しでも減らしたいと常々思っていました。
結論
以下の4つを特に意識してPRを作成するようにしてから、以前よりPRのやりとりが少なくなり、結果として開発スピードも上がりました。
- 粒度（PRを小さくする）
- タイトル・説明文を適切にする
- コンテキストが必要な部分に補足を入れる
- セルフレビューを徹底する（＋AIレビューも挟む）
この4つはバラバラのテクニックではなく、
小さくする（粒度） → 伝える（説明） → 迷いを潰す（補足） → 漏れを潰す（セルフレビュー）
という流れで、レビューの往復を減らすためのセットだと思っています。
それぞれについての詳細
1. 粒度（PRを小さくする）
PRの粒度が大きいと、レビュワーは変更を追うだけで大変ですし、レビュイー側も考慮漏れやロジックの不備が混ざりやすくなります。
とにかく認知負荷が上がって、結果的に往復が増えやすいです。
弊社ではPRのルールとして「小さければ小さいほど良い」という価値観が強く、私も強く同意しています。
迷ったら「目的が1つか？」「リファクタと仕様変更が混ざってないか？」を基準に分けています。
具体例：リファクタは先に分ける
機能追加のために既存コードへ手を入れる前にリファクタが必要な場合、私は次のように分けます。
- PR①：リファクタのみ（振る舞いは変えない）
- PR②：機能追加（仕様変更）
こうすると、レビュワーは「何が変わったのか」が見えやすく、ロジックの不備や考慮漏れにも気づきやすくなります。
もちろん自分自身のセルフレビューも楽になり、結果的に手戻りが減ります。
2. タイトル・説明文を適切にする
タイトルは一目見て「何をしたか」がわかるようにします。
説明文にはWhy（なぜ）とWhat（なにを）を必ず書きます。
これは一般的な話ですが、ここをサボると
- 「これって何のための変更？」
- 「他のやり方と比べてなぜこれにしたの？」
みたいな質問が発生しやすく、往復が増えます。
私が使っているPRテンプレ：
- Why：なぜこの変更が必要か（課題・背景）
- What：何を変えたか（変更内容）
- Screenshot：Before/After（UI変更がある場合）
- Notes：レビュワーに特に見てほしい点 / 判断ポイント / 補足説明
他にも参考ドキュメントやチェックリストも添えます。
「レビューで迷う要素」を先に潰すイメージです。
3. コンテキストが必要な部分には補足コメントしているか
コードは変更差分だけを見ると「なぜそうしたのか」が分からないことがあります。
ここが伝わらないと、レビュワーは疑問を持ち、PR上で質問のコミュニケーションが発生しがちです。
例えば、似た用途のカスタムフックがあるのに、あえて別のフックを使った場合。
レビュワーからすると「なぜこっち？」となり、質問が発生します。
そういう往復を減らすために、私は「迷いそうなポイント」には先回りして補足します。
- PR説明に書く：設計判断、比較検討（A案/B案）、背景
- コードに書く：その行の意図がないと読み解けないポイント
補足を入れることで、レビューする側も実装意図を汲み取りやすくなり、結果として往復が減ります。
4. セルフレビューはしっかりしているか（＋AIレビュー）
当たり前ですが、セルフレビューは徹底します。
そして1の話とも繋がるのですが、PRの粒度が小さいほどセルフレビューの負荷が軽くなり、漏れにも気づきやすいです。
また、AIによるレビューも必ず挟むようにしています。
人間のレビューを置き換えるというより、提出前に「見落としを減らす」目的で使っています。
最後に
以上が、私がチーム開発する上で「PRのやりとりを減らして、マージまでを早くする」ために特に意識していることでした。
PRの往復が増える原因はだいたい
- 差分が大きい
- Whyが伝わっていない
- 前提（コンテキスト）の共有不足
- セルフレビュー不足
に集約されやすいと感じています。
だからこそ、私は「粒度を小さくする」ことを軸に、説明・補足・セルフレビューをセットでやるようにしています。
最後まで読んでいただきありがとうございました。
Discussion