PR 本文の書き方

原則

PR 本文は、diff に現れない情報を運ぶ。読み手はレビューする人で、その人が知りたいのは次のことである。

• 何を、なぜ変えたか。何を変えていないか。
• 既存の利用者やデータに何が起きるか。
• 何が確かめられていて、何が確かめられていないか。

diff を読めば分かること（変更ファイルの列挙、commit ログの転記、関数ごとの変更内容）は書かない。

書く手順

本文を書く前に、次の 1〜3 を作業メモとして書き出す（5 の照合もメモに書く）。どの節を書くかは、書き手が節ごとに判断するのではなく、1 で挙げた事実の置き場として決まる。作業メモは本文に含めない。事実が数個の小さな PR なら、メモも数行で済む。

1. 事実の一覧: レビューする人に伝える事実を 1 行に 1 つずつ書く。
   • 出どころは、PR に含まれるすべての commit の message（本文と action 行）、PR 全体の diff、会話の中で分かっている確認結果。diff を読むために周辺のファイルを見てもよいが、diff に含まれないファイルの中身（他の設定項目の名前など）を事実として並べない。対象外のものは「他のエンドポイント」のように種類で書く。
   • 「何を変えたか」「なぜそうしたか」「何を対象外にしたか」「マージ後に何が残るか」は、別々の行にする。
   • 追加・変更したテストは、「確認したこと」の確認手段として扱う。テストした個々の入力や条件は事実として挙げない。
   • commit の action 行（decision / rejected / constraint / learned）は 1 行ずつ、一覧に採るかを決める。採らないのは、レビューする人の判断に影響しない行だけにする。
   • action 行がない commit では、diff とコードコメントから同じ種類の事実を探す。
2. 置き場の割り当て: 各事実に、下の「節のカタログ」から節を 1 つ割り当てる。事実が 1 つも割り当たらない節は書かない。マージ後も残るリスクは、主な置き場に加えて「注意点」にも割り当てる。
3. 確認の突き合わせ: 「概要」と「挙動が変わったところ」で主張する変化を 1 つずつ挙げ、それぞれを実際に観察した手段を書く。自動テストでしか確かめていない変化は、「実環境（実際に使われる環境や本物の API）では未確認」とする。未確認とした項目は「確認したこと」に割り当てる。「注意点」だけに置かない。
4. 本文を書く: 一覧の事実はすべて、割り当てた節に載せる。長すぎるときは事実を削らず、1 行に縮める。
5. 照合: 書き終えたら、一覧の事実を 1 つずつ本文の行と対応させる。対応する行がない事実は、割り当てた節に足す。

節のカタログ

次の順で並べる。条件を満たさない節は、見出しごと書かない。「なし」とも書かない。

見出しは下の表の節名をそのまま使う。

節	この節に置く事実と、書き方
概要	常に書く。何を変えたか、なぜ変えたか（動機）、この PR が扱わない範囲とその理由
以前 / この PR の対比表	仕組み、ツール、依存を置き換えたという事実。行に観点、列に「以前」と「この PR」を置く
構成・主な変更	設計の選択とその理由のうち、概要の「なぜ」に収まらないもの（部品の作り方や置き場所の理由、却下した案とその理由、コードの規約）。部品ごとに「何をするか」ではなく「なぜそう作ったか」を書く。ファイルを 1 つずつ並べない
互換性（引き継いだもの）	利用者、保存データ、公開 API、設定について、変えずに引き継いだもの。具体的に挙げる
挙動が変わったところ	利用者から見える変化。「以前: … / この PR: …」の対で書く。意図した変化であることが分かるようにする
計測	性能についての主張。条件（データ量、環境、回数）、統計量（中央値など）、限界（相対比較にすぎない等）を書く。不利な結果も書く
テスト基盤	テストの仕組みそのもの（テストランナー、fixture の共通化、CI の実行方法など）を変えたという事実。テストを足しただけの PR では書かない。そのテストは「確認したこと」に確認手段として書く
確認したこと	常に書く。手順 3 の結果。項目ごとに確認手段（実行したコマンド、見た画面、返ってきた値）を添える
注意点	マージした後も残るリスク（対象外にした問題による穴、既知の不具合、rc 版や experimental の依存）。最後に置く。他の節に置いた事実でも、ここに 1 行で再掲する。未確認のことは「確認したこと」に書く

規模の目安

• 1 ファイル程度の修正は「概要」と「確認したこと」だけで、合わせて数行になる。
• 節を増やすのは、その節の条件を満たしたときだけ。大きな PR だから全部の節を書く、ということはしない。

確認したことの書き方

• 自分が実際に実行・観察したことだけを書く。セッション中に実行していないテストや、見ていない画面を書かない。
• 手段と結果を 1 項目に並べる。例: 「pnpm test で 174 件通過」「デプロイプレビューで /cors-proxy/ に認証なしで送り、直接送ったときと同じ 403 を確認」。
• 自動テストが偽の API やモックに対して動いているなら、そう書く。本物の環境で確かめたことと分ける。
• この PR で追加・変更したテストは、実行したコマンドの項目に括弧で 1 句添える。例: 「pnpm test で通過（入力検証の失敗系を確かめるテストを追加）」。テストした入力や条件は並べない。どの入力を塞いだかがこの PR の主題なら、それは「挙動が変わったところ」に書く。
• 手順 3 で「実環境では未確認」とした変化は、項目として挙げて「未確認」という語で書く（「未実施」「行っていない」などに言い換えない）。確認済みのように書かない。例: 「実際のブラウザでの表示は未確認（jsdom 上のテストのみ）」。

言語とタイトル

言語は次の順で決める。

1. リポジトリの直近の PR 本文の言語（gh pr list --state merged --limit 5 --json body）
2. 1 がなければ README の言語
3. どちらもなければ会話の言語

会話の中で既存 PR の言語がすでに分かっているときは、1 の API 呼び出しを省略してよい。

タイトルは、直近の merged PR のタイトルの慣習に従う。Conventional Commits（feat: …）が使われていればそれに従う。

文体

• 1 文に 1 つの事実を書く。
• 評価語（「改善」「より良く」など）だけで済ませず、何がどう変わったかを書く。数値があれば数値を書く。
• 専門語や略語は、初出で括弧の言い換えを付ける。例: 「polyfill（足りない組み込み関数を補う仕組み）」。
• 日本語で書くときは japanese-tech-writing skill を読んで従う。
• 英語で書くときは、短い平叙文で書き、受動態と修飾の重ねを避ける。

提出前チェック

• 「概要」と「確認したこと」がある
• 手順 1 の一覧の事実が、すべて本文のどこかに載っている
• 手順 3 で未確認とした変化が、すべて「確認したこと」に載っている
• 作業メモ（事実の一覧、割り当て、突き合わせ）が本文に混ざっていない
• 書いた節には、すべて手順 2 で事実が割り当たっている
• 「確認したこと」の各項目に確認手段がある
• 確認していないことを確認済みのように書いていない
• diff や commit ログの転記になっていない

帰属表示

本文末尾の帰属表示（Generated with Claude Code 等）は、ハーネスやユーザーの指示に従う。

参考

大きな PR の実例: https://github.com/azu/irodr/pull/127 （置き換え、互換性、挙動の変化、計測、確認したことを書き分けている）