Claude Codeでプルリクエストの説明文を下書きする：レビューされやすい書き方

Claude Codeに任せる範囲と人が持つ範囲

Claude Codeの公式ドキュメントCommon workflowsには、PR作成の流れとして、まず変更内容を要約させ、次にPRを作らせ、最後に説明文へ文脈を足させる手順が載っています。同ページは、提出前にClaudeが生成したPRを確認し、リスクや注意点を挙げさせるよう勧めています。

この流れを踏まえ、情報の持ち主ごとに整理すると次のとおりです(割り振りは編集上の提案です)。

• 変更したファイルと内容の要約、主に誰が出すか：Claude Code、理由：差分とコミットから読み取れる
• 影響しそうな箇所の候補、主に誰が出すか：Claude Code、理由：呼び出し元の検索などが得意な作業
• 変更の背景・目的、主に誰が出すか：人、理由：チケットや会話の文脈は差分に出ない
• 実際に実行した確認、主に誰が出すか：人、理由：実行していないことを書かせない
• レビュアーに見てほしい点、主に誰が出すか：人が決め、Claudeが整える、理由：迷っている点は書いた本人しか知らない
• スクリーンショットや画面の変化、主に誰が出すか：人、理由：実際の画面を見て貼る

PR説明テンプレート

下のテンプレートは、レビュアーが最初に知りたい順(何のためか→何が変わるか→どう確かめるか→どこを見るか)に並べています。小さな変更なら不要な見出しは削って構いません。

## 概要
<!-- 1〜2文。何を、なぜ変えるか -->

## 背景・関連
<!-- 課題、チケット、議論へのリンク。なければ「なし」 -->

## 変更内容
-
-

## 変更しないこと
<!-- 今回のスコープ外。迷いやすい点があれば明記 -->

## 確認方法
<!-- レビュアーが再現できる手順 -->
1.
2.

## 実施した確認
<!-- 実際に実行したものだけ。未実施は「未実施」と書く -->
- [ ] テスト:
- [ ] 手動確認:

## 影響範囲・リスク
<!-- 影響する機能、互換性、移行手順、ロールバック方法 -->

## レビューしてほしい点
<!-- 特に見てほしい箇所、判断に迷った箇所 -->

「変更しないこと」と「実施した確認」に未実施を書ける欄を設けているのがポイントです。AIの下書きは、書き込む材料がないと、それらしい確認結果を補ってしまうおそれがあります。欄に「未実施と書く」と明示しておくと、空白を作り話で埋める余地が減ります。

テンプレートをリポジトリに置きたい場合、GitHubは.github/pull_request_template.md、ルート直下、docs/配下のいずれかにpull_request_template.mdを置く方式に対応しています。複数のテンプレートを使うならPULL_REQUEST_TEMPLATEサブディレクトリを使います。いずれも、デフォルトブランチにマージされてからコラボレーターが使える点に注意してください。詳細はGitHub DocsのPRテンプレートの作成にあります。

下書きを依頼する指示文

次の指示文は、テンプレートを使い、確認していないことを書かせず、PRの作成までは実行させない形にしています。【】の部分を自分の内容に置き換えてください。

現在のブランチの変更について、PR説明文の下書きを作ってください。

手順:
1. `git log main..HEAD --oneline` と `git diff main...HEAD` で変更を確認する
2. @.github/pull_request_template.md の見出しに沿って下書きを書く
3. 下書きはこの会話に表示するだけにし、PRの作成コマンドは実行しない

私から渡す情報:
- 背景・目的:【例:ログイン失敗時のエラーメッセージを統一したい】
- 実行した確認:【例:`npm test` を実行し全件成功。画面での手動確認は未実施】
- 特に見てほしい点:【例:エラー文言の変更箇所が他画面に影響しないか】

守ってほしいこと:
- 「実施した確認」には、上に書いたものだけを入れる。未実施と伝えたものは「未実施」、実施状況を伝えていないものは「要確認:実施状況不明」とする
- 差分から読み取れない背景や理由は推測せず、「要確認:」として質問に回す
- 影響範囲は、差分から見つかった根拠(ファイル名・関数名)付きで挙げる
- 最後に、レビュアーが指摘しそうな点を3つ以内で挙げる

