create-compelling-prs

説得力のあるPRを作成する

あなたのPRは注目を集めるために競い合っています。レビュアーは多くのPRを確認しているため、あなたのPRがすぐに納得できるものでなければ、見送られるか却下されます。主張より証拠がものを言います。2分で納得してもらえる、適切に実装されたPRは、追加対応が必要なPRを5つ出すより価値があります。

PR本文のテンプレート

変更の種類に合ったテンプレートを選んでください。

バグ修正

## What broke
[One sentence: what failed and where]

## Root cause
[The underlying cause — missing guard, race condition, wrong assumption]

## Fix
[What changed and why this approach over alternatives]

## Before / After
| Before | After |
|--------|-------|
| ![before](URL) | ![after](URL) |

## Test output
[paste test run]

## How to verify
1. [Step to reproduce original bug — should now pass]
2. [Regression check]

Closes #ISSUE

機能

## What this adds
[One sentence: the user-visible capability]

## Why
[Business or product motivation]

## Implementation
[2-3 sentences: what was added/changed, key design decisions]

## Demo
![demo](URL_OR_GIF)

## Test output
[paste test run]

## How to verify
1. [Golden path step]
2. [Edge case]

Closes #ISSUE

リファクタリング

## What changed
[What was moved, renamed, or restructured]

## Why
[The underlying problem that made this necessary]

## What stays the same
[Public API, behavior, outputs — nothing visible changed]

## Test output
[paste exact commands, revisions, scope and results; state limits and remaining required gates]

Closes #ISSUE

依存関係

## Update
[Package] vX.Y.Z → vA.B.C

## Why now
[Security advisory / feature needed / routine bump]

## Risk
[Low/Medium/High — breaking changes? Coverage of affected areas?]

## Test output
[paste — owning repo dependency verification passed; name the commands and scope]

---

独立レビューの記録

実装パイプラインで独立したアドバイザリーレビューが行われた場合は、修正した提案、理由を添えて採用しなかった提案、レビューの実行時エラーにより利用できなかった提案、未対応で残っている提案を区別する短いセクションを追加してください。客観的なリポジトリポリシーによって、準備完了の判定やマージを制限することはできます。独立したLLMの提案自体がPRの作成を妨げたり、ミッションを失敗させたり、プッシュ済みのチェックポイントを放置させたりすることはありません。

---

デプロイの証拠

PRのレビュー前に、どこかで実行されたことを証明する必要があるか、またその形式は何かは、プロトコルではなくリポジトリポリシーで決まります。ステージング環境へのデプロイの検証をインフラ／バックエンドのPRに必須とする企業もあれば、そもそもステージング環境がない企業もあります。

まずリポジトリのプレイブックを確認し（GET /admin/playbooks/<org>/<repo>、見つからない場合は CONTRIBUTING.md／.github/PULL_REQUEST_TEMPLATE.md を確認）、以下を明確にしてください。

質問	重要な理由
レビューゲートで必要とされるデプロイの証拠は何ですか。また、どのパスが対象ですか？	ゲートによって、PRがレビュー前に却下されることがあります
証拠ブロックの正確な形式は何ですか？	ゲートはこれを解析します — プレイブックのブロックを一字一句そのまま記載し、言い換えないでください
本文とコメントのどちらですか？	本文をスキャンするゲートはコメントを確認せず、その逆も同様です
どのような場合に免除されますか？	ドキュメント／テストのみのPRは通常免除されます。免除の記録方法はプレイブックに記載されています

プレイブックにデプロイ証拠のポリシーがない場合は、独自に作らず、ステージング環境があるとも想定しないでください。ローカルで何をどのように検証したかを、正確なコマンドとその出力とともに記載し、プレイブックにデプロイ証拠の要件が定められていないことをPR本文に明記してください。

---

視覚的な証拠

UIに影響する変更では、変更前と変更後のスクリーンショットを取得し（Playwrightを推奨、手動での取得も可）、PR本文に埋め込んでください。

画像のホスティング方法はリポジトリポリシーで決まります。 プレイブックにアセットホスティングのセクションがあるか確認し、その指示に従ってください。環境に EVIDENCE_* シークレットがある場合は、evidence-upload スキルを使用してください。公開の証拠用バケットにアップロードし、プライベートリポジトリでも表示できる埋め込み用URLを出力します（URLを知っていれば誰でもアップロードした内容を閲覧できるため、シークレットや顧客データはアップロードしないでください）。

アセットホスティングのセクションがない場合は、画像をPRに直接添付する（GitHubはPRエディターまたはコメントAPIからアップロードされた画像をホストします）か、CIアーティファクトにリンクし、どちらを使ったか記載してください。レビュアーがアクセスできないホストの画像には、絶対にリンクしないでください。

次の場合は省略してください：バックエンドのみ、CLIのみ、設定／インフラ、テストのみ、または取得に120秒を超える場合。視覚的な証拠は推奨事項であり、リポジトリのプレイブックで必須とされていない限り、ゲートではありません。

---

検証範囲

