PR説明文

PR の説明文だけを担当する。差分から本文を組み立て、提出前チェックを通してから提示する。 PR の作成・更新コマンドは実行しない。

1. 差分を把握する

まずベースブランチを決める。

gh pr view --json baseRefName,title,body 2>/dev/null   # 既存PRがあればベースと現行本文を取得
git symbolic-ref --short refs/remotes/origin/HEAD      # 無ければリモートのデフォルトブランチ(例: origin/main)

以降 <base> はリモート参照(origin/main など)を指す。gh pr view の baseRefName は main のようにリモート名を含まないため、origin/ を補う。

どちらも取れない場合は、ベースブランチをユーザーに聞く。推測で main や master を使わない。git merge-base --fork-point は upstream の reflog に依存し、fresh clone では失敗するか誤った起点を返すため使わない。

差分は次の3つを併用する。

git diff <base>...HEAD --stat   # コミット済みの変更
git diff <base> --stat          # 作業ツリーとの比較。未コミットの変更を含む
git status --short              # 未追跡ファイル。上の2つには現れない

三点記法(...)はコミット間の比較であり、未コミットの変更を含まない。コミット前に本文を作る場合、三点記法だけでは差分が空になる。

git log のコミットメッセージは構成の材料にしない。コミット単位は作業の順序であり、説明文の構成とは別物。

2. PRテンプレートを確認する

ls .github/PULL_REQUEST_TEMPLATE.md .github/pull_request_template.md \
   PULL_REQUEST_TEMPLATE.md pull_request_template.md \
   docs/PULL_REQUEST_TEMPLATE.md docs/pull_request_template.md 2>/dev/null
ls .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null   # 複数テンプレートが置かれている場合

.github/PULL_REQUEST_TEMPLATE/ に複数ある場合は、どれを使うかをユーザーに聞く。

テンプレートがある場合、見出しの構成はテンプレートに従う。手順3はその各見出しに何を書くかの基準として使う。

• テンプレートの見出しは削除・改名しない。該当が無い見出しは見出しごと残し、本文に「該当なし」と書く
• テンプレートに無い見出しを足さない。手順3の「後半」に挙げた観点は、テンプレートの既存見出しのいずれかに収める
• テンプレートの見出しが検討の経緯や代替案の記載を求める場合(「検討した代替案」など)も、見出しは残したうえで結論だけを書く。「変更の背景」のように背景を求める見出しは Why に当たるため、これに含まない
• チェックボックスやコメント行(<!-- -->)の指示があればそれに従う

テンプレートが無い場合のみ、手順3の見出し構成をそのまま使う。

3. PR説明文の構成

レビュワーとレビューエージェントの二種類が読む。必要な粒度が異なるため、削るのではなく層を分ける。

前半(人間向け・目安15行以内)

• What: 利用者または開発者の視点で、この変更で何が変わるか
• Why: diff から動機が自明でない場合は必須

判断に必要な最小限だけを置く。ここだけ読んで「マージしてよいか」の当たりがつく状態にする。

後半(レビュー材料)

レビュー観点ごとに見出しを立てる。該当しない見出しは省く。

• 影響範囲: 変更したファイル群と、波及しうる箇所
• 検証: 手動で確認した手順と結果
• 既知の制約: 今回対応しないと決めたこと、残課題

4. 提出前の確認

• 前半だけで変更の要否が判断できるか
• 時系列を表す語(当初、最終的に、〜した結果、〜が判明した)が残っていないか
• AI とのやり取りに言及していないか
• 「書かないもの」に該当する記述が残っていないか
• テンプレートがある場合、見出しの過不足が無いか
• 経緯や代替案を求める見出しに、経緯ではなく結論だけを書いたか

禁止事項

書かないもの

• diff を見れば分かる実装の説明
• CI が実行する検証コマンド(pnpm build、pnpm test など)
• 作業の経緯

経緯とは、結論に至るまでの試行錯誤の記録を指す。レビュワーは結論だけを必要としており、経緯が載ると結論と経緯を切り分ける作業を読み手に押しつけることになる。不採用案も書かない。

❌ 当初はAで実装したが型エラーが解決せず、Bに切り替えた
❌ 3回目の修正でキャッシュが原因と判明した
❌ Bで実装した(Aは型定義の都合で採用できない)
✅ Bで実装した

操作

• 確認なしに gh pr create / gh pr edit を実行しない。本文の提示までで止める
• 既存 PR の本文を、差し替え内容をユーザーに見せる前に上書きしない
• PRテンプレートのファイルを書き換えない
• 差分から確認できない検証結果・影響範囲を書かない。未実施なら「検証」の項目を省く(テンプレートに見出しがある場合は「未実施」と書く)
• 差分に無い変更を説明文に含めない

出力形式

1. 本文全体を Markdown のコードブロックでチャットに提示する
2. 同じ内容を一時ファイル(scratchpadなど)に pr-body.md として保存し、パスを伝える(gh pr create --body-file にそのまま渡せる形)
3. テンプレートの有無と、どのファイルを使ったかを1行で添える
4. 提出前の確認の各項目について、通ったか・省いた見出しは何かを1〜3行で添える
5. コマンドの実行はユーザーの指示を待つ

本文の言語は、そのリポジトリの直近の PR に合わせる。判断できない場合はユーザーに聞く。