プルリクの説明文を、毎回ゼロからひねり出しているなら、その時間はかなりもったいない。差分は読めるのに、説明だけが薄っぺらい。あれはだいたい、頭の中にある変更点をそのまま文章化していないのが原因だ。
Claude Code はここでかなり使える。コードの差分、変更したファイル、作業メモを拾わせて、PR のたたき台を一気に作らせればいい。自分で書くのは最後の調整だけになる。説明文の骨組みが先に出るので、抜け漏れも減る。
ただし、雑に「PR説明文を作って」で投げると、ふわっとした要約が返ってきて終わる。これがいちばんつまらない。人間が欲しいのは、読む相手がそのまま判断に使える文章だ。なので、最初から「何を見て、どの形式で、何を入れて、何を省くか」まで指定する。
まずは、作業中の変更があるリポジトリを開いた状態で、Claude Code にこう頼めばいい。
変更内容をもとに、プルリクエストの説明文を日本語で下書きしてください。
次の構成で出してください。
- 変更の要約
- 背景と目的
- 主な変更点
- 動作確認
- レビュー時に見てほしい点
- 補足
重要:
- 変更差分を読んだうえで書くこと
- 推測で機能を足さないこと
- 事実だけを書くこと
- 説明はそのまま GitHub のPR本文に貼れる粒度にすること
- 箇条書きを多めにして読みやすくすること
必要なら、未確定の点は「要確認」と明記してください。
これで十分なことが多い。Claude Code はリポジトリ内のファイルや差分を見て動けるので、説明文の下書きに必要な材料を自分で拾ってくる。ポイントは、「きれいな文章」を頼むのではなく、「レビューに使える説明」を頼むことだ。ここを外すと、見栄えだけ整った中身のない文章が出る。PR でそれをやると痛い。
もう少し実務寄りにするなら、差分の種類を先に伝えると精度が上がる。たとえば、コード修正なのか、ドキュメント更新なのか、ファイル整理なのかで、PR文の書き方は変わる。非エンジニア寄りの作業でも同じだ。たとえば大量のファイル整理や不要キャッシュ削除なら、説明文は「何をどう整理したか」「削除基準は何か」「戻す必要があるものはないか」を明確にした方がいい。
この変更は、重複ファイルの整理と不要なキャッシュの削除です。
PR本文の下書きでは、技術用語を増やしすぎず、以下を必ず入れてください。
- 何を対象に整理したか
- 何を残し、何を削除したか
- 削除の判断基準
- 失われる可能性があるものがあるか
- 復元が必要ならどう戻すか
読む人は技術者だけとは限らないので、短く明快に書いてください。
こうしておくと、説明文がただの作業日誌になりにくい。相手が知りたいのは「で、何が変わったのか」「安全なのか」「レビューでどこを見るべきか」だ。そこに合わせる。
筆者は最初、差分を見せずに「PR文を書いて」とだけ頼んで手戻りしたことがある。返ってきた文章はそれっぽいが、変更の肝が抜けていた。後で人間が全部直したので、結局二度手間だ。Claude Code に下書きをさせるときは、材料をちゃんと渡さないと意味がない。これはかなり大事だ。
特に気をつけたいのは、Claude Code が「それっぽい補完」をしてしまう点だ。変更したつもりのない挙動まで説明に混ぜられると、レビューが荒れる。だから、依頼文にこう入れておくといい。
差分に明示されていない機能追加や挙動変更は書かないでください。
不明な点は断定せず、「要確認」としてください。
これで、勝手な脚色をかなり抑えられる。PR の説明文で怖いのは、長いことよりも、事実と違うことが平気で混ざることだ。見た目が整っていても、そこは信用しない方がいい。
出力の形式も固定しておくと便利だ。たとえば GitHub の PR 本文にそのまま貼るなら、見出し付きの短い構成にすると読みやすい。レビュー担当は、長い作文より「何を見ればいいか」が欲しい。
GitHubのPR本文として使う前提で、Markdownで出してください。
見出しは次の順で固定してください。
## 変更の概要
## 背景
## 変更内容
## 動作確認
## レビューしてほしい点
## 補足
各項目は2〜5行を目安にし、必要なら箇条書きを使ってください。
ここまで指定すると、かなり実用的になる。逆に、全文を一段落でまとめさせると、読む側がつらい。PR 文は短文の寄せ集めの方が強い。特に動作確認とレビュー観点は、長文にしない方がいい。
実際の運用では、Claude Code に最初の下書きを出させたあと、人間が次の3点だけ直す、という流れがちょうどいい。ひとつ目は、目的の表現だ。変更内容が正しくても、目的がぼやけていると PR の意味が薄い。二つ目は、確認方法だ。実際にどう確かめたかを短く書く。三つ目は、レビュー観点だ。ここは「この部分だけ見てほしい」と具体化する。
たとえば、変更がファイル整理なら、こんな追記が効く。
レビューしてほしい点は、削除対象の選び方と、残すべきファイルを落としていないかに絞ってください。
コード修正なら、こんな感じだ。
レビューしてほしい点は、例外処理と既存挙動への影響に絞ってください。
この一文があるだけで、説明文の焦点が締まる。だらだらした「見てください」では、レビューは進まない。
もうひとつ、地味に効くのが「作業メモを一緒に渡す」やり方だ。Claude Code はリポジトリ内の差分を読むだけでもかなり働くが、作業中のメモがあるなら一緒に食わせた方がいい。たとえば、複数段階の整理や、途中で方針変更した案件だ。メモがあれば、変更の理由を補足しやすい。
以下は作業メモです。PR本文の背景と補足に反映してください。
- 旧形式のファイル名が混在していた
- 重複していた画像を整理した
- 参照が残っているファイルは削除していない
- 一部は今後別タスクで対応予定
この手のメモは、後から読む自分にも効く。PR 文はレビューのためだけでなく、未来の自分の記録にもなる。ここを雑にすると、あとで「あれ、なんでこうしたんだっけ」となる。
最後に、雑な依頼文でやりがちな失敗をはっきり言っておく。差分が大きいのに、何も指定せず要約だけさせる。あるいは、コードも文書も全部ひとまとめにして、同じ粒度で説明させる。これをやると、説明文は薄くなる。見る側も読みづらい。変更の種類ごとに分けて書かせた方がいい。
たとえば、コード変更とドキュメント更新が混ざるなら、こう指示する。
コード変更とドキュメント変更を分けて書いてください。
コード変更は挙動の変化を中心に、ドキュメント変更は読者への影響を中心に説明してください。
これだけで、PR の見通しがかなりよくなる。人間がレビューしやすい形に整えるのが目的であって、Claude Code に作文させること自体が目的ではない。
実務では、まず下書きを作らせ、次に自分で事実確認し、最後に文面を少しだけ削る。この順番で十分だ。PR の説明文は、気合いで書くものではない。差分を読ませて、判断材料を並べさせる。それがいちばん早い。