review-pr

他の人が出した PR をレビューし、総括コメントとインラインコメントをセットで GitHub へ投稿する。レビュー結果はまず会話に出し、ユーザーの GO を得てから投稿する。ユーザーが /review-pr を打ったときだけ動く(AI からは呼べない)。--deep を付けると、レビューの実施をサブエージェントの並列に差し替える。自分が出した PR の点検・仕上げは /finalize-prs の

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] で出す