pr-explainer

PR Explainer

レビュー担当者がPRの背景を理解できる、変更内容、重要な理由、仕組み、システム内での位置づけ、検証方法を説明する、ローカルで完結するHTMLページを作成します。

必須のワークフロー

1. HTMLを書く前にPRを理解する

   • PRのタイトル／番号、ブランチ、利用できる場合はリンク、ベースブランチ、コミット範囲、変更ファイル、すでに実施された検証を収集します。
   • git status --short で現在の状態を確認します。
   • git log --oneline -n 10 で最近のコミットを確認します。
   • git diff <base>...HEAD --stat と git diff <base>...HEAD で変更範囲を確認します。
   • 主要な変更が1つのコミットにまとまっている場合は、git show --stat <commit> と git show <commit> で確認します。

2. 説明の流れを組み立てる

   • ファイルを生の差分順に説明しないでください。
   • 可能な場合は、次の順序で変更を説明します。
     1. 問題
     2. システムのコンテキスト
     3. 変更前後のデータまたは制御フロー
     4. 重要なコード変更
     5. テスト／ビルド／手動確認による証拠
     6. レビュー担当者向けの要点
   • 変更ファイルを、コア動作、配線／統合、テスト、リリースメタデータ、付随的なノイズに分類します。
   • PRの説明に役立つファイルだけを取り上げます。

3. わかりやすく説明する

   • 平易な言葉、短いセクション、具体的な変更前後の例、小さく焦点を絞ったコードスニペット、図、補足を使います。
   • 実装の詳細に入る前に問題を説明します。
   • 略語やパッケージ固有の用語は、使う前に定義します。
   • 差分全体をそのまま載せたり、レビュー担当者が内部事情をすでに知っていると想定したりしないでください。

4. ローカルで完結するHTMLファイルを作成する

   • 生成ファイルは .pr-review/ に配置します。
   • CSSとコンテンツをすべて1つのHTMLファイルにまとめます。
   • デフォルトでは .pr-review/ をコミットしないでください。
   • 生成したレビュー用ページがコミットに含まれないように、リポジトリのignoreルールまたは .git/info/exclude の使用を優先します。

HTMLの推奨構成

PRに明らかに適した別の説明順序がない限り、次の構成を使用します。

1. ヒーロー

   • PR番号／タイトル、1文の概要、ブランチ／リンク／ステータス。
   • 変更ファイル数、追加テスト数、影響を受けるパッケージなどの小さな指標。

2. 問題

   • 変更前の動作。
   • それが不適切、わかりにくい、不足している、またはリスクがある理由。

3. システムのコンテキスト

   • プロダクトまたはアーキテクチャ内で変更が位置する場所。
   • 上流の呼び出し元、下流の動作、変更を加える層として適切な理由。
   • 意図的に変更していない動作。

4. 変更前後のフロー

   • PRでフロー、状態、所有権、権限、リクエスト処理、データ変換、またはコンポーネント間の関係が変わる場合は、変更前と変更後の経路を視覚化します。

5. コードの説明

   • 段階を追った説明の流れ。
   • 重要なファイルだけに絞った差分。
   • 各スニペットの役割と必要な理由を説明します。

6. テスト／検証

   • 追加または更新したテスト。
   • テスト、ビルド、型チェック、リンティング、または手動検証に実行したコマンド。
   • 関係のない警告や失敗があれば記載します。

7. レビュー担当者向けの要点

   • PRを理解するために役立つ、最も簡潔な考え方。
   • 実際の差分をレビューする際に注目すべき点。

図

理解の負担を軽減できる場合は図を追加します。外部依存関係を使うより、シンプルなHTML／CSSの図を優先します。

適した図の種類：

• リクエストフロー：クライアント → サーバー → ハンドラー → サービス → 結果
• 変更前後の経路：壊れた経路と修正後の経路
• 所有権マップ：パッケージ／モジュールの責務の境界
• データ変換：入力 → 正規化された形式 → 出力
• 状態遷移：保留中 → 実行中 → 完了／エラー

各図は「これによってレビュー担当者は何をより早く理解できるか」に答える必要があります。

焦点を絞った diff スニペット

巨大なパッチではなく、説明の流れに沿ってスニペットを提示します。重要なスニペットにはそれぞれ次を含めてください：

• ファイルパス、
• 関連する追加/削除行のみ、
• 追加/削除の視覚的なスタイリング、
• 短い説明、
• PR ストーリーへの結び付け。

次のパターンを使用します：

<div class="diff">
  <div class="diff-title">packages/example/src/file.ts</div>
  <pre>
<span class="del">- old behavior</span>
<span class="add">+ new behavior</span>
  </pre>
</div>

レビュアーは GitHub を開かずに PR を理解できるべきですが、このページは最終的な完全な diff レビューの代わりになるものではありません。

検証要件

最後に証拠を示します。可能な場合は正確なコマンドを含めてください。例えば：

pnpm --filter @scope/package test path/to/test.ts -- --run
pnpm turbo build --filter ./packages/package

検証を実行しなかった場合は、その旨を明確に述べ、推奨されるコマンドを列挙してください。

最終チェックリスト

ページを完成とみなす前に、次が含まれていることを確認してください：

• 明確な一文の要約、
• 問題の記述、
• 変更前/変更後の説明、
• より広いシステムコンテキスト、
• 有用な場合は視覚的な図、
• ステップバイステップのコードウォークスルー、
• ファイルパスを含む焦点を絞った diff、
• テストと検証コマンド、
• レビュアーへの要点、
• 自己完結型の HTML/CSS、
• .pr-review/ に保存されている、
• 明示的に要求されない限りステージまたはコミットされていない。

デフォルトの出力

PR エクスプレイナーを作成するよう依頼された場合、.pr-review/*.html ファイルを生成または更新し、次を要約してください：

1. 出力パス、
2. 対象となる PR ストーリー、
3. 含まれる主要なセクション、
4. 含まれる検証証拠、
5. .pr-review/ が未追跡のままか、除外されているか。