TrackerJo/pr-description

平易な英語のPR説明文

変更を素早く理解する必要があるメンテナー向けに記述します。良い説明文は、最初の画面で次の3つの質問に答えます。

1. 何が間違っていた、または不足していたか？
2. なぜ変更が必要だったのか？
3. 現在、何が真であるか？

記述する前に、実際の差分、現在のPR本文、コミット、テスト、PR状態を読み込んでください。古い本文やコミットタイトルは意図を表すものであり、証拠ではありません。作者が確認していない限り、手動テスト、デプロイ、本番環境での振る舞いを主張してはいけません。

必須の冒頭セクション: What Changed and Why

すべてのPR説明文は、モニター所有の ## Status セクションが存在する場合はその直後に、貢献者所有の ## What Changed and Why セクションで始まらなければなりません。これは必須の書式であり、任意ではありません。

次の順序で、3つの短いラベル付き段落を使用します。

• Issue: 実際のユーザーまたは運用者の障害、または欠落していた振る舞い。
• Why this change was necessary: その障害がなぜ重要だったか、なぜ選ばれた境界が必要なのか。
• New status quo: このPR後の具体的な振る舞い。

各ラベル付き段落は1～2文に抑えます。メンテナーはこのセクションだけで「このPRで何が起こったか」を答えられなければなりません。実装の仕組み、削除された設計、履歴の書き換えから始めてはいけません。

不十分な冒頭をレビューする場合は、具体的な代替案、または実際の差分に合わせた簡潔な3段落の概要を提示してください。「冗長である」「不明瞭である」「より良い説明が必要である」とだけ言うのは避けてください。

ほとんどのPRでは、以下の形式を使用します。

## What Changed and Why

**Issue:** [実際のユーザーまたは運用者の障害、または欠落していた振る舞い]

**Why this change was necessary:** [それがなぜ重要だったか、なぜこの境界が必要なのか]

**New status quo:** [このPR後の具体的な振る舞い]

## After merge

[残っている実際の運用者またはレビューアのアクションのみ。存在しない場合はこのセクションを省略]

## Verification

[確認済みの手動チェックと、真にマージ後に行うチェックのみを記載]

本題から始めてください。PRタイトルを言い換えたり、導入を追加したり、次の段落を繰り返す要約を書いたりしないでください。

保持すべきもの

• 重要な変更ごとに1つの明確な最終状態。 各段落や箇条書きの最初の文を読むだけで、マージ後に何が変わるかを理解できるようにします。
• 実際の判断。 却下した代替案は、製品の振る舞い、リスク、または意味のあるコストに影響する場合にのみ名前を挙げます。何を選び、なぜ選んだかを一文で述べます。「主要な判断」というラベルを作り出してはいけません。
• 運用上の事実。 マイグレーション、バックフィル、スケジュールされたジョブ、統合、シークレット、デプロイ順序、障害時の振る舞いについて、レビューアや運用者が対処する必要がある場合は言及します。
• 正直な検証。 誰かが実際に手動で確認したことと、本当にマージ後まで待たなければならない作業を区別します。lint、ビルド、CI、テストコマンドは記載しないでください。テストは、意味のある振る舞いをカバーしている場合に限り、平易な英語で言及できます。
• 未解決の依頼。 レビューアが判断しなければならない未解決の決定事項のみを含めます。質問を最初に置き、次に推奨事項とそのコストを記述します。判断すべきことが何もない場合はこのセクションを省略します。

変更されたシステムに対する必須の証拠

ユーザー向けシステム、重要な運用者ワークフロー、またはその設定を変更する場合で、レビューアに確認方法を示していない場合、説明は不完全です。

