AIが書いた差分を含むPRのレビュー観点とPRテンプレートの作り方
AIを使いこなすClaudeで執筆し、GPTで自動校閲・修正しています。
AIが書いた差分のPRでも、レビューの基本は変わりません。変えるのは「何を申告させるか」と「どこを重点的に疑うか」です。作成者には、AIをどの範囲で使ったか、自分で何を確認したか、理解できていない箇所はどこかを書いてもらいます。レビュアーは、人が書いたコードより「それらしく見えるが前提が違う」「頼んでいない変更が混ざる」「テストが実装をなぞっているだけ」という種類のミスを念頭に読みます。 この記事では、PR説明欄のテンプレートとレビュアー用チェック項目を先に示し、そのあとで運用上の判断基準を説明します。テンプレートは編集上の提案で、実際のリポジトリで運用した結果ではありません。
先にテンプレートを置く
GitHubでは、リポジトリのルート、docs/、.github/ のいずれかに pull_request_template.md を置くと、PR作成時の説明欄の雛形にできます。複数の雛形を使い分けたい場合は PULL_REQUEST_TEMPLATE ディレクトリに置き、template クエリパラメータで指定します。なお、雛形はデフォルトブランチにマージされてから協力者に使えるようになります（GitHub Docs: PRテンプレートの作成で確認した内容です）。
次の内容を .github/pull_request_template.md に保存して使います。
## 目的と範囲
- 解決したい問題（Issue番号・リンク）:
- このPRでやらないこと:
## AI利用の申告
- AI生成・補完の範囲: [ ] なし [ ] 一部（補完・雛形） [ ] 大部分 [ ] ほぼ全部
- 使ったツール（任意・名称とモード）:
- AIに渡した情報: [ ] ソースの一部 [ ] ログ・エラー [ ] 設計メモ [ ] 渡していない
- 秘密情報・顧客データ・認証情報を渡していない: [ ] はい
- 外部のコードや文章をそのまま取り込んだ箇所: [ ] なし [ ] あり（出典とライセンス: ）
## 作成者が自分で確認したこと
- [ ] 全ての差分を自分で読み、説明できる
- [ ] ローカルで実行した（コマンド: ）
- [ ] 追加・変更したテストが、修正前の実装では失敗することを確認した
- [ ] 新しい依存パッケージ・外部APIの存在とバージョンを公式情報で確認した
- [ ] 頼んでいないファイルの変更や整形のみの変更が混ざっていない
## 確認が足りていない点・見てほしい点
- 理解が浅い箇所（ファイル名と行）:
- 動作未確認の環境・条件:
- 特に疑ってほしい判断:
## リスク
- 影響範囲: [ ] 認証・権限 [ ] 課金・個人情報 [ ] DBスキーマ [ ] 公開API [ ] 該当なし
- ロールバック方法:ポイントは、AI利用を「使った／使っていない」の二択にせず、範囲と渡した情報を聞いていることです。申告は責任を分けるためではなく、レビュアーが読む深さを決める材料として使います。「理解が浅い箇所」の欄は、書くことが評価を下げない運用にしないと空欄か「なし」で埋まります。
レビュアー用チェック項目
PRコメントや社内Wikiにそのまま貼れる形にしました。上から順に、問題が見つかりやすい順に並べています。
### 意図
- [ ] 差分がIssueの目的と一致している（頼まれていない改善・リネームがない）
- [ ] 「やらないこと」に書かれた範囲に踏み込んでいない
### 実在性
- [ ] import・関数・設定キー・CLIオプションが実際に存在する
- [ ] 追加された依存の名前が正しく、メンテされている
- [ ] 既存の共通処理があるのに、似た処理を新規に書いていない
### テスト
- [ ] 削除・skip・期待値の緩和がない（あれば理由が説明されている）
- [ ] テストが実装のコピーになっておらず、仕様から期待値が決まっている
- [ ] 異常系・境界値・権限違いのケースがある
### 安全性
- [ ] 入力検証、認可チェック、エラー時の情報漏えいを確認した
- [ ] 秘密情報、ダミーではない実データ、内部URLがコード・テスト・ログに含まれていない
- [ ] 外部コード取り込みの申告があれば、出典とライセンスを確認した
### 保守性
- [ ] 作成者が説明できない箇所が残っていない
- [ ] 例外の握りつぶし、過剰なtry/catch、不要な抽象化がない見落としやすい箇所
AI生成の差分で特に確認する価値が高いのは、次の3点です。
- テストの改変：失敗したテストを直す代わりに、期待値や条件を変えて通すことがあります。差分でテストファイルの削除行を先に見ます。
- 存在しないAPIや古い書き方：ローカルで動けば安心ではなく、依存のバージョンとドキュメントを照らします。
- 範囲外の変更：整形やリネームが混ざると、本質的な変更が埋もれます。分割を依頼してかまいません。
申告内容で読む深さを決める
申告を読んだあと、何をするかの判断表です。閾値は編集上の目安なので、チームの規模に合わせて調整してください。
- 補完程度、リスク欄が該当なし、レビュアーの対応：通常のレビュー
- 大部分がAI生成、テストあり、レビュアーの対応：上のチェック項目を全て確認。テストが修正前に失敗することを再現できるかを尋ねる
- ほぼ全部がAI生成、または「理解が浅い」欄に記載あり、レビュアーの対応：作成者に口頭または文面で説明を求め、説明できない箇所は分割か書き直しを依頼
- 認証・課金・個人情報・DBスキーマに触れる、レビュアーの対応：AI利用の有無にかかわらず担当者を指定し、2人目のレビューを入れる
- 秘密情報を渡した疑い、レビュアーの対応：レビューを止め、セキュリティ担当へ連絡
担当者の自動指定には CODEOWNERS が使えます。.github/、ルート、docs/ のいずれかに置け、ブランチ保護で「コードオーナーのレビュー必須」を有効にすると、変更されたファイルのオーナーのうちいずれかの承認が必要になります。全オーナーの承認ではない点に注意してください（GitHub Docs: コードオーナーについて）。
レビュー結果の返し方
GitHubのレビューには、Comment（承認も変更要求もしない一般的な意見）、Approve（マージ可能の合図）、Request changes（マージ前に対応すべき指摘）の3種類があります。また、管理者は保護ブランチでマージ前の承認を必須にできます（GitHub Docs: プルリクエストレビューについて）。
AI生成のPRでは、次のように使い分けると指摘が伝わりやすくなります。
- 「実在しないAPIを使っている」「テストの期待値が緩められている」など、動作や安全に関わる点はRequest changes
- 「ここは既存の共通処理が使えそうです」といった改善案はComment
- 作成者が説明できない箇所は、Request changesにせず、まず質問をコメントで返す
作成者への質問例
説明を求めるときは、責める文面を避け、確認したい対象を絞ります。
`src/billing/retry.ts` の再試行ロジックについて、
バックオフの上限を30秒にした理由を教えてください。
Issueの要件には記載がないので、仕様の根拠があるか、
AIの提案をそのまま採用したのかを知りたいです。
後者なら、上限を設定値に切り出す案も検討できます。運用を始める手順
- テンプレートを小さく始めます。項目が多いと全部チェックされるだけになるため、まず上の雛形から「AI利用の申告」と「作成者が確認したこと」の2ブロックだけで試すのも有効です。
- デフォルトブランチへマージして反映させます。マージ前は他のメンバーに表示されません。
- 数件のPRで、空欄になりやすい項目を見直します。常に空欄や「なし」の項目は、質問の仕方か項目自体を変えます。
- 重要なパスだけ CODEOWNERS とブランチ保護で担当者を固定します。
テンプレートはチェックを促すだけで、記入内容の正しさを保証する仕組みではありません。虚偽や記入漏れを防ぐ強制力はないため、レビュアーの確認項目と併用してください。
