review-pr
他の人が出した PR をレビューし、総括コメントとインラインコメントをセットで GitHub へ投稿する。レビュー結果はまず会話に出し、ユーザーの GO を得てから投稿する。ユーザーが /review-pr を打ったときだけ動く(AI からは呼べない)。--deep を付けると、レビューの実施をサブエージェントの並列に差し替える。自分が出した PR の点検・仕上げは /finalize-prs の
SKILL.mdhome/.claude/skills/review-pr/SKILL.md
GitHub他の人が書いた PR をレビューし、総括コメント + インラインコメントを1つのレビューとして GitHub へ投稿します。
指摘を受ける側の /resolve-human-reviews と対になります。書き込みの向きが逆なので、混同しないこと。
/resolve-human-reviews |
このスキル | |
|---|---|---|
| 対象 | 自分の PR に付いた指摘 | 他の人の PR の差分 |
| やること | コードを直す | 指摘を書いて投稿する |
| GitHub への書き込み | しない | する(総括 + インライン) |
進め方
1. 対象 PR の特定と、レビューしてよいかの確認
- 引数の PR 番号 / URL から
gh pr view <PR> --json number,title,author,state,isDraft,baseRefName,headRefName,body,changedFiles,urlを引く - 作成者が自分でないことを確かめる。自分の PR なら
/finalize-prsの領分なので、このスキルは使わない gh repo view --json nameWithOwner -q .nameWithOwnerでOWNER/REPOを取る- draft でもレビューしてよい。ただし本人が仕上げ途中の可能性があるので、報告時に draft である旨を添える
- PR に既に付いているコメントを全部読む。 インライン(
pulls/<PR>/comments)・PR のコメント欄(issues/<PR>/comments)・レビュー本文(pulls/<PR>/reviews)の3か所。ほかのレビュアーの指摘や作成者の補足を知らずに書くと、同じ指摘を重ねたり、決まったことを蒸し返したりする。課題のコメントとあわせて、PR と課題の経緯を踏まえてレビューする。本文は全文を読み、一覧のために切って取らない(references/re-review.mdの「返信は全文を読む」) - PR 本文は、貼られた画像と動画まで開いて見る。 文章だけでは、作成者が画面で何を確かめたかが分からない。スクリーンショットと動画は、その確かめた画面そのもの。差分・課題の受入基準・QA の指摘と照らし、文言・状態・どの画面かが食い違っていないかを見る。PR のコメントに貼られたものも同じ
github.com/user-attachments/assets/...は認証が要る。curl -sSL -H "Authorization: token $(gh auth token)" -o <スクラッチパッドのパス> <URL>で落とす。動画は数 MB でも数分かかることがあるので、バックグラウンドで流して先に進む- 画像は Read で開く。動画は
ffmpeg -i <動画> -vf fps=1 <出力>/frame_%02d.pngで1秒ごとに切り出し、Read で開く - 報告の「どの観点で見たか」に、何枚・何本を開き、何と照らしたかを1行置く。開けなかったものは、開けなかったと書く
- 実際に、本文の文章だけを読んでレビューを投稿し、画像1枚と動画1本を開かないまま「見なかった領域」にも書いていなかった
自分の過去のレビューがあるかを、毎回引く。 あれば下記「再レビュー」へ入る。
gh api "repos/OWNER/REPO/pulls/<PR>/reviews" --jq '.[] | select(.user.login=="<自分>") | "\(.id) \(.submitted_at)"'
会話の記憶で判定しない。 同じ PR を2度目に呼ばれても、セッションが変わっていれば前回の投稿を覚えていません。
/review-pr <PR> は、いつ打ってもその時点の状態から続きを始められる形にする。 結果は毎回変わってよく(差分が動けば指摘も変わる)、同じコマンドで再実行できることが要件です。だから判定は記憶ではなく API で行う。
課題票を読み、PR の範囲と突き合わせる
差分を読む前に、PR が紐づく課題票を読む。 PR だけを見ていると、PR が「直した」と言っている範囲の中でしか正しさを判定できない。課題が求める範囲を PR が覆っているかは、課題票を読まないと分からない。
| 順 | やること |
|---|---|
| 1 | 課題を特定する。 PR のタイトル・本文の課題キーと URL から引き、課題管理ツール側の PR 欄も見る。PR タイトルのキーと課題管理ツールのキーは表記が違うことがある(よく触るリポジトリの対応は非公開側のルールが持つ。入口は user_context.md ) |
| 2 | 症状・再現手順・本来の挙動・受入基準を読む。課題のコメントも全部読む。 範囲や方針の決定(「表示も直す」「洗い出してひと通り直す」)は、本文ではなくコメントで出ることがある |
| 3 | 課題の主題を1文で言う。 件名と症状から、報告者が困っていたことを取り出す |
| 4 | 本来の挙動と受入基準を1項目ずつ並べ、PR の差分で満たされるかを見る |
| 5 | 満たされない項目の重要度を、主題に入るかと PR の区切りで決める。判定は review-code/references/severity.md の「差分の外は、課題の主題に関わるときだけ must」。PR が直した箇所が直し切れていないなら、PR の変更が目的を果たしていないので [must]。PR の区切り(作成者が直した範囲)の外にあるなら、次の PR で直すものとして [fyi] で渡す |
PR 本文の「対応範囲」をそのまま範囲として読まない。 作成者が直した箇所だけを書いているので、課題が求めていて直していない箇所は本文に出てこない。
実際に、本来の挙動に3つの表示が挙がっていた課題で、PR が直していたのは2つだけだった。PR 本文も2つの表示しか書いていなかったので、差分だけを読むと正しく見えた。課題票と突き合わせて初めて、残る1つに気づいた。ただし、その1つを must として投稿したのは誤りだった。主題(送る値と表示の食い違い)はこの PR で解決しており、残る1つは別 PR で対応すればよいものだった。
課題票が無い PR(依存の更新・雑務)は、この手順を飛ばし、報告に「紐づく課題票なし」と書く。must は「どうしてもこの PR の中でやっておいてほしいか」で決める(同じく severity.md の節)。課題票の記述の裏の取り方は Step 5の表と verify_before_asserting.md の「課題票の症状記述も裏を取る」が持つ。
2. そのリポジトリのレビュー規約を読む
prefix の語彙と意味はリポジトリごとに違う。 記憶で決めず、そのつど拾う。
PR 本文に「レビューのルール」等の節があれば、そこに書かれた prefix をそのまま使う(
imoだけは置き換える。下記)無ければ
.github/pull_request_template.md/CONTRIBUTING.mdを見るそれも無ければ、既存の PR に付いたコメントを読んで慣習を推定する
gh api "repos/OWNER/REPO/pulls/<直近のPR>/comments?per_page=20" -q '.[].body' | head -40慣習が読み取れなければ prefix を付けず、重要度を文章で明示する
投稿してよいのは [must] / [iaio] / [nits] の3つと、下に挙げる5種類の [fyi] だけ。 語彙がリポジトリごとに違っても、投稿するのは「直すべきか」を述べる指摘に限るという原則は変わらない。5種類の [fyi] はこの原則の例外で、直すかどうかは述べないが、作成者の次の判断を変える。
| 種別 | 扱い |
|---|---|
[must] / [iaio] / [nits] (直すかどうかを述べるもの) |
投稿する |
[ask] (質問) |
投稿しない。 相手に問いかけるかは、聞き方も含めてユーザーが決める |
[fyi] (参考情報) |
原則として投稿しない。 相手の行動を変えないうえ、指摘の中に混ざると読む量だけ増える。例外は下の5種類 |
投稿してよい [fyi] は、この PR では直さないが、作成者の次の判断を変えるものだけ。
[fyi] そのものは、PR の外での対応を渡すものと、PR の中の参考情報(読むだけでよい補足)の両方を含む語です。こちらが投稿するのは前者だけで、下の5種類はどれも PR の外で対応するものです。PR の中の参考情報は、投稿せず Step 7の報告に回します。
許す [fyi] |
例 |
|---|---|
| 同じ不具合を根本から防ぐリファクタ案(PR の範囲の外) | 日時を TZ の指定なしに扱えない形(共通の関数・Temporal)へ寄せる |
| 課題の症状と同じ原因で、ほかの箇所にも起きうる不具合(調べて見つけたもの) | 表示を直した箇所とは別に、選べる枠の判定もブラウザの TZ で時刻を読んでいる |
| PR が足した防御や判定が届かない経路が、main から残っているもの | ガードに外部の URL を止める判定を足したが、ログイン画面の push は判定を通らずに外へ移れる |
| PR の範囲の外で、今は直さなくてよい改善 | 触っていない隣の関数も、同じ書き方に揃えると読みやすい |
| 課題が求めているが、PR の区切り(作成者が直した範囲)の外にある項目 | 面接日時の表示7か所を直した PR に対し、課題が「ひと通り直す」とした表示のうち、ミーティングの日時がまだブラウザの TZ で出る |
1つの課題を複数の PR に分けて閉じるのは普通の進め方。 ここまでが1本の区切りだと読めたら、その外は課題が求めていても次の PR で直すものと見て、「この PR で直すか」を問う [iaio] にしない。
- 本文の最後に「この PR で対応する必要はありません」を1行置き、approve を止めないことを示す
- 根拠は実測で示す(動かした結果・
path:line・数えた件数)。推測だけの[fyi]は出さない - 1件1主題。リファクタ案と、ほかの箇所の不具合は別のコメントにする
- 直し方を添えるとき、それが PR 自身の差分の作りを変えるなら、その部分は
[iaio]に分けて差分の行に付ける。 「PR の直し方より良い」という評価は、PR の範囲の中への意見になる。[fyi]に混ぜると、作成者は PR の外の話として読み、この PR の作りを見直す材料にしない。実際に、ほかの操作に残る二重の送信を伝える[fyi]に、PR が足した「送った条件と同じなら止める」作りより別の形がよい、という段落を混ぜ、あとで[iaio]に移した - 置き場は、関係する行が差分にあればインライン、複数のファイルにまたがるなら PR コメント欄
- Step 7の報告では指摘と同じ一覧に並べ、GO を得てから投稿する
PR の範囲の外で見つけたものは、起票を勧めず [fyi] で作成者へ渡す。 起票はレビュアーの役目ではなく、課題にするかは作成者とチームが決める。報告で「別の課題が合う」と添えたり、課題の文案を作ったりしない。
それ以外の質問・参考情報として書きたくなったものは、ユーザーへの報告(Step 7)に回す。指摘として成立するなら [iaio] / [nits] に言い換えて投稿する。
ただし報告へ回すのは、こちらが調べて初めて分かることだけ。 PR 本文に「ここを確認してほしい」と書かれていても、PR を出した側が既に把握していることには答えない。
| 報告に書く | 書かない |
|---|---|
| 差分を読んで分かった影響(読み出し箇所の有無、既存テストの欠落) | マージ順・リリース順。出した側が組み立てた計画 |
| 規約や実装を当たって確かめた事実 | 相手が本文で自ら説明している前提の言い換え |
「聞かれたから答える」で判断しない。 本文の確認依頼は、たいていレビュアー全員に向けた念押しであって、こちらが調べ直す必要のあるものとは限らない。答える前に「これは自分が調べて初めて分かったことか」を見る。
imo は使わず iaio と書く
意見を述べる指摘は [iaio] (in AI opinion)にする。 リポジトリの規約が [imo] を定義していても変えない。何が意見に当たるか、[imo] との書き分けの表、iaio の語を開かない理由は references/posting.md の「 imo は使わず iaio と書く」にある。
3. 規約ドキュメントの本体を読む
差分を見る前に読む。 規約を知らないまま差分を読むと、目に付いた違いを規約と思い込んで指摘してしまう。
規約の本体は .claude/rules/ ではない。 ルール側は paths で対象を絞る入口で、中身は @docs/... の参照先が持つ。入口だけ読んで「規約違反」と書かない(Step 6)。
| 順 | やること |
|---|---|
| 1 | 置き場を実際に見る。ls docs/ で規約ドキュメントのディレクトリを特定する |
| 2 | 差分のファイルパスに paths がマッチする .claude/rules/** を集める |
| 3 | そこから参照されている docs/ 配下のファイルを辿る |
| 4 | 辿った先を並列で読む(1メッセージに複数の Read を並べる) |
置き場の名前はリポジトリごとに違う。 揃っている前提で決め打ちせず、毎回 ls docs/ で見る。よく触るリポジトリの置き場は、そのリポジトリのメモリに書いてある。
全部読まない。 数十本あることが多いので、差分が触れた領域に絞る。ただし絞った結果が10本を超えても、並列で読めば1往復で済む。
横断的な規約は、領域を問わず読む。 テストの書き方・命名・アーキテクチャの原則は paths で絞られないことがあり、領域別のドキュメントが「上書きする標準ルール」として参照している側にある。領域別だけ読むと、上書きされていない本則を見落とす。
照らすのは、そのリポジトリの規約だけ。 ~/.claude/ の個人の規約(ルール・スキル)との違いは指摘にしない。作成者はその規約を共有していないので、従う理由がない。
4. レビューの実施
--deep が付いていたら、この Step だけ references/deep.md に従う。 ほかの Step はこのファイルのとおり進める。
そのリポジトリのレビュースキルがあれば必ず委譲する( /review-code 等。.claude/skills/ と .claude/commands/ の両方を見る)。レイヤー構成と観点を知っているのはそちらなので、ここで自前の観点を組み直さない。
委譲しても Step 3は省かない。 規約の原文を自分で読んでいないと、返ってきた指摘を検証できない。
読みやすさ・削れるもの・テストの当て方・設計の形は、/review-code の「4つの観点で見る」と同じ pstack の原則を当てる。当てる原則と場面の対応はあちらにある。
差分の行だけで判定しない。 変更が乗る流れを、差分の外も含めて入口から出口まで辿る。手順は /review-code の手順3「変更が乗る流れを、入口から出口まで辿る」が持つ。他人の PR では、課題票の再現手順がその流れになる。base と head を別々の worktree に取り出し、両方で同じ流れを動かして差を見る(Step 5の「ビルド・テスト」と同じ取り出し方)。PR の説明が挙げる「直る理由」も、そのとき確かめる。
5. 断定する前に裏を取る
投稿は取り消せない。 指摘の根拠は、書く前に実物で確かめる( verify_before_asserting.md )。
| 確かめること | やり方 |
|---|---|
| 行番号 | gh pr diff の出力行番号を使わない。 新規ファイルはヘッダと先行ファイル分のオフセットが乗る。git show <ref>:<path> | grep -n <アンカー> でファイル単体から採る |
| ビルド・テスト | 「規約違反なし」「テストが通る」と書くなら実測する。ブランチを git worktree add <一時パス> origin/<head> --detach で取り出して流し、終わったら git worktree remove する |
| 規約の引用 | 規約ドキュメントの原文を読んで引く。「〜のはず」で書かない |
| 既存パターン | 「既存と不揃い」と言う前に、既存側を grep で数える。数えるのは base 側( git show <base>:<path> )。レビュー中は対象の PR が checkout されているので、作業ツリーを数えるとレビュー対象の差分を「既存」に数える。優勢な流儀の方が少数派だったことがある |
| PR 本文がリンクする先(関連 PR・課題管理ツールのチケット) | 開けるなら開く。 関連 PR はマージ済みかを見る。課題票は Step 1の「課題票を読み、PR の範囲と突き合わせる」で読んだうえで、症状・確認環境・受入基準を見、「確認できた環境」を「発生する環境の全て」と拡大解釈していないかと、本文の記述を全部「直す対象」として扱っていないかを確かめる( verify_before_asserting.md の「課題票の症状記述も裏を取る」) |
| 影響を主張する指摘の、運用の前提(「本番に出る」「マージ後に辿れない」) | コードではなく運用で決まる前提を、書く前に確かめる。マージの方式は main の直近のコミットで見る(親が1つで末尾に (#番号) が付くならスカッシュ。スカッシュでは PR のコミットは main から辿れない)。フィーチャーフラグは、出す環境での今の値を評価する(すでに ON なら、OFF の経路は誰にも表示されない) |
| PR が足した・直した仕様書と設計文書 | 全文の主張を1件ずつ実装と照らす(対象 API・値・テーブルの定義・テストのケース数)。食い違いは nits でも書く。文書は後から実装を調べる人が読むので、食い違うとどちらを信じるか決められない |
確信が持てないものは重要度を1段階下げる。 誤検知は相手の時間を奪ううえ、レビュー全体の信頼を落とす。
6. 書けた指摘を敵対的に検証する
ここで構えを切り替える。 Step 5までは「指摘が成立する根拠」を集めていた。ここからは自分が書いた指摘を壊しにいく。
続きは references/verify-findings.md の「6. 書けた指摘を敵対的に検証する」。
7. 会話で報告し、GO を待つ
投稿はここでは行わない。 重要度順に整理して会話へ出し、ユーザーの明示的な承認を得る( decide_or_ask.md )。
- 重要度ごとに畳んで出す。件数が多ければ表にする
- 投稿先の行(
path:line)を指摘ごとに決めておく。ここで確定していないと、投稿段で貼り直しになる - ユーザーが指摘を落とす・言い回しを変える判断をしたら、それに従う
- 投稿の可否は書く / 書かないを1件ずつ決めた一覧を示してから尋ねる。 判定は
references/verify-findings.mdの「成立しても、書く価値があるかを1件ずつ決める」。「must だけ」「全部」のように件数や重要度で切った選択肢は出さない。必要な指摘が重要度の低い側に入っていても、選択肢の切り方で落ちる
報告に入れるもの
ユーザーは自分でもレビューする。 指摘の一覧だけ渡すと、次に自分でレビューするときに再現できない。何を見て、何を見なかったかまで渡す。
先頭1行は結論。 ブロッカーの有無と、approve の見立てを言い切る。下記の1〜4はその後に続ける。
| 節 | 中身 |
|---|---|
| 1. どういう PR か | 冒頭に PR の URL を置く(読み手がそこから PR を開く)。続けて、その機能を知らない人が読んで分かるように噛み砕く(下記「どういう PR かは、初見の人に向けて噛み砕く」) |
| 2. どの観点で見たか | 観点・見たもの・結果を表で。指摘に至らなかった観点も載せる。課題票との突き合わせ(主題が解決するか、残る項目は何か)は必ず1行置く |
| 3. 指摘の一覧 | 重要度順。投稿先の行を添える |
| 4. 落とした候補 | 落とした理由とセットで1件1行(Step 6) |
5. ## approve の可否 |
見出しを立てて報告の最後に置く。下記「ユーザーへ伝える見立て」 |
どういう PR かは、初見の人に向けて噛み砕く
ユーザーはこの節を読んでから差分と指摘を読む。 機能の前提(誰が使えて、どこまで共有されるか)が分からないと、指摘がどれだけ重いかを決められない。
| 書くこと | 形 |
|---|---|
| 何の機能か | 誰が何のために使うかを1〜2行で |
| 機能の決まり | 誰が使えるか・どこまで共有されるか・上限など、指摘の前提になるものを表で |
| この PR が何を足すか | 画面で見えるもの(FE)、受け付ける API とデータの保存先(BE)を表で。内部の呼び名は「〜とは〜」で開く |
| 複数の PR を見たとき | それぞれの受け持ちと、相手との約束(API・値)を並べる |
差分の性質(新規追加 / 既存改修 / 契約変更)と規模は最後に1行で添える。
長さは決めない。 表で畳み、一般的な技術用語は開かない( plain_language_explanation.md )。
実際に、新機能の FE と BE の2本を2〜3行で説明して報告し、「初見者向けに噛み砕いて」と言われてから、機能の決まりと2本の関係を書き直した。
2が成長の材料になる。 「規約ドキュメントを6本読んだ」「既存101本を数えた」「CI の失敗が承認待ちか実害かを見た」は、指摘がゼロでも次のレビューに役立つ。逆に「見なかった領域」も書く。読み切れなかった箇所があるなら、そこは保証していないと分かる形にする。
土台は focus_insights_on_judgment.md 「代行するほど、渡す責任が増える」。本節はそれをレビューの報告に具体化したもの。
観点は水増ししない。 実際に見たものだけを書く。見ていない観点を並べると、裏取りの範囲を過大に伝えることになり、指摘そのものより害が大きい。
8. 総括コメント + インラインコメントを1レビューで投稿
payload を組む前に git fetch する。 規約を読み、差分を追い、反証しているあいだに、相手が直していることがある。
続きは references/posting.md の「8. 総括コメント + インラインコメントを1レビューで投稿」。
9. 投稿結果を確認する
gh api "repos/OWNER/REPO/pulls/<PR>/comments?per_page=100" \
--jq '.[] | select(.pull_request_review_id==<review_id>) | "\(.path):\(.line)\t\(.html_url)"'
ファイル単位のコメントを別に投稿したなら、pull_request_review_id が別になるので、投稿したときに返った id で引く。
意図した行に付いたかを1件ずつ見る。 行がズレていても API はエラーを返さず、無関係なコードに指摘が付いた状態になる。diff_hunk の末尾行を見れば、どのコードに付いたかまで確かめられる。
html_url はここで拾って報告へ回す( report_formatting.md )。確認と報告で2回叩かない。
再レビュー
過去のレビューがあるとき(Step 1の判定)の手順は references/re-review.md にある。 Step 1〜9は同じで、差分を merge-base から取り直す・前回の指摘が片付いたかを1件ずつ確かめる・返信に 👍 を付ける、の3つが増える。
承認は GitHub に書かず、見立てはユーザーへ渡す
是非の表明を GitHub に書かないことと、ユーザーに何も言わないことは別。 宛先で書き分ける。
| GitHub | ユーザーへの報告 | |
|---|---|---|
| 承認の操作 | しない。 event は COMMENT 固定で APPROVE / REQUEST_CHANGES は使わない |
— |
| 是非の表明 | 書かない(「LGTM」「マージして問題ありません」「良い実装だと思います」) | 伝える。 「approve して問題なさそう」まで踏み込む |
| 事実 | 書いてよい(「must はありません」) | 同じ |
| CI・テストの結果 | 書かない(下記「CI と approve は GitHub へ書かない」) | 書く |
承認するのはユーザー本人。 こちらは判断材料と見立てを渡すところまでで、ボタンを押さない。
must を投稿したら、自分の approve を取り下げる。 有効な approve が残っていると、must があるのにマージできる状態に見えるためです。取り下げは must の投稿の GO に含め、こちらで打ちます(ユーザーの指示)。付け直すのはユーザー本人です。コマンドは references/posting.md の「must を投稿したら approve を取り下げる」。
ユーザーへ伝える見立て
反証(Step 6)を通した結果から、次のどれかを報告の先頭1行で言い切る。
同じ結論を、報告の最後にも ## approve の可否 として立てる。 先頭は結論、最後は締めで役割が違う。先頭1行だけだと、後続の表や図に埋もれて届かない(実際に、指摘・観点・落とした候補の表が3つ続いた回で伝わらなかった)。
| 状況 | 伝えること |
|---|---|
must があり、コード変更が要る |
「今は approve を待ったほうがよい」と言い切る。 あわせて、どの指摘が直れば approve できるかを添える |
must があるが、コード変更を伴わない(PR 本文・タイトルの記述のみ) |
「コードは approve して問題ないが、〇〇(本文の記述)は直してほしい」と両立させる。approve をブロックしない |
iaio / nits だけ |
「approve して問題なさそう」と添える。 指摘は投稿するが、止める理由ではない |
| 指摘がゼロ | 「approve して問題なさそう」だけ伝える。 レビューは投稿しない(下記) |
must があるときこそ、件数だけでは足りない。 押すのはユーザー本人なので、何が残っていると押せないのかまで渡す。件数を数えるだけなら PR を開けば分かる。
指摘が2件以上あるなら、approve を止めているのがどれかを表で示す。 must が1件だけなら先頭1行で足りる。
| 指摘 | approve をブロックするか | 理由 |
|---|---|---|
| (指摘の要約) | する / しない | 1行 |
見立てには根拠を1行添える。 何を実測し、どの規約に照らしたか。根拠のない「問題なさそう」は、裏取りをしていない場合と区別が付かない。
コード変更を伴う must では、この2つを混ぜない。 「〇〇が直れば approve できる」という条件文は書いてよいが、コード変更を伴う must が残っている限り、結論の中に「approve して問題なさそう」という完了形の評価を入れない。
コード変更を伴わない must(PR 本文・タイトルの記述のみ)はこの限りではない。 コードに欠陥が無いなら、approve と「本文は直してほしい」は両立する。review-code/references/severity.md の判定表がそもそもコードの欠陥を対象にしているので、本文の事実誤りはどの重要度区分にも当たらない。must という重要度は「直すべきか」を表すのであって、「approve を止めるか」とは別の軸。
指摘がゼロなら投稿しない
中身の無いレビューを投稿しない。 「must はありません」だけの総括はレビュアーへ通知が飛ぶ一方、相手の行動は何も変わらない。
- Step 7の報告で「指摘なし。approve して問題なさそう」と伝え、そこで終える
- ユーザーが「その旨をコメントしておいて」と指示したときだけ投稿する
- 許した5種類の
[fyi]だけがあるときは、その[fyi]だけを投稿してよい(GO を得てから)。中身を持つので「中身の無いレビュー」には当たらない。総括は付けず、[fyi]のコメントだけを出す
総括に内訳を書かない
総括に書くのは件数だけ。 書き方の例・「インラインに置いています」も書かない理由・インラインに置けない指摘の例外は references/posting.md の「総括に内訳を書かない」にある。
レビューは直す候補だけを出す
書くのは「ここは直した方がよさそう」だけ。 良かった点・評価・所感は、総括にもインラインにもユーザーへの報告にも書かない。
approve の見立てと、見た観点は別枠。 どちらも評価ではなく事実なので、ユーザーへの報告には載せる(Step 7「報告に入れるもの」、上記「承認は GitHub に書かず、見立てはユーザーへ渡す」)。
| 評価(書かない) | 事実(報告に載せる) |
|---|---|
| 「設計は妥当だと思います」 | 「規約ドキュメントを6本読み、既存101本を数えた」 |
| 「テストが丁寧です」 | 「 must が1件あるので、それが直れば approve できそう」 |
「水増ししなければ1〜2行は添えてよい」ではない。 分量の問題ではなく、混ぜること自体をしない。
| 書く | 書かない |
|---|---|
直す候補( [must] / [iaio] / [nits] ) |
良かった点・評価・所感 |
許した5種類の [fyi] (Step 2) |
それ以外の参考情報 |
| approve の見立て(ユーザーへの報告のみ) | — |
| 裏を取った事実(規約の引用、既存の件数) | 「丁寧に書けています」「設計は妥当だと思います」 |
| — | CI の状態と approve の話(下記) |
評価に見えない書き方でも同じ。 「〜は規約に正面から沿っています」「〜は適切です」は、指摘ではなく評価なので落とす。
理由は3つある。
- 相手が読むのは何を直すか。評価が混ざると、直す対象を拾う手間が増える
- 褒めた箇所は「見た上で問題なしと判断された」と読まれる。 裏取りの深さは箇所ごとに違うので、この含意は渡せない
- 評価は是非の表明に近づく。GitHub 上で承認の是非を書かない(上記「承認は GitHub に書かず、見立てはユーザーへ渡す」)
CI と approve は GitHub へ書かない
どちらも PR を開けば見えるか、こちらが決めることではない。 主題ごとの書き分けと、例外( .github/ を触る PR)は references/posting.md の「CI と approve は GitHub へ書かない」にある。
コメント本文の書き方
土台は rules/concise_first_then_detail.md。ここではレビューコメント固有の事情だけを足す。
続きは references/posting.md の「コメント本文の書き方」。
長くなったら畳む
| 使うもの | いつ | 注意 |
|---|---|---|
| 表 | 同じ観点が3件以上(観点と所見、案の比較、影響範囲) | 1列目に長い値を置かない。 GitHub は内容幅で列幅を決めるので、先頭列がファイルパスや長い識別子だと残りの列が潰れる。短くできないなら箇条書きにする |
| Mermaid | 差分の羅列から読み取れない構造・関係・流れ | GitHub は ```mermaid フェンスをそのままレンダリングする |
続きは references/posting.md の「長くなったら畳む」。
出力の目安
- 報告は重要度順。ブロッカーの有無を先頭1行で断定する
- 同じ1行で approve の見立てを言い切り、報告の最後にも
## approve の可否を立てる(上記「ユーザーへ伝える見立て」)。mustがあっても出す - 投稿後は件数の内訳を出す。指摘本文を会話へ再掲しない(GitHub 側にある)
- URL は PR とインライン1件ずつを添える(
report_formatting.md)。Step 9の確認でhtml_urlも一緒に拾う - 良かった点は書かない(上記「レビューは直す候補だけを出す」)
やってはいけないこと
APPROVE/REQUEST_CHANGESを投稿すること。承認のボタンはユーザーが押す(上記「承認は GitHub に書かず、見立てはユーザーへ渡す」)- GitHub 上に「LGTM」「マージして問題ない」「良い実装だと思います」と書くこと。ユーザーへの報告では逆に、approve の見立てを必ず伝える
- approve の可否を先頭1行だけで済ませること。後続の表や図に埋もれる。報告の最後に
## approve の可否を立てる - コード変更を伴う
mustが残っているのに「approve して問題なさそう」と書くこと。条件を満たせば approve できるとしても、結論は「今は approve を待った方がよい」の形で言い切る。コード変更を伴わない must(PR 本文・タイトルの記述のみ)は除く。この場合は approve と「本文は直してほしい」を両立させる - 指摘がゼロなのにレビューを投稿すること。中身の無い通知になるので、報告だけで終える
- CI の状態や approve の話を GitHub へ書くこと。前者は PR に出ており、後者はユーザーと決めることなので、どちらもレビュアーへ渡す情報ではない(上記「CI と approve は GitHub へ書かない」)
- 良かった点・評価・所感を添えること。総括・インライン・ユーザーへの報告のいずれも、直す候補だけを出す
- コメントや返信を、本文を切った一覧で読んだことにすること。全文を読む(Step 1、
references/re-review.md) - PR 本文に貼られた画像と動画を開かずにレビューすること。作成者が画面で何を確かめたかは、文章だけでは分からない(Step 1)
- 課題票を読まずに、PR の差分と本文だけでレビューすること。課題が求めていて PR が直していない箇所は、差分にも本文にも出てこない(Step 1の「課題票を読み、PR の範囲と突き合わせる」)
- 課題の主題が解決しているのに、課題票の残りの項目を理由に
mustを付けること。PR が直した箇所の直し残しなら[must]、PR の区切りの外なら次の PR で直すものとして[fyi]で伝える - PR の範囲の外で見つけたものに、起票を勧めること・課題の文案を作ること。渡すなら許した5種類の
[fyi]で作成者へ(Step 2) - 許した5種類以外の
[fyi]を投稿すること。それ以外の参考情報は Step 7の報告に回す - 課題が求めておらず、この PR が持ち込んだのでもない話(main からある別の不具合)を
[iaio]で出すこと。この PR で検討すべき指摘として読まれる。許した5種類の[fyi]に当たるかを見て、当たらなければ報告に回す。課題が求めていて PR が直していない項目は、これに当たらない(Step 1の手順5のとおり、直し残しは[must]、区切りの外は[fyi]で伝える) - マージ順・リリース順をユーザーへ報告すること。PR 本文で問われていても、出した側が把握している(Step 2)
- ユーザーの GO を得ずに投稿すること。レビュアーに通知が飛び、取り消せない
- 敵対的検証(Step 6)を飛ばして投稿すること。書けた指摘をそのまま出さない
- Step 6を「確認」として通すこと。構えを変えずに読むと追認になる。壊しにいって初めて成立しない箇所が出る
- 敵対的な構えを文面へ持ち込むこと。壊す相手は自分の指摘であって、PR 作成者ではない(Step 6)
- 規約の原文を開かずに「規約違反」と書くこと。引用できないものは指摘にしない
gh pr diffの行番号をそのまま引用すること(Step 5)- 投稿してから形式を直せばよいと考えること。インラインは消せてもレビュー本体は消えない(下記「投稿し直すとき」)。形式は投稿前に確定する
- 総括だけ、またはインラインだけで済ませること
- Note ブロックを省くこと。1行の
[nits]でも付ける - PR 作成者へのメンションを省くこと。総括・インラインのすべてに、1行目として付ける
- prefix をコードスパンにすること、prefix と同じ行に本文を続けること(Step 8)
- 総括の件数に prefix を立てること。
[iaio]+ 「1件です」は、総括そのものが指摘に見える。地の文で「iaio が1件です」と書く [imo]と書くこと。意見の指摘は[iaio](Step 2)(iaio = in AI opinion)のように語の説明を添えること。同じレビュアーへ何度も出すので、毎回開くと邪魔になる(Step 2)- 自動生成ファイル(
*_mock.go、mock/配下等)へ指摘すること - 相手の書き方の好みを規約と偽って指摘すること。規約に無いものは
[iaio]以下にする - 件数を揃えるために指摘を水増しすること。反証で全部落ちたなら投稿せず、ユーザーへ「指摘なし」と伝えて終える(上記「指摘がゼロなら投稿しない」)
- 成立したことを、書く価値があることとみなすこと。作成者の次の行動か判断が変わるかを1件ずつ見る(
references/verify-findings.md) - 投稿の範囲を、件数や重要度で切った選択肢で尋ねること。書く / 書かないを1件ずつ決めた一覧を示す(Step 7)
- プロジェクトの規約から外れた指摘を、既存が同じ形だからと落とすこと。前例を添えて書く(
references/verify-findings.md) ~/.claude/の個人の規約との違いを指摘にすること。照らすのはそのリポジトリの規約だけ(Step 3)- マージの方式やフラグの値を確かめずに、影響や直し方を書くこと。スカッシュマージでは PR のコミットは main から辿れず、すでに ON のフラグの OFF の経路は誰にも表示されない(Step 5)
- 散文を長く積むこと。同じ観点が3件以上なら表、構造・流れなら Mermaid、根拠が長いなら
<details>に畳む - 1コメントに複数の主題を詰めること。相手がどれに対応済みか管理できなくなる
- 設計判断が絡むものを
suggestionで渡すこと。相手が考えずに適用できてしまう - 直し方を方針だけで書くこと。「〜を並べるとよいです」で止めず、変更後の形をコード片で示す。差分の外なら
path:lineを添えてコードブロックで置く - 動かして確かめていない直し方を、コード片で示すこと。コード片は作成者がそのまま当てる。前提が推測なら、確かめていないと書いて方針に留める(
review-code/references/severity.mdの「原因と直し方の案も、同じ強さで裏を取る」) - 差分とその直近だけを読んで指摘すること。変更が乗る流れを、base と head の両方で入口から出口まで辿る(Step 4)
- 相手のコードを長く引用すること。インラインは既にその行に付いている
例外
- ユーザーが「まとめて1コメントで」と指示した場合は、インラインに分けず総括のみで投稿する
- レビュー結果を投稿せず会話に留めたい場合(下読みだけ頼まれた場合)は、Step 7で終える
関連
/resolve-human-reviews(受ける側): 指摘の受け手の手順。本スキルは出し手responding_to_reviews.md(対応した指摘へ 👍): 受け手側の規定。出し手側は上記「再レビュー」が定める/review-code(--deepを含む)とプロジェクト側のレビュースキル: レビューの中身。本スキルは対象特定・裏取り・整形・投稿を担うresponding_to_reviews.md: 人間のコメントへ勝手に返信しないことを定める。本スキルが扱うのは新規レビューの投稿であり、既存コメントへの返信ではないconcise_first_then_detail.md(簡潔に、表と Mermaid の使い分け): 「コメント本文の書き方」の土台。/create-pr・/update-pr-descriptionも同じ土台に乗るgithub_note_generated_by_claude.md: 生成者表示の書式github_writing.md: GitHub へ書く日本語は1文ごとに改行し、行末の句点を落とす。総括・インラインの両方が対象/format-post(投稿する文章の畳み方): Alert /<details>/ 脚注の使い分け。Alert は本文に1〜2個、コメントや返信なら1個で足りる(生成者表示のNOTEは数えない)focus_insights_on_judgment.md(代行するほど、渡す責任が増える): Step 7「報告に入れるもの」の土台。ユーザー自身がレビューできる状態を保つことを定めるverify_before_asserting.md: Step 5〜6の土台。ユーザーの発言も裏取りの対象という点は、PR 本文の主張にもそのまま当てはまるreport_formatting.md(報告に貼る識別子の書式): 投稿後の報告に添える URL の土台。PR とインライン1件ずつを出すことを定めるsolve_with_minimal_change.md(最小の変更で解決する): 目の前の問題に要らない改善は must にせず、範囲の中は[iaio]、範囲の外は[fyi]で出す