review-walkthrough

レビューの進め方

シニア開発者が同僚を指導しながら進めるように、プルリクエストをレビューします。変更の各部分と、その周辺のコードについて、レビュアー自身でコードを変更できるようになるまで説明します。各判断をレビュアーに委ね、最後にレビュアー自身の名前で投稿する GitHub レビューを1件作成します。コードは作者が残した状態のままにします。加えたい変更はすべて指摘事項にします。

すべて writing-lean に従って記述します。指摘事項、要約、投稿方法については REVIEW.md に記載されています。GitHub の呼び出しはすべて GITHUB.md に記載されています。

進めるペースはレビュアーが決めます。 ステップ3以降は、完了条件を満たし、 レビュアーが次へ進むよう伝えた時点でステップを終了します。回答しただけでは指摘事項が確定するだけで、ステップは終了しません。準備ができたか確認してください。

1. プルリクエストを特定する

引数はプルリクエストの番号または URL です。この進め方では、関連付けられた Issue、説明、チェック、過去のレビューを確認するため、プルリクエストが必要です。指定されていない場合は停止し、open-pr を提案します。

番号、リポジトリ、ベース、ヘッド SHA、作者、クローズする Issue を記録します。エージェントが作成したものかどうかも確認します。判断材料は、copilot/ ブランチ、ボットの作者、コミットのエージェント共同作成者です。

レビュアーがこのプルリクエストを以前にレビューしている場合は、フォローアップレビューです。前回のレビューが対象としたコミットを記録します（GITHUB.md）。レビュー対象の差分は、そのコミットからヘッドまでの差分です。該当するコミットがない場合は、ベースからの差分です。

完了条件：これらすべてが記録され、レビュー対象の差分が特定されていること。

2. バックグラウンド作業を開始する

レビュアーがステップ3に回答している間に作業が進むよう、次の処理をバックグラウンドのサブエージェントとして実行します。

• code-review でレビュー対象の差分を確認します。要件は、クローズする Issue とそのエージェント向けブリーフです。フォローアップレビューの場合は、前回のレビューの指摘事項も含めます。文書化された標準として house-rules と writing-lean を Standards ソースに追加します。これらはコードの臭いに関する基準より優先されます。code-review がインストールされていない場合、サブエージェントはクローズする Issue とエージェント向けブリーフ内のすべての受け入れ条件をレビュー対象の差分と照合し、それぞれについて満たしている、一部満たしている、または満たしていないと報告します。
• チェック。 プルリクエストのチェックを読みます。成功したチェックは、そのまま引用します。ローカルでは、失敗したチェックと、CI で実行されない文書化済みのチェックのみを、リポジトリの AGENTS.md に記載されたコマンドで実行します。
• 過去のスレッド。 すべてのレビュースレッドを、レビュアーを問わず取得し、返信もすべて読みます。各未解決スレッドについて、その後のコミットを踏まえて、対応済み（対応したコミットも記録）、一部対応済み、未対応、または適用されなくなった、のいずれかに分類します。解決済みのスレッドごとに、修正を確認する返信があるかどうかも記録します。

完了条件：3つすべてが実行中であること。

3. レビュアーについて把握する

gh と git の情報から、このスキルを呼び出している人を特定し、1回のやり取りで次の点を確認します。

• このコードベースにどの程度詳しいか
• レビューの目的（全般、正確性、セキュリティ、パフォーマンス、またはこの領域の学習）
• プルリクエストの作者かどうか

レビュアーが作者の場合、レビューイベントにどのような制約があるかをこの時点で伝えます。REVIEW.md を参照してください。

レビュー対象の差分が変更行数で約400行を超える場合、または多数のファイルに触れている場合は、先へ進む前に分割を依頼することを勧めます。フォローアップレビューでは、代わりにそのまま進めることを勧めます。レビューへの回答を含むコミットは、うまく分割できないことがよくあります。

回答に応じて、各ステップでどれだけ詳しく説明するか、どの指摘事項を先に扱うかを決めます。たとえば、セキュリティレビューでは情報漏えいを最初に扱います。

完了条件：レビュアーが回答し、分割を勧めた場合は分割するかどうかも決めていること。

