【失敗３例】『君のプルリク、見やすいね！』と言われる、超具体的なPR作成ガイド【レビュー対応３ステップ】

Last updated at 2025-11-02Posted at 2025-11-02

🔰 はじめに：なぜ「伝わるプルリクエスト」が重要なのか？

突然ですが、**「プルリクエスト（Pull Request, PR）」**を作る時、こんな不安はありませんか？

「初めてのプルリク、何を書いていいか全然わからない…」
「こんなPRでレビュー依頼したら、先輩に怒られないだろうか…」
「レビューで『全部やり直して』とか言われたらどうしよう…」

その気持ち、痛いほどわかります。あなたのために、この記事を書きました。
この記事でお伝えしたいのは、**「チーム開発をスムーズにするためのPR」「レビュアーに感謝されるPR」**の作り方です。

Web系ベンチャーやスタートアップのようなスピード感が求められる現場では、開発チーム全体の生産性が何より重要です。
「伝わるPR」は、レビュアーの確認時間を劇的に短縮し、レビューの質を高め、バグの早期発見につながります。結果として、チーム全体の開発スピードを上げることに直結するのです。

技術力に自信がなくても大丈夫です。
「いかにレビュアーの手間を省くか」という**「思いやり」と「想像力」**さえあれば、あなたはプルリクエストを通じてチームに大きく貢献できます。

この記事では、現場で実践しやすく、かつ先輩エンジニアから「レビューしやすい！」と褒めてもらえる、今すぐ使える超具体的なテクニックだけを厳選してご紹介します。

📜 この記事の目次

そもそもプルリクエスト（PR）って何だっけ？
PR作成前の「3つの下ごしらえ」
【最重要】爆速レビューを生む「PR本文」の書き方テンプレート
レビュアーの時間を奪わない「セルフチェック」のすすめ
よくある失敗と対策（アンチパターン）
レビューをもらったら（素早いレスポンスが信頼を生む）
まとめ：小さな積み重ねが、大きな信頼に繋がる

1. そもそもプルリクエスト（PR）って何だっけ？

もう知ってるよ！という方は読み飛ばしてOKです。

超平易に言えば、プルリクエスト（PR）とは：

自分が書いたコード（変更）を、チームのメインのコード（main や master ブランチ）に取り込んでもらうための「お願い＆提案書」

です。

一人で開発しているなら不要ですが、チーム開発では必須のプロセスです。
PRを送る（＝作成する）主な目的は2つあります。

レビュー（Review）:
チームの他のメンバー（レビュアー）に、「こんな変更をしたんだけど、問題ないかチェックしてください」とお願いすること。
マージ（Merge）:
レビューで「OK！（LGTM! ※）」をもらったら、その変更をメインのコードに正式に合体させること。
(※ LGTM = Looks Good To Me の略。「良さそうですね！」という意味で使われるスタンプやコメント)

なぜPRが必要なのでしょうか？
それは、「チームの資産」であるコードの品質を守り、開発の透明性を高めるためです。

品質の担保: 変なコード（バグ）が紛れ込むのを防ぐ。
知識の共有: 「今、Aさんがこんな機能を作ってるんだな」とチーム全員が把握できる。
合意の形成: 「この実装方法で本当に大丈夫か？」をチームで議論できる。

PRは、単なる「作業依頼」ではありません。
チームで円滑に開発を進めるための、最も重要な「コミュニケーション」の場なのです。

2. PR作成前の「3つの下ごしらえ」

良いPRは、コードを書き終わった瞬間から始まるのではありません。**PRを作る前段階の「下ごしらえ」**が非常に重要です。

下ごしらえ1：ブランチ名は「分かりやすく」

まず、変更作業を始めるために作ったブランチの名前です。

悪い例 👎: fix, update, feature, test, abc
良い例 👍: fix/login-validation-error, feat/add-user-profile-page, refactor/optimize-query

なぜか？
レビュアーは毎日、何本ものブランチ（変更）を見ています。ブランチ名が「何についての変更か」を具体的に示しているだけで、レビュアーは「ああ、ログイン周りの修正なんだな」と心の準備ができます。

Slackの通知などで TaroYamada pushed new branch feat/add-user-profile-page と流れるだけで、チームへの情報共有にもなります。
fix や update では、誰も何も分かりません。

現場のヒント:
多くの現場では feat/ (機能追加), fix/ (バグ修正), refactor/ (リファクタリング) のように、**プレフィックス（接頭辞）**を付けるルールがあります。チームのルールを確認してみましょう。

下ごしらえ2：コミットメッセージは「こまめに」「具体的に」

PRは「コミット（変更履歴）」の集まりです。この「コミット」が雑だと、PR全体も雑に見えてしまいます。