mainはPRのマージ先ブランチに読み替えてください。このコマンド例の対象はコミット済みの変更です。未コミットの変更は含まれないため、必要な変更をコミットしてから使ってください。テンプレートがまだ無いリポジトリでは、手順2の行を差し替え、この記事のテンプレートを指示文の末尾に貼れば使えます。

ポイントは「推測せず、要確認として質問に回す」という指定です。Claude Codeに、不明な背景を補わず質問として返すよう促せます。質問への回答と、推測が混ざっていないかの確認は人が行います。

下書きを直す追加指示

Common workflowsでは、作成後に「セキュリティ改善についての文脈を説明文に足して」のように追加の指示で磨く流れが紹介されています。下書きが出たら、次のような短い指示で改善できます。

「概要」を、変更の背景を知らない人でも読めるよう2文以内に書き直して。
「確認方法」を、コマンドと期待される結果の組に分けて。

説明用の入力例と下書きのイメージ

次は、架空の変更を想定した説明用の例です。実際に実行した結果ではありません。

人が渡す情報(例)

• 背景:ログイン失敗時のメッセージが画面ごとに違い、問い合わせが増えている
• 変更:エラーメッセージを一つの定数ファイルに集約した
• 確認:ユニットテストは通過、画面確認は未実施

求める下書きの形(例)

## 概要
ログイン失敗時のエラーメッセージを `messages.ts` に集約し、画面間で文言を統一します。

## 実施した確認
- [x] テスト: ユニットテストを実行し通過
- [ ] 手動確認: 未実施

## レビューしてほしい点
- 旧文言を参照している他の画面が残っていないか

「手動確認:未実施」とそのまま書かれているかを見てください。ここが「確認済み」に化けていたら、下書きをそのまま使ってはいけません。

提出前の確認項目

下書きを貼る前に、人が次を確かめます。

• [ ] 「実施した確認」の各項目を、自分が実際に実行したか
• [ ] 確認手順を、自分の手でもう一度たどれるか
• [ ] 変更内容の箇条書きが、差分と食い違っていないか(消したのに「追加」と書かれていないか)
• [ ] 「要確認:」の質問に答え、文章から消したか
• [ ] 影響範囲に挙がった箇所を、少なくとも1か所は自分で開いたか
• [ ] 本来のスコープ外の変更が差分に混ざっていないか
• [ ] 認証情報、社内URL、顧客名などが説明文やログの貼り付けに含まれていないか
• [ ] 1つのPRに複数の目的が混ざっていないか

スコープ外の変更や複数の目的が混ざっている場合は、差分そのものの見直しも必要です。説明文を整えても、混ざった変更は読みやすくなりません。説明文を書きにくいときは、PRの分割を考える合図になります。

判断表:Claude Codeの出力をどう扱うか

• 「確認済み」が、自分の実行内容と合っている、対応：他の提出前の確認項目も満たしていれば採用
• 実行していない確認が書かれている、対応：確認済みの記述を削除し、未実施と実施状況不明を区別するよう指示して再生成
• 背景が抽象的で一般論になっている、対応：背景を自分の言葉で渡し、概要だけ書き直させる
• 変更内容が差分より多い、または少ない、対応：差分と突き合わせ、ファイル単位で再整理させる
• 説明が長大になる、対応：「変更内容」を重要度順に5項目以内に絞らせる

提出後に、同じ作業の会話へ戻りたいことがあります。公式ドキュメントによれば、Claudeがgh pr createなどでPRを作成した場合、セッションがPRに紐づきます。claude --from-pr <PR番号>で、そのPRに紐づくセッションを選ぶ画面を開けます。レビューで修正を求められたときに、元の文脈を引き継げます。

運用のコツ

テンプレートと指示文をそれぞれ一度作れば、PRごとに変わるのは「背景」「実行した確認」「見てほしい点」の3項目だけです。この3つは、PRを出す直前にメモしておくと負担が小さくなります。

プロジェクト固有のルール(コミットメッセージの形式、PRタイトルの付け方など)がある場合は、指示文に毎回書くより、リポジトリ側の設定ファイルにまとめる方法が考えられます。設定の方法は本記事の範囲外なので、Claude Codeのドキュメントで確認してください。