PR にそのまま貼る説明文を、いきなり Claude Code に書かせると、だいたい散らかる。要点が混ざる。変更の理由が薄まる。読んだ相手が「で、何を見ればいいの」となる。
ここで効くのが、先に論点整理をさせて、PR説明の芯を作ってから本文に落とすやり方だ。非エンジニアの作業でも同じで、ファイル整理でも文書作成でも、先に「何を伝えるか」を固めるだけで手戻りがかなり減る。
Claude Code は、雑に頼むと雑に広げる。これは欠点というより、指示のあいまいさをそのまま反映するだけだ。だから最初にやることは、文章を書かせることではない。論点を切ることだ。
PR説明、論点整理、この二つを先にやると、説明の芯ができる。芯ができると、後から差分を見た人が追いやすい。レビューの質も上がるし、あとで自分が読み返したときの恥ずかしさも減る。
やり方は単純だ。まず変更内容を丸ごと説明させるのではなく、論点だけを短く抜き出させる。たとえばこんな頼み方でいい。
この変更について、PR説明を書く前の論点整理をしてください。
以下の観点で、重複しないように箇条書きにしてください。
- 変更の目的
- 何が変わるか
- 利用者に見える影響
- レビューで確認すべき点
- 説明で省いてよい細部
まだPR本文は書かないでください。まず論点だけ整理してください。
この段階では、きれいな文章は要らない。むしろ要らない。論点が見えれば十分だ。Claude Code に「本文を書いて」と先に言うと、細部まで抱え込んで、後で削るのが面倒になる。差分が大きいときほど、この失敗は重い。筆者は一度、修正内容の説明をそのまま全文で出させて、あとで「それは PR には不要だ」と半分以上切ったことがある。最初から論点だけ出させれば済んだ話だ。
論点が出たら、次に芯を一文で言わせる。ここが大事だ。PR は説明文の長さではなく、最初の一文で読者の頭に入るかどうかで決まる。芯のない PR は、変更点の一覧にはなっても、意図が残らない。
今の論点整理をもとに、このPRで最も伝えるべき芯を1文で作ってください。
条件は次のとおりです。
- 変更の目的が先にわかる
- 技術的な細部を詰め込みすぎない
- レビュー担当が確認すべきポイントがにじむ
- 読み手が「この変更は何のためか」をすぐつかめる
この「芯の一文」は、あとで PR 本文の冒頭に置く。たとえば「検索条件の扱いを統一して、一覧画面とCSV出力でズレないようにした」のような一文だ。こういう文があるだけで、後ろの説明はだいぶ書きやすくなる。読む側も、まず何の話か掴める。
そのあとで、Claude Code に PR説明を組み立てさせる。ここでも、いきなり本文全体を書かせるより、構造を先に決めるほうがいい。
次の構成でPR説明を書いてください。
1. 何を直したかを1〜2文で述べる
2. 変更の理由を簡潔に書く
3. 影響がある箇所を整理する
4. レビューで見てほしい点を明記する
条件:
- 断定しすぎず、でも曖昧にしない
- 冗長な背景説明は削る
- 実装詳細は必要なものだけ残す
- 箇条書きは最小限にする
ここで役に立つのが、ソースコードや差分そのものではなく、「何を変えたか」「なぜ変えたか」「何を確認してほしいか」の三点に絞ることだ。PR説明の中身を全部詰め込もうとすると、読む側の認知が先に死ぬ。特に、複数ファイルにまたがる修正や、見た目は小さいのに影響範囲が広い修正は危ない。説明が広がりすぎると、肝心の確認ポイントが埋もれる。
実務では、ここに一段だけ人間の判断を挟むと強い。Claude Code が出した論点整理をそのまま採用するのではなく、「これは説明に要る」「これは削る」を自分で線引きする。たとえば、内部のリファクタリングで利用者に見えない変更なら、PR本文ではそれを前に出しすぎない。逆に、動作は変わらなくても副作用がありそうなら、そこは明示する。
この線引きをサボると、PR は妙に長いのに重要点が薄い、あの嫌な文書になる。
つまずきやすいのは、論点整理を「要約」と勘違いすることだ。要約は元の説明を短くするだけだが、論点整理は読む順番を作る作業だ。順番が違う。
たとえば、先に実装の細部が並んでいると、読む側は目的を見失う。先に目的があれば、細部は後からでも追える。Claude Code に頼むときは、要約より先に「論点を切って」と言ったほうがいい。
もう一つ、やりがちなのが、差分を見せずに「いい感じに PR 文を書いて」と丸投げすることだ。これだと、平気で一般論が増える。実際の変更とズレた、ふわっとした説明になる。
筆者は一度、ファイル整理の手順を文章化させるとき、対象フォルダの実態を渡さずに頼んでしまい、不要な注意書きばかり増えたことがある。説明の芯がないと、出力はすぐ散る。Claude Code は勝手に察してくれない。そこは人間が先に枠を作る必要がある。
非エンジニアの使い方でも、この順番はかなり効く。たとえば、弁護士が案件フォルダを整える場面なら、「何を残すか」「何を捨てるか」「誰向けの説明か」を先に切っておく。書面作成でも、「結論」「根拠」「補足」の順に論点を並べるだけで、長文の迷子感が消える。
ファイル削減でも同じだ。重複ファイルを消したいのか、キャッシュを空けたいのか、古い書類をまとめたいのか。目的が違うのに同じ頼み方をすると、Claude Code の答えもぼやける。論点整理は、作業の名前を正しく付け直す工程だと思えばいい。
少し進めるなら、PR説明の下書きだけでなく、レビュー依頼文にも使える。先に論点を整理して、次に「今回はここを見てほしい」と明示する。これでレビュー相手の負担がだいぶ減る。
そして、もし論点が多すぎるなら、PR を割ったほうがいい。説明文で無理やりまとめても、読む側には関係ない。1本のPRに詰め込みすぎるほど、芯は薄くなる。そこは遠慮なく分けるべきだ。
最後に、使いやすい流れをそのまま置いておく。これを一回の依頼でやらせてもいいし、分けて使ってもいい。
1. この変更の論点を整理してください
2. その論点の中から、PR説明で必ず伝える芯を1文にしてください
3. その芯を先頭に置いて、PR説明の下書きを作ってください
4. レビューで確認してほしい点を最後に短く添えてください
この順番にすると、説明は散らからない。先に芯、次に肉付けだ。逆にすると、だいたい長いだけで弱い文になる。PR に載せる前に論点を整理させるのは、手間を増やすためではない。手戻りを減らして、説明の重心を前に置くためだ。そこを外さなければ、Claude Code はかなり使える。