はじめに
こんにちは！
Webエンジニアの矢島と申します。
エンジニアとして働く中で、コードを書くことと同じくらい、あるいはそれ以上に重要なのが「プルリクエスト（PR）を作成し、レビューしてもらう」というプロセスでしょう。
PRは単なるコードの提出場所ではなく、チームメンバーとのコミュニケーションの場でもあります。
雑に作ってしまうと、レビュアーの時間を奪うだけでなく、バグや手戻りの原因になってしまいます。
私も日々の業務でPRを作成していますが、最近になって
「レビューしやすいPRですね」
「見やすくて助かります」
といった嬉しい言葉をいただくことが増えました。
そこで今回は、私が日々の開発でPR作成時に意識している7つのことをまとめました。
ひとつでも参考になるポイントがあれば嬉しいです！
結論
先に結論をお伝えします。
私がPR作成時に意識しているのは、以下の7つです。
1. サイズを小さく保つ（500行までを目安に）
2. 変更点を箇条書きにする
3. 動作確認の動画・画像を添付する
4. 「やらないこと」を明記する
5. 仕様を記載する
6. 悩んだこと・相談事項を素直に書く
7. 過去に指摘されたことは繰り返さない
ここからは、上記内容について詳細にお伝えしていきます！
1. サイズを小さく保つ（500行までを目安に）
PRのサイズ（変更行数）は、レビューの質と速度に直結します。
私は、PRのサイズはできるだけ小さくするようにしています！
具体的には、だいたい変更行数は50行〜300行までを目指しつつ、どんなに詰め込んでも500行までに収まるようにしています！
（あまり小さすぎると今度はPRの数が増えすぎるので、50〜300行を目安にしています）
なぜサイズを小さく保っているかというと、500行・1,000行という巨大なPRは、見るだけでレビュアーの負荷を高めてしまい、結果的にレビューの質を落としてしまうためです。
（自分がレビュアーだったら、500行を超えるPRをじっくり見るのはちょっと大変かも……）
サイズを小さく保つことで、適切にレビューをしてもらうことができ、コードを質を上げることができています！
変更行数が500行を超えそうになったら、チケットを分割しています。
API実装の例
例えば1つのAPI実装であっても、「機能の実装」と「リファクタリング」を分けることがあります。
❌ NG：1つのPRですべてを実装する
-
PRの内容:
feat: ユーザー登録APIの実装 - やったこと: コントローラー作成、バリデーション、DB保存処理、そしてドメインモデルやValue Objectまで、すべてを1つのPRで実装
たぶんこの内容だと500行を超えそうですよね。
✅ OK：フェーズを分けてPRを出す
「機能の実装」と「リファクタリング」の2段階にPRを分割します。
（分割内容に合わせてチケットも分けています）
PR①：最低限の実装とテスト
- 目的: まずは仕様通りに動く機能を作ります
-
内容:
- Controllerに処理がベタ書きされていてもOK
- 正常系・異常系のテストコードを書き、CIを通す
- レビュアー視点: 「要件を満たしているか？」「バグがないか？」に集中できます
注意
PRの説明文に「このPRでは最低限の実装とテストを実装しました。リファクタリングは別PRで実施します」と書いておくと、レビュアーの方に意図が伝わりやすいです。
PR②：リファクタリング
- 目的: システムのアーキテクチャに沿って、適切な実装にリファクタリングします
-
内容:
- PR①のコードを整理
- ロジックを
DomainクラスやValue Objectへ移動・抽出する - アーキテクチャに沿って、Service層やRepository層に処理を移動する
- テストはPR①で完成しているため、デグレを恐れずに作業できます
- レビュアー視点: 「設計は適切か？」「命名はわかりやすいか？」に集中できます
このように分割することで、それぞれのPRの焦点が絞られ、結果としてレビュー負荷を減らしてコードの質を高めることができます。
2. 変更点を箇条書きにする
PRの説明文の内容が不足していると、レビュアーが仕様や実装の意図を把握できなくなり、レビュー負荷が上がってしまうと考えています。
そこで私は、変更点を箇条書きにすることでレビュー負荷を下げています。
API実装の例
PRの説明文に、以下のように「変更1.」「変更2.」といった見出しを設けて、変更点を箇条書きにしています。
見出しにすることで、他に追記事項などがあった場合も見出しごとに記載することができます。
（例: SwaggerのIF定義、ロジックの仕様、アーキテクチャなど）
3. 動作確認の動画・画像を添付する
説明文に仕様などを記載するよりも「実際の動き」を見せるのが最もわかりやすいです。
動きを見てもらうことで「このPRで何をしたいのか？」を理解してもらい、レビューの質を上げることが狙いです！
「百聞は一見にしかず」はコードレビューでも同じですね。
そこで私は、PRの説明文にスクリーンショットや画面収録動画を添付しています。
API実装の例
↓このように、エンドポイントにリクエストした際の動画を添付しています。
4. 「やらないこと」を明記する
もしなにかあえて「このPRではやらない」「対応しない」ことがあれば、説明文に明記しています。
このやらないことを前もって明記しておくことで、PR作成者（私）の意図を明らかにできるので、レビュアーからの不要な質問・指摘を減らすことができ、結果的にレビューの質が上がると考えています！
例
5. 仕様を記載する
コードの How（どう実装したか）は差分を見ればわかりますが、Why（なぜ実装したか）はコードからは読み取れません。
チーム外のレビュアーも適切にレビューができるよう、仕様をできるだけ詳しく記載します。
6. 悩んだこと・相談事項を素直に書く
PRは「完璧な回答」を提出する場ではなく、チームでより良いコードにするための場だと考えています。
自分の実装に自信がない部分や、設計上のトレードオフで迷った点は、隠さずに相談します。
私はよく「悩んだ点1. 〇〇」のような形で記載して、意見を求めています。
7. 過去に指摘されたことは繰り返さない
同じ指摘を何度も受けることは、レビュアーの時間を浪費させるだけでなく、エンジニアとしての信頼を損なうと考えています。
そこで私は、過去にレビューで指摘してもらった内容はNotionに蓄積しておき、レビュー依頼の前に読み直しています！
例（過去に指摘された内容）
- クラス名は単数形にする
- ユニットテストは他のクラスの実装に依存しないよう実装する
- Repositoryクラスにロジックは入れない
- など
まとめ
今回は、私がPR作成時に意識している7つのことについてお伝えしました。
結論、以下の7つを意識しています。
- サイズを小さく保つ（500行までを目安に）
- 変更点を箇条書きにする
- 動作確認の動画・画像を添付する
- 「やらないこと」を明記する
- 仕様を記載する
- 悩んだこと・相談事項を素直に書く
- 過去に指摘されたことは繰り返さない
今回の内容は以上です。
もしみなさまの業務に活かせそうな箇所があれば、ぜひ取り入れていただけたら嬉しいです！
また、この記事が少しでも参考になったら、ぜひ「いいね」を押してもらえると嬉しいです！
ここまで読んでいただきありがとうございました！