| name | pull-request-conventions |
| description | Use when writing a pull request description, or when responding to review comments — including automated review bots. Triggers on PR作成, PR本文, レビュー指摘への対応, nits, bot レビュー, レビュー返信文案. |
| summary | PR 本文の組み立て方と、レビュー指摘（特に自動レビュー bot）への対応判断の規範。テンプレート保持、指摘の裏取り手順、nits の着地の付け方を扱う。 |
PR 作成とレビュー対応
PR 本文はテンプレートを丸ごと残す（必須）
リポジトリに PR テンプレート（.github/pull_request_template.md 等）がある場合、その構造を 丸ごと残し、記入が必要な箇所だけを埋める。
- 記入不要なセクション・定型チェックボックス・HTML コメントを削除・置換しない。
- 該当しない項目（証跡の動画/スクリーンショット、任意チェックボックス等）は、チェックを入れずコメントごと温存する。
- 補足を書きたい場合は適切なセクションへ 追記 する。既存のテンプレ要素は消さない。
なぜ: 不要に見える項目も、レビュワーが「その観点が該当するのか／対応済みなのか」を判断する手がかりになる。テンプレ構造の一貫性はチーム運用の前提であり、埋まっていない欄があること自体が情報になる。
レビュー指摘への対応判断
「既存の慣習に合わせろ」は規約文書と突合してから受け入れる
自動レビュー bot は、規約が文書化される以前の古い書き方が残存しているコード を「既存の慣習」として引用し、規約準拠のコードに逆行修正を求めてくることがある。
判断の順序:
- 規約文書に定めがあるか → 文書が正。
- 文書に定めがなければ、多数派の前例と、引用された前例の 新旧 を確認する。
誤指摘は修正せず、規約文書を引用した返信文案を用意する。なお bot の指摘の多くは規約・多数派前例と一致する妥当なものなので、一律に疑ってかからない。
規約を根拠に反論する前に、その規約のスコープを確認する
規約文書を引用して指摘に反論するときは、その規約が対象としている範囲が今回のケースを本当にカバーしているか を先に確認する。文面だけ一致していても、規約が書かれた文脈・例示コードの対象が違えば適用できない。
確認するのは 2 点:
- 規約の 例示コードが今回の対象と同種か（例示が特定のスコープを前提にしていないか）。
- 規約でカバーされない部分について、今回のケース固有の実績（同種コードの既存パターン・同ファイル内の先行例）はどうなっているか。
規約でカバーされないケースは、規約の拡大解釈ではなく実績で判断する。
nits 指摘の着地の付け方
- 参照実装（別プラットフォームの実装・移植元など）がある場合は、実際に確認してから 整合性を論じる。推測で「揃う／ズレる」と言わない。現状が参照実装と 1:1 なら、それ自体が現状維持・最小変更の強い根拠になる。
- 見送りの論拠として有効なもの: 実害がない／仕様が今後動きうる（YAGNI）／影響範囲が閉じている／レビュワー自身が nits・imo と位置づけている／動作確認済みの状態を崩すリグレッションリスク。
- 理想解（構造整理・複数箇所の同時変更）は follow-up に回し、許容コスト内の中間案で着地してよい。 レビュワー自身が出した提案を採用すると確実にクローズできる。
- 意図的に指摘と違う着地をした場合、その意図と経緯は PR 返信＋コミットメッセージ に残す。コードコメントには書かない（コード自身の意味だけを書く場所であり、レビューの経緯は陳腐化する）。
