review-walkthrough

レビューのウォークスルー

現在のブランチの自己完結型 HTML ウォークスルーを生成します。最終的な差分を論理的なステップに分け、説明と重要なレビュー所見を含めます。理解しやすいグループ分けと読む順序を選択します。コミット順に従う必要はありません。Claude Code では /review-walkthrough:review-walkthrough、Codex では $review-walkthrough として呼び出します。

ブランチの差分を取得する

ユーザーがベースを指定している場合は、それを使用してください。指定がない場合、PR メタデータを取得できるなら、現在開いている PR のベースを使用してください。PR がない場合は、git symbolic-ref --quiet --short refs/remotes/origin/HEAD または設定済みのリモートで同等のコマンドを使って、リポジトリのデフォルトブランチを特定してください。main と決めつけないでください。選択したベースが見つからない場合や曖昧な場合は、別のブランチを黙って選ばず、ベースを尋ねてください。

git rev-parse --verify --end-of-options "${ref}^{commit}" を使ってベースと HEAD をコミット ID に解決し、git merge-base でマージベースを計算してください。完全なパッチを git diff --no-ext-diff --no-textconv --no-color --src-prefix=a/ --dst-prefix=b/ "$merge_base" "$head_sha" -- で取得してください。変数の初期化と、その変数を使うコマンドの実行は、同じシェル呼び出し内で行ってください。シェル変数はツール呼び出しをまたいで保持されません。チェックアウトの外にある一時ファイルにパッチを保存し、実際のパスを保持してください。Git エラーが発生した場合、またはパッチが空の場合は停止し、結果を説明してください。

この対象範囲には、取得した HEAD までのコミット済み変更が含まれます。除外される未コミットの作業があれば、その旨を記載してください。ブランチを切り替えたり、チェックアウトをリセットしたり、レビューの準備のためにソースファイルを変更したりしないでください。ユーザーから特定の出力先を指定された場合を除き、生成データと HTML はチェックアウトの外に置いてください。生成されたレビュー成果物を取得対象のパッチに含めてはいけません。

GitHub PR の場合は、そのメタデータから owner、repo、pr_number、head_sha を取得してください。PR の HEAD が取得した HEAD と一致し、選択したベースが PR のベースと一致する場合に限り、これらを含めてください。それ以外の場合は null を使用し、コメントのエクスポートを利用できない理由を説明してください。認証やネットワークリクエストに失敗しても、PR が存在しない証拠にはなりません。ベースを特定できない場合は、失敗を報告してベースを尋ねてください。ユーザーがベースを指定した場合、または PR がないことを確認した場合は、GitHub へのアクセスは任意です。

レビューの構成

変更されたファイルと、それらを評価するために必要な周辺のソース、テスト、設定、依存関係のメタデータを確認します。レビューは読み取り専用にしてください。ウォークスルーを作成するだけのために、プロジェクトのテストを実行したり、依存関係をインストールしたりしないでください。

関連ファイルを、1つの概念を扱うステップごとにまとめます。定義をそれを使用するものより前に配置し、コンポーネントを接続する配線は接続先のコンポーネントの後に、テストは対象の後またはその隣に配置します。キャプチャしたパッチに含まれるファイルごとの完全な差分を、それぞれ厳密に1つのステップにそのままコピーします。ファイルをステップ間で並べ替えることはできますが、パッチの分割、書き換え、省略、捏造はできません。テキストの差分がない場合も、リネーム、バイナリ、モード変更の項目を保持します。バイナリの概要は変更されたファイルを特定するものであり、そのペイロードはこのレビューの対象外です。

各ステップにつき1つの説明を記述します。通常は50～150語で、変更の目的、設計上の選択、トレードオフ、他のステップとの関連を扱います。実際の識別子を参照してください。各ステップにつき1つのレビューリストを作成し、コードで裏付けられるバグ、セキュリティ、検証、API 設計、パフォーマンス上の問題を記載します。軽微な問題も省略せず、重大度を付けて報告してください。問題のないステップには空のリストを使用します。

説明とレビュー本文は HTML フラグメントです。構造には <p>、<strong>、<em>、<code>、<pre>、<ul>／<li> を使用します。文章やスニペット内のリテラルの < と > は、それぞれ < と > に置き換えます。バッククォートと Markdown のフェンスは、ここではリテラルテキストです。サポートされているインラインタグには、<sup>、<sub>、<kbd>、<del>、<a href="https://…"> も含まれます。ページはフラグメントをサニタイズし、PR コメントを作成する際に Markdown に変換します。安全なリンク先だけが保持されます。任意の属性、スクリプト、画像は保持されません。表はセル区切り付きのテキスト行として出力され、キャプションと行の順序は保持されます。段落、リスト、コードブロックで十分に表現できる場合は、それらを優先してください。

指摘事項は、同じステップ内のファイルと、そのファイルの表示差分内の行にアンカーします。追加または新規ファイルのコンテキストには side: "RIGHT"、削除または旧ファイルのコンテキストには side: "LEFT" を使用します。範囲を指定する場合、line と end_line は同じ側の1つのハンク内で指定します。複数のステップにまたがる指摘事項は、対象のファイルがあるステップに記載するか、アンカーなしのままにします。アンカーなしの指摘事項も表示されますが、インライン PR コメントにはできません。

アーティファクトをレンダリングする

ファイル書き込みツールを使って、以下のフィールドを含む JSON オブジェクトを作成します。リテラルのパッチは、シェル展開を行わず JSON 文字列データとして保持してください。

フィールド	値
title	機能またはレビューのタイトル
steps	sha（step-1 のようなステップ ID）、message（ステップのタイトル）、files（パッチ内の順序で並べたパス）、diff（ファイルごとの完全なパッチ）を含むオブジェクトの配列
explanations	各ステップに対応する HTML 文字列
reviews	各ステップに対応する指摘事項の配列。各指摘事項には severity（high、medium、low のいずれか）、title、HTML の body を含めます
pr_meta	owner、repo、pr_number、head_sha を含むオブジェクト、または null

アンカー付きの指摘事項には file、line、side も含め、必要に応じて end_line を指定します。 3 つの配列は同じ長さにし、各要素を対応させます。ファイルパスは、a/ または b/ のプレフィックスを除いた diff ヘッダーと一致させます。ファイル名が変更されている場合は、新しいパスを使用します。両方の側に同じ行がある場合に曖昧にならないよう、side を明示的に指定してください。

このレビュー用に作成した実際のパスを指定して、同梱のレンダラーを実行します。

uv run --no-project {baseDir}/scripts/render_walkthrough.py \
  --input /tmp/data.json \
  --diff /tmp/captured.patch \
  --output /tmp/walkthrough.html

レンダラーはデータを検証し、各ステップのパッチと取得した完全な diff を比較し、アンカーを確認したうえで、同梱のテンプレートに結果を安全に埋め込みます。報告された入力エラーを修正してください。レンダラーを迂回したり、別のページを生成したりしないでください。

ブラウザーを利用できる場合は、macOS では open、Linux では xdg-open を使って出力を開き、ユーザーにそのパスを伝えてください。ヘッドレス環境では、開かずにファイルの場所を報告してください。PR メタデータがある場合、ページ上で選択したコメント用の gh api コマンドをコピーできます。このコマンドは実行されず、GitHub に何かを投稿することもありません。Comment と Request Changes では、コマンドをコピーする前にレビューの要約が必要です。Approve では要約は任意です。