4. 手順を計画する

code-review の指摘と先行するスレッドを待ってから、それらとレビュー対象の差分に基づいて手順を計画します。code-review とスレッドで以前の指摘について意見が異なる場合は、スレッドの返信を優先します。レビュー担当者による後の判断が反映されているためです。共通の基盤（ヘルパー、コントラクト、データ構造）から周辺やインターフェースへと計画を並べ、各手順が前の手順の上に成り立つようにします。重大な指摘がある手順には十分な時間を割き、問題のない箇所は隣接する手順にまとめます。

ファイル名を含めて、手順を番号付きリストで1行ずつ示し、レビュー担当者が手順の順序変更、統合、省略をできるようにします。その後、残りの仕様、ローカルテスト、ドラフト作成と投稿の手順を追加します。

完了条件 レビュー担当者が計画を承認し、レビュー対象の差分に含まれるすべてのファイルが、いずれかの手順またはレビュー対象外リストに含まれていること。

5. 各手順を確認する

各手順は、次の順で説明します。

1. 目的：このコードが存在する理由と、解決する問題。
2. 仕組み：リンクだけでなく、コードそのものを示します。説明するコードブロックは、それぞれ該当する行への見出しまたはリンクの下に、フェンス付きコードブロックで原文のまま引用し、指摘や論点に該当する行に // ← マーカーを付けます。定型部分のみ省略し、省略したことを明記します。リンクだけでは追いにくいため、レビュー担当者が後でこのコードを変更できるよう、周辺システムについても十分に説明します。
3. 重要な点：リスク、落とし穴、プルリクエスト以前からある問題。
4. テスト範囲：このコードを検証する仕様と、具体的な不足箇所。
5. ローカルで試す：動作を確認する簡単な方法。この手順でユーザーに見える動作が変わる場合は、アプリの実行にコストがかかり、依頼された変更が同じ箇所に及ぶ場合を除き、レビュー担当者とすぐに動作確認します。その場合は、延期を提案します。それ以外のすべての項目は、ドラフトのローカルテストチェックリストに追加します。

以前のスレッドはそれぞれ、そのコードを扱う手順で取り上げます。対応した場合はその旨を記し、対応しない場合は引き継ぐことを提案します（REVIEW.md を参照）。該当しなくなった場合は、レビュー担当者の判断に委ねます。

各手順の最後にラウンドを設けます。REVIEW.md と同じ番号で、提案する指摘をそれぞれ記載し、推奨案を添え、「はい」と答えるとその提案が承認される表現にします。その後に「質問はありますか。それとも次の手順に進みますか？」と尋ねます。

❓ **F3** - **<finding title>**: <the problem, and why it matters>

➡️ <your recommended fix, and its label and blocking status>

合意した指摘は、その都度ドラフトに追加します。

完了条件 レビュー担当者の質問に回答し、すべての指摘について合意または却下がなされていること。

6. 残りの仕様

各手順で取り上げなかった仕様ファイルと、再接続時や失敗時にのみ実行されるパスなど、複数の手順にまたがる不足箇所を確認します。最後にラウンドを設けます。

完了条件 レビュー対象の差分に含まれるすべての仕様ファイルについて説明し、すべての指摘について合意または却下がなされていること。

7. ローカルテスト

ローカルテストのチェックリストを提示し、レビュー担当者と今すぐ実行するか、依頼された変更が反映されるまで保留するかを提案します。

完了条件 レビュー担当者がチェックリストを実行するか、延期を選択していること。

8. ドラフト作成と投稿

REVIEW.md に従って、概要とコメントのドラフトを作成し、イベントを提案して投稿します。

完了条件 レビューが投稿されているか、レビュー担当者が投稿できるよう保留されており、その URL がレビュー担当者に示されていること。

9. 振り返り

チャットで、セッションで説明したコードベースの概念をそれぞれ1行で振り返り、レビュー担当者が対象領域の全体像を把握できるようにします。対応済みで未解決の以前のスレッドごとに「Addressed in <sha>」と返信して解決することを提案し、それぞれレビュー担当者に確認します。

完了条件 レビュー担当者が振り返りを確認し、提案があれば回答していること。