PR Viz

指定した PR を図中心のHTML1枚にして tmp/visual/ に書き出す。レビュワーとレビュイーが、GitHub の差分を開く前に「何を・なぜ・どこを変えたか」と「どこを重点的に見るべきか」を掴むための読み物である。

良し悪しの断定と修正指示は書かない。それは /code-review の担当で、この資料は判断の材料を並べるところで止まる。

手順

上から順に実行する。承認を求める場面は無い。節構成が固定なので、起動後は最後まで自律で進める。

1. 対象PRを決める：引数に番号があればそれを対象にする。無ければ gh pr view --json number で現ブランチに紐づく PR を対象にする。どちらでも PR が特定できなければ、資料を作らずその旨を伝えて終わる

2. 材料を読む：下のコマンドで本文・ファイル一覧・全差分を取る。PR本文が Issue を参照していれば gh issue view <Issue番号> も読む

   gh pr view <PR番号> --json number,title,body,files
   gh pr diff <PR番号>

   これ以外は読まない。設計書・変更ファイルの周辺コード・レビューコメント・他Skillの出力は材料に入れない。PRとして提示されたものだけで全体像が掴めるかどうかを、資料がそのまま映すためである

3. 固定4節を書く：後述の節構成に従う。.claude/skills/html/SKILL.md を Read し、その「デザインシステム」「図」の規則で書く。.claude/skills/html/design-system/ を tmp/visual/design-system/ へコピーし（既にあれば上書きしない）、HTML からは ./design-system/document.css などを相対パスで読む。/html の「基本構成」は使わず、4固定節で上書きする。図は inline SVG の手書きのみ。節の半分以上を図にし、ノードの関係が一直線の内容は図にせず表か箇条書きにする

4. 描画を確かめて直す

   1. tmp/visual/ で python3 -m http.server 8765 --bind 127.0.0.1 をバックグラウンド起動する（navigate は file:/// を開けない。ポートが埋まっていたら別の番号にする）
   2. mcp__claude-in-chrome__navigate に http://127.0.0.1:<ポート>/<出力ファイル名> を渡し、computer の screenshot で見る。入りきらなければ下へ scroll して続きを撮る（戻って撮り直さない）
   3. 文字のはみ出し・線と文字の重なり・矢印が箱に刺さっていない箇所を直す。直したら navigate を呼び直す
   4. 確認が終わったらサーバを停止する

   ブラウザのツールが使えない環境では、崩れを見ていない旨を明記して渡す

5. 図だけで要点を言えるか確かめる：スクリーンショットを見ながら、本文を読まず図と見出しだけで各節の要点を言えるかを確かめる。言えない節は図が本文の飾りになっているので、図を描き直す。あわせて崩れが残っていないことも確かめる

6. 出力先のパスを伝える：配布はしない。Artifact として公開せず、PR にも貼らない。資料がPRに残ると、あとから差分が変わっても古い断面が正典のように参照されるためである

節構成

4節で固定する。増やさない。

• 変更の背景・目的（なぜ）：PR本文と関連Issueから、この変更が要る理由を書く。差分からは読み取れないので、どちらにも書かれていなければそう書く
• 変更の全体図：層・コンポーネント単位で描く。ファイル単位では描かない（ファイルの並びは GitHub の差分表示と同じで俯瞰にならない）
• 振る舞いの before / after：変更の前後で、利用者や呼び出し側から見て何がどう変わるかを対比で見せる
• 重点確認ポイント：後述の根拠だけで選ぶ

該当が無い節は、空欄にせず**「なし」と理由を書いて閉じる**。空欄のままだと、読者は「検討していない」のか「対象外」なのかを区別できない。

重点確認ポイントの選び方

重点に上げてよいのは、次のどれかに当たる箇所だけである。

1. 説明と食い違う、または説明されていない変更：PR本文・関連Issue の説明に無い、または説明と食い違っている箇所
2. 高リスクな変更の種類にあたる箇所（下記）
3. テストの差分が無い振る舞いの変更：振る舞いを変えているのに、対応するテストの差分が無い箇所。既存のテストで守られているかは差分だけでは分からないので、断定せず確認の対象として挙げる

• 権限・認証：IAMポリシー、ロール、トークンの検証、公開範囲
• 公開APIや外部インターフェース：エンドポイント、リクエスト・レスポンスの形、CLIの引数
• データの削除・スキーマ変更：DELETE を伴う処理、カラム・テーブルの追加削除、移行
• エラー処理・リトライ：catch の握りつぶし、リトライ回数・待ち時間、タイムアウト

上の番号順に並べ、最大3件まで載せる。候補がそれを超えたら、載せずに残りの件数だけ添える。多く並べるほど、どれから見ればよいかが分からなくなるためである。

差分行数の多さは根拠に使わない。大量の定型変更が上位に来て、重要度と逆転するためである。

全差分を読み切れなかったとき

読んだ範囲と未読ファイルを、資料の先頭に明記する。黙って落とすと、見ていない箇所が「重点なし」と読まれる。

出力先

• ディレクトリ：tmp/visual/（無ければ作る。git 管理外）
• ファイル名：YYYYMMDD-pr-<番号>-<題名のケバブケース>.html
• 日付：date +%Y%m%d で取る
• 既存ファイル：上書きしない。同名なら末尾に -2 を足し、それも在れば空いている番号まで増やす

使用方法

/pr-viz 123   # PR #123 を資料にする
/pr-viz       # 現ブランチに紐づくPRを資料にする