レビューアー視点でPRテンプレートを設計する方法

「このPR、どこを見ればいい？」
「仕様変更かバグ修正かも分からない」
「なぜこの処理にしたのか、判断意図が見えない」

これは、コードレビューの現場で頻繁に聞かれる声である。
レビューを正確かつ効率的に行うには、PR（Pull Request）にレビューアーの判断に必要な情報が含まれている必要がある。

そのための鍵が、レビューアー視点で設計されたPRテンプレートである。

本稿では、レビューアーが「どのような情報を必要としているか」から逆算して、PRテンプレートをどのように構成し、どう運用していくかを実務的に整理する。

1. なぜPRテンプレートにレビューアー視点が必要か

PRテンプレートとは単なる提出フォームではない

  • GitHubやGitLabのPR作成時にあらかじめ記入フォーマットを提供するもの
  • プロジェクトにとってのレビュースタート地点
  • 説明が不十分だと、レビューアーは目的・意図・検証ポイントの全てをコードから推測することになり、無駄が生じる

PR説明の質がレビューの質を決定づける

  • コードだけを見ても、意図はわからない
  • テストコードがあっても、「どのパスが重要か」が説明されなければ確認の焦点が定まらない
  • 説明が曖昧なままだと、「LGTM」「OKです」など形だけのレビューで済ませてしまう空気が生まれる

結果：「レビューされるべき観点」が見逃される

  • 設計変更が含まれているのに、それがレビュー対象と認識されない
  • バグ修正に見えて、実は仕様追加だったという認識違い
  • 修正対象外のファイルまでコメントが入る、逆に本命の処理がスルーされる

2. PRテンプレートに含めるべき項目（レビューアー視点の逆算）

レビューアーとして「読みたい情報」とは、主に以下の5観点である。

観点1：変更の目的（Why）

  • なぜこの変更が必要だったのか
  • どの業務背景・設計判断・ユーザー要求に基づくものか
例： 
「受注登録画面でエラーが出る不具合に対処するため。登録直後の入力チェックを補強」

観点2：変更内容の要約（What）

  • 何を追加・変更・削除したか
  • 重要なファイルやロジック単位の構造整理
例： 
- `OrderValidator` に新しい`validatePaymentDeadline()`を追加
- `OrderForm.vue` でバリデーションタイミングを修正

観点3：見てほしい観点（Focus）

  • どの点について判断・指摘してほしいか
  • 設計意図に自信がない、処理方針に揺らぎがある、など明示
例： 
- 入力エラー時の挙動が他画面と統一されているか確認してほしい
- ロジック分離が過剰か、責務の境界を見ていただきたい

観点4：影響範囲・副作用（Impact）

  • 他機能・データ・API・UIに波及する可能性の有無
  • 再実行性、非同期処理の影響、ミス時の復旧方針
例： 
- `OrderService` 配下のユーティリティ変更のため、他画面の受注操作に影響する可能性あり
- DB構造には影響なし

観点5：確認方法（Verification）

  • テスト手法（自動 or 手動）
  • 確認項目とその成功条件
例： 
- 手動確認：受注画面で期日未入力時にバリデーションエラーが表示されること
- 自動テスト：`OrderValidator.test.ts` に正常系と異常系を追加済み

3. PRテンプレートの設計例（レビュワー視点を全面採用）

以下はレビューアー視点で構成したPRテンプレートの例である。

.github/PULL_REQUEST_TEMPLATE.md 

## 1. このPRの目的（Why）
（例）バリデーション強化／UI修正／DBスキーマ変更／不具合修正 など



## 2. 主な変更内容（What）
（例）OrderValidator.ts に期日バリデーション追加／関連ユニットテスト修正 など



## 3. 見てほしい観点（Focus）
（例）ロジック責務の分離具合が過剰でないか／副作用が生じる可能性がないか



## 🧩 4. 影響範囲・副作用（Impact）
（例）受注登録全体に影響／同一サービスを利用する在庫機能に影響あり など



## 🧪 5. 動作確認方法（Verification）
- [ ] 自動テスト（pass）
- [ ] 手動操作（記述）

