サンプルコードで身につける: PRの説明文 — 何を・なぜ・どう確認したか

解説で学んだ概念を、5つの具体例で確認します。素朴な例から実務寄りの例へと進みます。

1説明文の基本テンプレート

「何を・なぜ・どう確認したか」の3点セットが説明文の骨格です。特に「なぜ」はコードの差分からは読み取れないので、必ず言葉にします。このテンプレートを毎回コピーして埋めるだけでも、PR の伝わりやすさは大きく変わります。

## 何を変えたか
ユーザー一覧画面に検索ボックスを追加しました。
入力した文字列で氏名を部分一致フィルタします。

## なぜ変えたか
ユーザー数が増えて目的の人を探しづらい、という要望に対応するためです。
(チケット: #123)

## どう確認したか
- [x] `ng test` が全件パス
- [x] ローカルで「山田」と入力して該当ユーザーのみ表示されることを確認
- [x] 空文字に戻すと全件表示に戻ることを確認

2画面の変更にはスクリーンショットを貼る

見た目の変更は文章より画像のほうが早く正確に伝わります。GitHub のコメント欄には画像をドラッグ&ドロップするだけで貼れます。変更前後を表で並べると、レビュアーは差分を数秒で把握できます。

## スクリーンショット

| 変更前 | 変更後 |
| --- | --- |
| ![before](変更前の画像URL) | ![after](変更後の画像URL) |

変更後は一覧の上部に検索ボックスが表示されます。

<!-- 貼り方: GitHub の説明文入力欄に画像ファイルを
     ドラッグ&ドロップすると、URL付きのマークダウンが自動挿入される。
     動きのある変更なら画面録画(GIFや動画)も同じ方法で貼れる -->

3レビュアーに見てほしい点を先に書く

レビュアーの時間は有限なので、自信のない箇所や設計判断が分かれる箇所を冒頭で指名します。逆に「機械的な変更なので流し読みでよい」箇所も伝えると、レビューの密度が上がります。案内板を立てるイメージです。

## レビューで特に見てほしい点

1. **フィルタ処理の設計**(`user-list.ts` の 20〜35 行目)
   検索文字列と一覧を computed で組み合わせています。
   メソッド呼び出しにする案と迷ったので、意見をもらえると嬉しいです。

2. **デバウンス時間**(300ms にしています)
   短すぎ/長すぎがあれば指摘してください。

## 流し読みでよい箇所

- `user-list.html` のクラス名変更はスタイル調整のみで、ロジックに影響しません。

4説明文を書くことはセルフレビューになる

説明文を書くには自分の差分を最初から見直すことになるため、消し忘れのデバッグコードや無関係な変更に自分で気づけます。レビュー依頼を出す前に自分の PR の差分画面を一度通読する習慣とセットにすると効果的です。

<!-- 説明文を書きながら差分を見直すときのセルフチェック観点 -->

## セルフレビューのチェックリスト(説明文を書く前に差分を通読)

- [ ] 消し忘れの `console.log` やコメントアウトが残っていないか
- [ ] この PR の目的と無関係な変更が紛れ込んでいないか
- [ ] 「なぜ」を一言で説明できるか(できないなら詰め込みすぎのサイン)
- [ ] 動作確認の手順を書けるか(書けないなら確認不足のサイン)

<!-- 「説明が書きにくい PR は、変更を詰め込みすぎている PR」。
     説明文は他人のためだけでなく、自分の見直し装置でもある -->

5テンプレートをファイル化してCLIから使う

毎回同じ構成で書くなら、テンプレートをファイルにしておくと楽です。リポジトリに PULL_REQUEST_TEMPLATE.md を置けばチーム全員の PR に自動で雛形が入り、gh pr create の --body-file でも説明文をファイルから渡せます。

# チーム共通のテンプレートを置く場所(どちらでもよい)
#   .github/PULL_REQUEST_TEMPLATE.md
#   docs/pull_request_template.md
# → 以後、PR 作成画面に自動でこの雛形が入る

# 手元で説明文を書いてから PR を作る場合
# 1. エディタで説明文を書く(何を・なぜ・どう確認したか)
#    例: pr-body.md に保存

# 2. ファイルを説明文として PR を作成
gh pr create \
  --title "ユーザー一覧に検索ボックスを追加" \
  --body-file pr-body.md

# 長い説明文はコマンドの引数に直接書くより
# ファイルで渡すほうが編集しやすく、書き直しも楽