• スクリーンショットまたは短い動画: ビジュアル証拠は独立した ## Visual evidence セクションに配置します。変更された画面のスクリーンショット、または変更された操作や複数ステップのフローの短い動画を含めます。メディアを埋め込むか、安定したPR添付ファイルにリンクします。キャプションには、何が変更され、レビューアが何を見ているかを記述します。ソースコードのスクリーンショット、テストレポート、変更されていない画面で代用してはいけません。公開面やイベント面では、必要な携帯電話の証拠をノートパソコンの証拠より先に配置し、各ビューポートとテスト済み状態を特定します。取得、アップロード、最新コミット確認については visual-proof スキルに従ってください。このセクションは、PRにビジュアルまたはインタラクティブな面がない場合にのみ省略します。
• 設定、環境、マイグレーション: 実際に追加、削除、名称変更、または振る舞いを変更する環境変数、シークレット、ダッシュボード設定、データベースマイグレーションのみを ## Configuration に配置します。運用者が取るべき1つのアクションを先頭に置き、通常の外部設定は1つの短い文にまとめます。例: Set up a monitor at <URL> and point it to https://buildpurdue.org/api/health. No internal changes. ポーリングの詳細、既に別の場所で説明済みの根拠、重複したランブックへのリンクでセクションを埋めてはいけません。実際のマイグレーションについては、コミットされた supabase/migrations/ パスを名前を挙げ、スキーマ/データ/ポリシーの変更を要約し、互換性またはバックフィルの要件を述べ、確認済みの npm run dev:verify の再生結果を記載します。シークレットの値を出力してはいけません。設定やマイグレーションの変更がない場合は、このセクションを省略します。
• 変更されたフロー: 重要なフローの変更にはMermaidフローチャートを使用します。フローが重要となるのは、複数のステップ、分岐、リトライ、システム間のハンドオフ、または障害パスがある場合です。変更されたパスとその重要な障害時の振る舞いを、レビューアが読める平易なラベルで示します。変更されたフローごとに1つの図を追加します。1ステップの名称変更や些細なローカル計算には図を使用しないでください。

これらはメインの説明とは別のものです。説明は変更が存在する理由を述べ、証拠、設定、図はレビューアがそれを検査できるようにします。

読みやすさを保つ

• デフォルトは 250ワード以下 にします。運用者が短いチェックリストを必要とする場合、説明はより長くなっても構いませんが、すべての文はその価値を証明しなければなりません。
• 短い段落を使用します。実際のリスト（残りのセットアップ手順など）にのみ箇条書きを使用します。すべての文をラベル付きの箇条書きにしないでください。
• 問題、理由、新しい現状を通常の英語で記述します。誰が何をするかを明確にします。
• 生のコード、クエリ、設定の断片、名詞としてのステータスコード、専門用語、比喩、誇大広告、emダッシュ（—）を避けます。
• すべての仕組みを説明する必要はありません。レビューアが知る必要のある振る舞いに留めます。
• 後続のセクションで事実を繰り返さないでください。情報を失わずに文を削除できる場合は、削除します。

Statusはモニターが所有する

貢献者は、## Status を除く PR説明文のすべての部分を所有します。そのセクションを自分で追加、削除、編集してはいけません。BuildPurdue PRモニターがそれを所有し、現在のレビュー状態と整合性を保ちます。

Statusを変更する場合、モニターは一致する Status update: PRコメントも投稿します。作業が残っている場合はマージ前の具体的な次のアクション、何も残っていない場合は No more remaining work. という、1文の平易な英語を使用します。Statusは、貢献者向けの説明レビューコメントに含めてはいけません。

Statusを、将来のオプションのアイデア、過去のメモ、マージ後専用の作業、またはこのPRをブロックしない別途追跡されている作業に使用してはいけません。

より多くの構造が正当化される場合

メインの説明に収まらない情報がある場合にのみ、焦点を絞ったセクションを追加します。

• データベース / マイグレーション: 何を実行する必要があるか、既存データの互換性、バックフィルが必要かどうか。
• 運用上の振る舞い: 何が実行されるか、いつ実行されるか、障害がどのように可視化されるか、運用者が何を設定する必要があるか。
• 検証: 確認済みの手動チェックと、真にマージ後に行うチェック。
• 未解決の依頼: 未解決の製品またはリスクの選択。

小さなバグ修正では、単純に次の形式を使用できます。

## Root cause

## Fix

## Verification

公開前の確認

1. すべての主張が現在の差分、テスト、PR状態、または自分が実行したコマンドに基づいていることを確認します。
2. 最初の画面だけを読んでみます。問題、変更理由、新しい現状が明確に述べられている必要があります。
3. 歴史的な説明、チェンジログ形式の実装記録、繰り返しの説明、無関係な作業を削除します。
4. マイグレーション、デプロイ、シークレット、ダッシュボード、マージ後のアクションが明示的かつ実行可能であることを確認します。
5. 音読してみます。監査報告書のように聞こえるのではなく、チームメイトに変更を説明している人のように聞こえるべきです。
6. プッシュのたびに、PR本文を新しい差分と比較し、振る舞い、残りのセットアップ、検証ステータスが変更された場合は更新します。

ソース

このコピーは .agents/skills/ の下で編集します。pre-commitフックがそれを .claude/skills/pr-description/ にミラーリングします。ミラーを直接編集しないでください。