Pr Description

---
name: pr-description
description: PR のタイトルと本文を、レビューする人の問いに diff に現れない情報で答える形で書くための規範。書く手順（事実の一覧、節への割り当て、確認の突き合わせ）、節のカタログ、規模の目安、確認したことの書き方、言語の決め方、提出前チェックを定める。PR を作る・本文を書き直すとき（`gh pr create`、`gh pr edit`、`/create-pr`、会話中の「PR 出して」）に使う。commit メッセージ（`/commit` を使う）や issue 本文には使わない。
---

# 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 （置き換え、互換性、挙動の変化、計測、確認したことを書き分けている）