悪い例 👎:
1つのコミットが「いろいろ修正」という名前で、50ファイルくらい変更されている。（通称：モンスターコミット）
良い例 👍:
1. [feat] ユーザープロフィール編集画面の骨格を作成
2. [feat] プロフィール更新（update）のアクションを追加
3. [fix] バリデーションエラー時の表示崩れを修正
4. [refactor] 共通ロジックをUserモデルに移動

なぜか？
レビュアーは、PR全体の差分（Files changedタブ）を見るだけでなく、「コミット履歴（Commitsタブ）」を1つずつ追って、**「どういう思考順序でこの変更が行われたか」**を確認することがあります。

コミットが「意味のある単位」でこまめに分けられていると、レビュアーは変更の意図を非常に追いやすくなります。もしレビューで「この修正だけ取り消したい」となった時も、コミットが分かれていれば簡単です。

現場のヒント:
「1つのPRには、1つの関心事（目的）」を心がけましょう。
例えば、「機能追加」と「ついでに見つけた別機能のバグ修正」は、コミットを分けるだけでなく、PR自体を2つに分けるのがベストです。これを守るだけで「仕事が丁寧な人だ」と評価されます。

下ごしらえ3：pushする前に「ローカルで確認」

これは「思いやり」以前の、**「最低限の責任」**です。

PRを作成する（＝リモートリポジトリに git push する）前に、必ずローカル環境（自分のPC）で以下を確認してください。

ビルドやテストは通るか？
npm run test や bundle exec rspec などのテストコマンドを実行し、全てパス（Green）することを確認します。
Lint（構文チェック）は通るか？
コーディング規約違反の警告が出ていないか確認します。
不要なコードは残っていないか？
console.log("テスト") や binding.pry, var_dump($user) といった、消し忘れのデバッグコードは絶対にNGです。

なぜか？
これらが残ったままPRを出すと、GitHub ActionsなどのCI（自動テスト）がコケます。
レビュアーがレビューしようとPRを開いた瞬間に、CIが真っ赤なエラー（Red）を吐いていると、「うわ、まずCI直すところからか…」と、レビューの意欲が一気に削がれます。

CIをパスさせるのは、レビューを依頼するための最低限のマナーです。

3. 【最重要】爆速レビューを生む「PR本文」の書き方テンプレート

お待たせしました。いよいよPRの「本文（Description）」の書き方です。
ここがあなたの「評価」を決定づけると言っても過言ではありません。

レビュアーは常に忙しいです。
彼らが知りたいのは「何のPRか」「何を見ればいいか」「どうやって動確（動作確認）すればいいか」の3点です。

「よろしくお願いします」だけのPRは、最悪です。
レビュアーは、まず関連するイシュー（チケット）を探し出し、コードを全件読み解き、「これは何をしようとしてるんだ…？」と推理しなければなりません。これほど無駄な時間はありません。

レビューコストを極限まで下げること。それが、駆け出しエンジニアができる最大の組織貢献です。

迷ったら、以下のテンプレートをコピーして使ってください。

究極の「思いやり」PRテンプレート

## 概要 (What)
例：ユーザープロフィールの編集機能を追加しました。

## 関連イシュー (Why)
例：イシュー #123 の対応。
（イシューがない場合は、変更理由を簡潔に書く）

## 変更内容 (How)
* `users_controller.rb` に `edit`, `update` アクションを追加
* プロフィール編集画面 (`edit.html.erb`) を作成
* ルーティング (`routes.rb`) に `/users/:id/edit` を追記

## 影響範囲
例：既存のユーザー一覧画面には影響ありません。

---
## 動作確認の方法
1.  ログイン後、`/users/1/edit` にアクセス
2.  フォームに任意の値を入力して「更新」ボタンを押す
3.  プロフィールが更新されることを確認
4.  （あれば）バリデーションエラー時の動作確認
    * 名前を空にして更新 → 「名前を入力してください」と表示されることを確認

## スクリーンショット (あれば)
**変更前 (Before)**


**変更後 (After)**


## レビューしてほしい観点（特に見てほしいところ）
* `update` アクションのバリデーション処理（`users_controller.rb` L45-L50）について、もっとDRY（簡潔）な書き方があればご教授いただきたいです。
* セキュリティ面（他人のプロフィールを編集できないかなど）で、権限チェックに漏れがないか不安です。重点的に見ていただけると助かります。

## その他 (あれば)
* 参考記事：[Railsチュートリアル第X章 (URL)]
* （今回のPRではスコープ外としたことなど）

テンプレートの「キモ」解説

このテンプレートの肝は、後半の**「動作確認の方法」「スクリーンショット」「レビューしてほしい観点」**の3つです。

動作確認の方法