コマンドを選ぶ前に、対象リポジトリで有効な指示と検証要件を確認してください。変更全体を、影響を受ける動作と直接の利用者に対応付けてください。共有コード、依存関係／ロックファイルの変更、マイグレーション、変換処理、統合境界も対象に含めます。検証要件で許可される場合は、意味のある重点チェックを実行してください。必須の広範なチェック、全テストスイート、ビルド、ステージング、リリースの各ゲートはすべて維持してください。依存関係の変更をテスト免除の理由にしてはいけません。影響範囲が対応付けられていない場合や、意味のあるカバレッジが不足している場合は、より広範な検証を行うか、未解決のカバレッジ不足として明示してください。リポジトリのポリシーと実際に設定されたワークフローを確認せずに、CI が完全なゲートを担うと推測してはいけません。

実行したコマンド、対象範囲、結果、正確なリビジョン、残っているゲートを記録してください。失敗した実行、利用できなかった実行、テストが 0 件だった実行は合格とみなせません。既存の検証記録を再利用できるのは、そのリビジョン、対象範囲、環境、ポリシーが現在も適用される場合に限ります。変更後、失敗後、または懸念事項が未解決の場合は、再実行してください。独立した受け入れ確認は引き続き必要です。diff を確認し、必要に応じて関連する動作やゲートを再現してください。変更されていないコードに対して、同じ全テストスイートを自動的に繰り返す必要はありません。

セルフ監査チェックリスト

PR を作成する前、またはレビュー可能としてマークする前に、以下を実行してください。

• 完了していますか？ この PR の単一の主導イシューが示す、範囲の定まった作業をすべて完了していますか？
• 出荷可能ですか？ 現状のままマージした場合、この PR によって主導イシューが解決されますか？意図的に延期するすべての基準を、共有のフォローアップイシューの規約に従って、リンク先のフォローアップに原文どおり記載していますか？
• 手動作業への注意書きはありませんか？ PR 本文に「手動で X する必要があります」という指示が一切ありませんか？
• 検証に合格していますか？ 現在のエビデンスで、影響を受ける動作と、リポジトリで必須のすべてのゲートを確認できていますか？正確なコマンド、対象範囲、リビジョンを記録していますか？
• エビデンスがありますか？ 意味のある変更ごとに、スクリーンショットまたはテスト出力を埋め込んでいますか？
• ポリシーに従っていますか？ プレイブックで指定されたデプロイエビデンスのブロックを、指定された場所に原文どおり記載していますか？または、「プレイブックにポリシーなし」という注記を本文に記載していますか？
• イシューにリンクしていますか？ PR には主導イシューがちょうど 1 件あり、そのイシューに Closes #N、Fixes #N、または Resolves #N を使用していますか？意図的な複数 PR の作業では、後続の各 PR にもそれぞれ主導イシューが必要です。共有のフォローアップイシューの規約に従ってフォローアップを作成してリンクし、後続の PR からそのフォローアップをクローズしてください。Refs #N は、関連する背景情報として明確に示されたイシューにのみ使用し、現在の PR の主導イシューには使用しないでください。

「手動作業への注意書きはありませんか？」の確認に失敗した場合は、代わりに PR をクローズし、ブロッカーを報告してください。 報告の形式は、リポジトリのプレイブックで指定されているもの（ブロッカー報告、イシュー、ミッションレポート）に従います。指定がない場合は、リポジトリにイシューを作成してください。作業を先送りする PR は、PR がない状態よりも悪いものです。障害を迂回してください。UI しか手段がない場合は API を使い、API がない場合はスクリプトを作成してください。

リードの自己評価ループ

作業者が完了を報告しても、すぐに受け入れてはいけません。さらに深く確認してください。

反復プロトコル：

1. 合意した成果、差分、影響を受ける動作、現在の検証記録を確認します。
2. 具体的な受け入れ基準の不足を特定します。主張ではなく、行動を求めてください。動作確認が不足しているなら証拠が必要です。表示上の不備があるなら、必要に応じて実際に確認するか、スクリーンショットを求めます。
3. 修正後は、更新されたリビジョンで影響範囲を検証し、重要な不足が残っていないか確認します。独立して必要なリポジトリのゲートは維持してください。
4. 受け入れが証拠によって裏付けられたら終了します。努力を示すためだけに、反復、テスト、コード変更を追加してはいけません。不足を解消できない場合は、具体的な阻害要因と証拠を示してください。

ルール：

• 美辞麗句を受け入れないでください。「これは確実に問題ありません」という言葉は証拠ではありません。証拠を求めてください。
• **独立して検証してください。**現在の証拠を確認し、担当リポジトリの契約に沿って、関連する動作やチェックを再現します。PR の URL を開き、該当する場合は影響を受ける稼働中のサイトを読み込みます。受け入れる前に、重要な不足を解消してください。
• **修正と証拠を追跡してください。**有効な検証記録があれば、コード変更なしで不足を解消できます。特定した不足ごとに、具体的な結果を求めてください。

ローテーション用の質問（回答が定型化しないように変えてください）：

• 「シニアエンジニアなら、コードレビューで何を却下しますか？」
• 「この証拠は、どの影響を受ける動作とリポジトリのゲートをカバーしていますか？不足している有意義なチェックを実行し、出力を貼り付けてください。」
• 「影響を受けるページのスクリーンショットを撮ってください。デザインシステムに合っていますか？」
• 「何を後回しにしましたか？タスクを読み直して、すべての成果物を列挙してください。」
• 「これが却下されるとしたら、最も可能性の高い理由は何ですか？先回りして修正してください。」