→ 各セクションに「例示」や「補足文」を添えることで、書く人の負荷を軽減し、記入率を上げる

4. チームへの導入方法と運用改善の流れ

ステップ1：まずは「レビュワーがつらい」現状を共有する

PRテンプレートの導入は「開発者の負荷を増やすもの」として抵抗されがちである。
だが視点を変えれば、「PR説明が薄いとレビュワーが過剰にコードを読み解く必要がある」という現場課題がある。

  • 「どこをレビューしていいか分からないPRが増えている」
  • 「レビュワー間で観点がバラバラ」
  • 「誰も設計意図に踏み込まないレビューになっている」

これらの課題をチームで可視化し、PRテンプレート導入の動機と目的を共有することが重要。

ステップ2：テンプレート初期案はシンプルに、補足はコメントで対応

いきなり重厚なテンプレートを強制すると記入率が下がる。
最初は以下の3項目程度でスタートし、レビュー精度が明らかに改善することをチームで実感した後に項目を拡張していく。

最小テンプレート案 

## このPRの目的
## 主な変更点
## 見てほしい観点

→ これだけでも「LGTMだけのレビュー文化」から脱却する一歩になる。

ステップ3：テンプレートの記入内容をレビューでフィードバックする

記入内容に対するフィードバック例 
@Reviewer: 「見てほしい観点」に業務的判断のポイントが書かれていたので、今回はその点に集中して確認しました。とても助かりました。

→ 単に「書け」と要求するのではなく、「書いてくれて助かった」というポジティブなフィードバックを循環させることで文化として定着する

ステップ4：PRテンプレートの改善ループを回す

テンプレートがうまく使われない、記入されない理由を放置しない。

  • 「書きづらい」「入力量が多い」「どう書いてよいか分からない」
  • これらに対応するために、記入例・補足説明・選択式チェックボックスを追加していく
記入を助ける補足例 

## 見てほしい観点
（例）命名規則が既存と一致しているか？／状態管理の責務が肥大化していないか？ など

5. PRテンプレートが変えるレビュー文化の再設計

設計判断を「見える化」する文化が根づく

  • 開発者が「なぜこうしたか」を明示的に書くことで、レビュワーは設計判断に対してコメントできるようになる
  • 結果、レビューが単なる構文チェックではなく意図に対する対話となる
意図に基づくレビュー例 
@Reviewer: 状態管理をstoreではなくlocal stateにしているのは、モーダルだけの用途だからという設計判断でしょうか？共有可能性の観点では将来的に分離する可能性もありそうに思いました。

「レビュー観点のすり合わせ」が減る

  • PR説明に観点が明示されていれば、「見落とした」「そんな前提だとは思わなかった」といった観点齟齬が減る
  • 複数のレビューアーがいても、共通の焦点でレビューできる

レビュー効率が上がる

  • すべてを読んで判断する必要がなくなり、「意図と差分」に集中できる
  • PR説明が丁寧な人ほど、レビュー時間が短くても深い指摘が得られる構造になる

結果として、設計意図の共有と育成の土台が整う

  • レビューが「設計判断の根拠を明示する場」となり、若手開発者が判断思考を学ぶ教材にもなる
  • テンプレート記入内容をもとに、設計レビュー・アーキテクチャ議論への発展も可能になる

6. まとめ：レビュワーの欲しい情報からPRテンプレートを逆算する

PRテンプレートとは、開発者のためにあるのではない。
レビューアーが質の高いレビューを行うための情報提供フォームである。

本稿で示したポイントは次の通り：

要素 内容
目的 レビューアーの観点・判断の再現性と精度を高めるため
必須項目 変更目的、内容要約、見てほしい観点、影響範囲、確認方法
設計ポイント 補足例・入力形式・選択肢を併用し、記入負荷を下げる
導入方法 少数項目から始め、記入内容をレビューで活用して循環させる
効果 意図の可視化、観点の明確化、レビュー文化の再設計

レビューアーの仕事は、コードを見ることではない。
「判断のための情報が揃っているかを設計すること」でもある。

PRテンプレートは、その設計の第一歩である。