レビュアーが、あなたのブランチをローカルに落とし（git pull）、サーバーを起動し、ブラウザでポチポチ操作する…という面倒な手順を、あなたが肩代わりするための記述です。
これがあるだけで、レビュアーは「ああ、この手順で確認すればいいのね」と、思考停止でレビューに入れます。

スクリーンショット

UI（見た目）の変更が1ピクセルでもあるなら、スクショは絶対に貼りましょう。
レビュアーは、わざわざローカルで起動しなくても、GitHubの画面上で「ああ、ここのマージンがこう変わったのね」と視覚的に理解できます。

「変更前（Before）」と「変更後（After）」を並べて貼ると、100点満点です。
（動画（GIF）を貼れば、もはや神です）

レビューしてほしい観点

ここが、新人・駆け出しエンジニアにとって最強の武器です。

技術力に自信がないのは当たり前です。それを隠す必要はありません。
むしろ、「どこが不安か」を具体的に言語化することで、レビュアーは「なるほど、そこが不安なんだな。じゃあ重点的に見よう」と、レビューのピントを合わせることができます。

悪い例 👎: 「自信ないので全部見てください」（＝丸投げ。レビュアーが一番困る）
良い例 👍: 「Userモデルのupdate_profileメソッドについて、もっと効率的なクエリがないか不安です。ご意見ください」

「自分はここまで考えた。でも、この部分の最適解が分からないから助けてほしい」という球を投げるのです。
これは「技術力の低さ」のアピールではなく、「課題を特定し、助けを求める」という、チーム開発における超重要なスキルのアピールになります。

4. レビュアーの時間を奪わない「セルフチェック」のすすめ

PRの本文を書き終えたら、[Create pull request] ボタンを押す…その直前に、必ずやってほしいことがあります。
それが**「セルフチェック（自己レビュー）」**です。

PRを作成する画面には、「Files changed（変更ファイル一覧）」タブがあります。
まず、レビュアーが確認するのと同じように、自分自身でこの「Files changed」タブを上から下まで全部見てください。

そして、以下の観点でチェックします。

デバッグコードの消し忘れはないか？
- console.log, print_r, debugger, (S)top! (byebug)
**コメントアウトされた「ゴミコード」**は残っていないか？
- # (古いロジック)
**タイポ（Typo）**はないか？
- 変数名、メソッド名、コメント内の日本語
意図しないファイルが混入していないか？
- .env や config/database.yml （機密情報！）
- node_modules/ や tmp/ （.gitignore に書くべきもの）
**コードフォーマッター（Prettier, RuboCopなど）**をかけ忘れていないか？
- インデントがガタガタ、不要なスペースがある、など。

なぜか？
「あ、すみません、console.log 消し忘れです！」「タイポです！直します！」
…このPRの往復、めちゃくちゃ無駄だと思いませんか？

レビュアーが貴重な時間を使ってコードを読み、見つけた指摘が「デバッグコードの消し忘れ」だった場合、レビュアーはガッカリします。「本質的なロジックのレビューをしたかったのに…」と。

技術力以前の「注意力」で防げるミスは、自分で潰しておく。
これが**「レビューに集中してもらう」ための最高の気配り**です。

現場のヒント:
GitHubには「Draft（下書き）PR」機能があります。
自信がない時は、まずDraft PRとして作成し、セルフチェックが完了したら [Ready for review] ボタンを押す、という運用もオススメです。

5. よくある失敗と対策（アンチパターン）

セルフチェックもOK！いざレビュー依頼！
…の前に、よくある「残念なPR」のアンチパターンと、その対策を知っておきましょう。

失敗1：巨大すぎるPR（モンスターPR）

内容: 変更ファイル数 50、追加/削除行数 +3000 / -2000
問題: レビュアーがPRを開いた瞬間に「うっ…」となり、そっと閉じます。読む気を失うため、レビューが非常に雑になるか、永遠に後回しにされます。結果、バグが大量に混入し、リリース後に大事故が起きます。
対策:
- **「1 PR = 1つの関心事」**を徹底します。
- 機能追加とリファクタリングを絶対に混ぜない。（リファクタリングは別のPRでやる）
- 「ユーザー登録機能」と「ユーザー編集機能」は、別のPRに分ける。
- もし実装が大きくなりそうなら、着手する前に先輩やリーダーに「このタスク、PRを2〜3個に分けて進めたいのですが、どう分割するのが良いですか？」と相談する。この「相談」こそが組織貢献です。

失敗2：CI（自動テスト）が落ちたままレビュー依頼

