pr-viz

# 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番号>` も読む ```bash gh pr view <PR番号> --json number,title,body,files gh pr diff <PR番号> ``` **これ以外は読まない**。設計書・変更ファイルの周辺コード・レビューコメント・他Skillの出力は材料に入れない。PRとして提示されたものだけで全体像が掴めるかどうかを、資料がそのまま映すためである 3. **固定4節を書く**：後述の節構成に従う。雛形 `.claude/skills/vis/assets/template.html` を出力先へコピーして中身を差し替え、図は `.claude/skills/vis/references/figure-patterns.md` の骨格を土台にする。本文の量と図の描き方は `.claude/skills/vis/SKILL.md` の「書くときの規約」に従う 4. **描画を確かめて直す**：`.claude/skills/vis/SKILL.md` の「描画を確かめて直す」を Read して、そのとおりに実行する 5. **図だけで要点を言えるか確かめる**：`.claude/skills/vis/SKILL.md` の「最終検査」を Read して、そのとおりに実行する 6. **出力先のパスを伝える**：配布はしない。Artifact として公開せず、PR にも貼らない。資料がPRに残ると、あとから差分が変わっても古い断面が正典のように参照されるためである > [!IMPORTANT] > **（AI・必須）** `.claude/skills/vis/SKILL.md` のうち正典として従うのは、手順3〜5で名指しした「書くときの規約」「描画を確かめて直す」「最終検査」の3節だけである。**他の節には従わない**。そのうえで、下の3点は `/pr-viz` の側が上書きする。 > > | `/vis` の規定 | `/pr-viz` での扱い | > | ---------------------- | -------------------------------- | > | 節の数の既定 | 4固定 | > | 見出し構成の承認を取る | 取らない。節構成が固定だから | > | 成果物をファイルで送る | 送らない。出力先のパスだけ伝える | ## 節構成 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を資料にする ```