pr-description-writer

PR 説明文作成スキル

差分、コミット一覧、または簡単なメモをもとに、構成が整ったレビューしやすいプルリクエストの説明文を作成します。変更内容、理由、レビュー方法を網羅し、レビュアーがすぐに確認を始められるようにします。

目的が少し違いますか？ GitHub コネクターを使って実際の差分を読み込ませたい場合は、pr-description-live を使用してください。

必須入力

次の情報が提供されていない場合は、ユーザーに確認してください。

• 変更内容（git diff、git log --oneline を貼り付けるか、変更内容を平易な言葉で説明してください）
• 変更理由（解決する問題、または追加する機能）
• テスト方法（動作を確認するためにレビュアーが必要とする手順）
• リスクレベル（low / medium / high — レビュアー向けの説明の詳しさに影響します）
• PR の種類（feature / bug fix / refactor / dependency upgrade / config change / hotfix）
• ターゲットブランチ（例：main / develop / release/2.4 — リスクの説明やレビュアー向けの案内に影響します）
• 関連する issue またはチケット（例：JIRA-1234、GitHub #567 — または「なし」）

出力形式

タイトル

72 文字未満の、明確で命令形のタイトル： [type]: [concise description of what changed]

例：

• feat: add rate limiting to the public API
• fix: resolve race condition in session expiry
• refactor: extract payment logic into PaymentService

概要

次の内容を含む 2～3 文：

• この PR の内容（変更点）
• 変更が必要だった理由（問題または目的）
• 採用したアプローチ（概要）

変更内容

ファイル単位ではなく、論理的な変更ごとに 1 つの項目で、具体的な変更を箇条書きにします。

• [Y] を処理するために [X] を追加
• [B] を減らすために [A] をリファクタリング
• [D] に置き換えられたため [C] を削除
• [F] を修正するために [E] を更新

スクリーンショット／デモ

[UI の変更がある場合：変更前／変更後のスクリーンショット、または画面録画を含めます] [API の変更がある場合：リクエスト／レスポンスの例を含めます] [視覚的な変更も API 契約の変更もない場合：このセクション全体を省略します。プレースホルダーとして残さないでください]

テスト方法

レビュアーが実施できる手順：

1. [必要に応じてセットアップ手順]
2. [実行する操作]
3. [確認する内容]
4. [確認するエッジケース]

必要なコマンド、テストデータ、環境フラグがあれば含めます。

テストチェックリスト

• 単体テストを追加／更新
• 統合テストを追加／更新
• エッジケースを網羅
• 手動テストを完了
• 既存テストでリグレッションがないことを確認

レビュアー向けメモ

特に注意が必要な点を記載します。

• セカンドオピニオンがあるとよい不確実な箇所
• 意図的に選択したトレードオフ（およびその理由）
• 気づいたものの、対応範囲外として扱った項目
• 他の PR への依存関係（リンクを記載）

関連項目

• #[issue number] を解決（該当する場合）
• #[PR/issue number] に関連

参考資料

このスキルには補助ファイルが付属しています。利用可能な場合は使用してください。

• references/reviewer-empathy.md — レビューの道しるべとしての PR 説明文。出力を作成する際に適用してください。このファイルには、上記の手法の概要で簡潔にまとめた調整方法や判断の指針が記載されています。
• templates/pr-template.md — 品質チェック項目が併記された、成果物の記入用テンプレート。生成を依頼するのではなく、ユーザー自身で文書を作成したい場合に提示してください。

採点基準（0–40）

このスキルの出力は、提出前に必ず採点してください。32点以上であれば、出荷できる品質です。

評価項目	0	5	10
何をするかではなく、なぜするか	説明が差分の言い換えだけで、動機が示されていません	何をするかは明確ですが、なぜするかの説明が薄い、または一般的です（「コードを改善する」など）	問題、目標、アプローチが明確です。説明には、差分だけでは伝えられない背景が加えられています
タイトルと構成	構成のない段落が1つだけです。タイトルが曖昧、タイプの接頭辞がない、または72文字を超えています	見出しで構成されていますが、タイトルまたはセクションの使い方に問題があります（プレースホルダーのセクションが残っているなど）	有効なタイプの接頭辞があり、命令形で72文字未満です。セクションを見れば、レビュー担当者が必要な情報にすぐ移動できます
テストの再現性	テスト手順がありません	手順はありますが、コードベースへの理解が前提になっている、またはエッジケースが省かれています	コードに詳しくない人でも検証を再現できます。コマンド、テストデータ、フラグ、少なくとも1つのエッジケースが含まれています
リスクに応じたレビュー担当者向けガイダンス	リスクの高い PR にレビュー担当者向けの注意事項がない、または定型文だけです	注意事項はありますが、具体的なトレードオフ、不確実性、対象外の項目が示されていません	ガイダンスがリスクに見合っています。リスクが高い場合は具体的な懸念や意図的なトレードオフを明示し、低い場合は注意事項を1行にまとめるか、省略しています

品質チェック

• タイトルは命令形で、72文字未満です
• 概要で、何をするかと、なぜするかの両方を説明しています（何をするかだけではありません）
• 変更点のリストでは、ファイルごとではなく、論理的な変更を説明しています
• タイトルは有効なタイプの接頭辞（feat / fix / refactor / chore / deps / config / hotfix）で始まり、72文字未満です
• コードに詳しくない人でも再現できるテスト手順があります
• リスクの高い PR では、レビュー担当者向けの注意事項に、具体的な懸念点または意図的なトレードオフを少なくとも1つ記載しています。リスクが低い場合、レビュー担当者向けの注意事項は省略するか、1行にまとめています

アンチパターン

• 変更内容を言い換えるだけの説明にせず、変更の理由を説明してください
• テスト手順を省略しないでください。レビュー担当者が変更の動作を検証する方法を知る必要があります
• リスクの高い PR では、レビュー担当者向けの注意事項を省略しないでください。意図的なトレードオフや、慎重なレビューが必要な箇所を明示してください
• 差分を見れば明らかな実装の詳細を説明せず、差分だけでは伝えられない背景を加えてください
• 段落を1つだけにせず、見出しで構成し、レビュー担当者が必要な情報に移動できるようにしてください

使用例

• 「これらの変更について PR の説明文を書いてください」＋［差分または説明を貼り付ける］
• 「[機能] のプルリクエストを作成してください」
• 「PR の説明文が必要です。変更内容はこちらです」
• 「これらのコミットを PR の説明文にまとめてください」
• 「このブランチの PR 本文を書いてください」