内容: PRに赤い「✕」マーク（CI failed）が付いているのに、「レビューお願いします！」と依頼する。
問題: 「自分の仕事（コード）に責任を持っていない」と見なされます。「（テストも通せないコードのレビューなんて、できるわけないだろ…）」とレビュアーは呆れます。
対策:
- PRを作成したら、まずCIが通る（緑の「✓」になる）のを待つ。
- CIが落ちたら（赤の「✕」になったら）、他の誰よりも早く最優先で修正する。
- ローカルでは通ったのにCIだけ落ちる場合（環境差異）は、その旨をPRにコメントし、助けを求める。

失敗3：レビューコメントに反論・論破しようとする

内容: レビュアーからの「ここはこうした方が良いのでは？」という指摘に対して、「でも、自分は〜だと思うので」「こっちの方が効率的なので」と感情的に反論する。
問題: チームの雰囲気が最悪になります。レビューは「攻撃」や「粗探し」ではありません。「コードをより良くするための共同作業」です。
対策:
- まず「感謝」する。 「レビューありがとうございます！」「ご指摘ありがとうございます！」
- 指摘の意図が分からないなら、質問する。 「ありがとうございます。〜という理解であってますでしょうか？」
- 納得できない場合も、「相談」ベースで話す。「なるほどです。自分は〜という理由でこう書いたのですが、ご指摘の方法とどちらがチームの今後の方針としてベターでしょうか？」
- （技術力の期待値コントロール）「そう書くべき理由が理解しきれず…！恐れ入りますが、なぜその方が良いか、背景を教えていただくことは可能でしょうか？」と謙虚に学ぶ姿勢を見せる。

6. レビューをもらったら（素早いレスポンスが信頼を生む）

ついにレビューコメントが付きました！
ここからの**「対応速度」と「丁寧さ」**が、あなたの信頼を確立します。

ステップ1：最速でリアクションする

SlackやGitHubの通知に（業務時間内であれば）できるだけ早く気づけるようにしておきましょう。
レビュアーは、レビューのために一度、あなたのPRの「コンテキスト（文脈）」を頭にロードしています。その「熱」が冷めないうちにキャッチボールを始めるのが理想です。

まずは「レビューありがとうございます！今から確認します。」と一報（コメント or Slack）入れるだけでも、レビュアーは「ああ、伝わったな」と安心します。

ステップ2：コメントには全て返信する

もらったコメント（Suggestion）を、絶対に無視しないでください。

修正する場合:
- コードを修正し、git commit & git push します。
- GitHubのコメント欄に「ご指摘ありがとうございます！修正しました。(コミットID: xxxxxxx)」と返信します。
議論したい・質問したい場合:
- （失敗5参照）「ありがとうございます。ここは〜〜ということでしょうか？」とスレッドで質問します。
指摘が妥当で、コード修正が不要な場合（「ここはOKです！」など）:
- 「承知しました！」「ありがとうございます！」と返信します。

GitHubの「Resolve conversation（会話を解決）」ボタンを適切に押すことも忘れずに。
すべてのスレッドが「解決済み」になることで、レビュアーは「ああ、全部対応してくれたんだな」と一目でわかります。

ステップ3：再レビューを依頼する

すべての指摘に対応し、CIも通ったら、PRは「マージ待ち」の状態です。
しかし、レビュアーは他の作業をしているかもしれません。

「全部直しました！」という空気を出すだけでは、マージしてもらえないかもしれません。
必ず、明示的に「再レビュー」を依頼します。

「ご指摘ありがとうございました！
すべて修正（or 回答）完了しました。
お手数ですが、再度レビュー（Approve）をお願いいたします！ 🙏」

この最後のひと押しまでが、PR作成者の責任です。

7. まとめ：小さな積み重ねが、大きな信頼に繋がる

ここまで、本当にたくさんの「コツ」を書いてきました。
「うわ、全部やるの大変そう…」と思ったかもしれません。

大丈夫です。一言でまとめると、これだけです。

プルリクエストは「コード」を投げる場ではなく、「コミュニケーション」の場である。

あなたの目の前にいるレビュアーも、同じチームで働く「人間」です。
その人が、いかにストレスなく、いかに早く、いかに気持ちよくレビュー作業を終えられるか？

その「想像力」と「思いやり」を、PR本文のテンプレートや、スクリーンショット、こまめなコミットといった「形」に落とし込む。
技術力に自信がなくても、この**「レビュー・コミュニケーション能力」**を磨き続けることで、あなたは間違いなくチームから「なくてはならない存在」として信頼されます。

「君のプルリク、見やすくて助かるよ！」

その一言が、あなたのエンジニアとしてのキャリアを支える、何よりの自信になるはずです。
この記事が、あなたの「伝わるPR」ライフの第一歩となれば、これ以上嬉しいことはありません。

最後まで読んでいただき、ありがとうございました！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up