| name | github-pr-review |
| description | GitHubのPull Request(PR)のコードレビューを行うSkill。worktreeを作成してソースコード全体を読みながらFinder SubAgentで指摘候補を発見し、Verifier SubAgentで検証する。レビューをレポートとインラインコメントで投稿する。self reviewにも対応する。 ユーザーが「このPRをレビューして」のように依頼したら使うこと。 |
| allowed-tools | Task, Read, Write, AskUserQuestion, Bash(git:*), Bash(gh:*), Bash(jq:*), Bash(mkdir:*), Bash(mktemp:*), Bash(rm:*), Bash(bash:*) |
Pull Request Review
PRのhead commitを worktree にチェックアウトし，Finder SubAgentが指摘候補を探す．
Finder SubAgentが出した指摘候補は，1件ずつ Verifier SubAgent が反証を試み，
検証を通過したものだけを要修正事項としてレビューレポートとinline commentに投稿する．
Arguments
PR number: レビューするPR番号 (optional, defaults to PR for current branch)--dry-run: レビューレポートをチャットに提示するのみで、post_review.sh 等の投稿スクリプト・dismiss・resolve操作を一切呼ばない(worktreeの後片付けは通常どおり行う)
Task
GitHub操作は必ずgh CLIで行うこと。GitHub connector/pluginやMCPのGitHubツールは使用しない。
Phase 1: 準備
Phase 1.1: 対象PRの特定
- 引数にPR番号が指定されている場合: 指定されたPRを対象にする
- 引数なし
- 現在のブランチに紐づくopen PRが存在する場合: そのPRをそのまま使用する(確認なし)
- 現在のブランチに紐づくopen PRが存在しない場合: RemoteのOpen PR一覧を取得し、
AskUserQuestionでユーザーに対象PRを確認する。Open PRが1件もなければその旨を報告して終了する
Phase 1.2: PR情報とGitHub上の状態の収集
以下を取得する。
- PR情報: repository名、タイトル、本文、base・head branch、最新head commit SHA
- 変更内容: 変更ファイル一覧、diff、コミットメッセージ
- CI: checkの結果、失敗したcheckの名前・URL・取得可能な関連ログ
- 自分の既存レビュー: 未resolve threadと会話、
APPROVED / CHANGES_REQUESTED レビューID
最新head commit SHAは <latest-commit-sha> として保持する。
CIの失敗はレポートの概要に記載し、Finderの内部証拠として使用する。
自分の既存threadと会話はVerifierの反証材料として使用し、投稿前のthread IDを <existing-thread-ids>、レビューIDを <existing-review-ids> として保持する。
他のレビュワーのレビューやthreadは参照しない。初回レビューではどちらのID一覧も空になる。
Phase 1.3: worktreeとレビュー環境の準備
<repo-root>/.tmp/<repo-name>-worktrees/pr-<number>-review を専用 worktree path とする。- 同じ path の worktree が存在し、未commit変更がある場合は中止する。clean な場合のみ作り直してよい。
- PRの最新head commitとbase branchを取得し、head commitをdetached状態で専用worktreeにcheckoutする。
- worktreeの
HEAD が <latest-commit-sha> と一致することを確認する。一致しない場合はレビューを中止する。
- Phase 2以降では、レビュー対象のファイルをすべて専用worktree内から参照する。
- worktreeの準備に失敗した場合は、エラーを報告して中止する。
Phase 2: レビュー
Finder SubAgentが変更全体から候補を収集し、Verifier SubAgentがfalse positiveを落とし、確定指摘からレビューレポートを作成する。
Phase 2.1: Finder SubAgentの実行
pr-reviewer-finder を1つ起動し、PRの変更全体からカテゴリラベル付きの指摘候補を収集する。
レビュー方法と出力形式はFinderのagent定義に従う。
Finder には以下の情報を渡す:
- PRのタイトル・本文
- 変更ファイル一覧、diff、コミットメッセージ
- PR全体の変更サマリ(changedFiles / additions / deletions)
- worktree のパス(絶対パス)
- base branch と head branch の最新 commit SHA
- 失敗したCI結果のサマリと、checkの名前・URL・関連ログ
Finderには、Gitの差分と履歴の参照、ファイルの検索と読み取りだけを許可する。
worktree内のコード、テスト、ビルド、lint、型チェック、package script、再現コードは実行させない。
Phase 2.2: 候補選別と敵対的検証
Finderが発見した指摘から候補を確定する。
- Finderが出力したカテゴリラベル付きの指摘をすべて候補とする
- 候補は以下をすべて満たすこと: PRのdiffが導入・露出した問題である /
問題 に発生条件・原因・具体的な実害がある / 完了条件 が実装方法ではなく満たすべき状態を示している / 証拠 の実行パスがある
- verifier の起動前に、同じ
filepath:line または同じ根本原因の候補を1件にまとめる
- カテゴリは表示用情報として扱い、候補の重複統合やverifierの判定に使用しない
- 各候補と自分の既存未resolve threadを照合し、同じ根本原因の会話だけをVerifierの反証材料とする
敵対的検証: 候補1件ごとに pr-reviewer-verifier を1つずつ起動して反証を試みる。
- 選別の結果、候補が0件ならこのステップをスキップする
- 各 verifier には、候補1件の全文(証拠チェーンと関連するCI情報を含む)、同じ根本原因の既存threadと会話(ある場合)、worktree のパス、PRのタイトル・本文、base / head の commit SHAを渡す
- verifierには、worktree内で検証に必要なコマンドと、関連する最小のテストや再現コードの実行を許可する
- verifierがコードを実行した場合は、コマンドと結果を内部の根拠に残す
最終verdictがconfirmedの候補のみ通過させる。refuted / uncertainは破棄する。
確定指摘の正規化: verifier が confirmed と判定した候補だけを、以下の内部レコードへ正規化する。
path / line / sideカテゴリ要約問題完了条件証拠 (問題へ実際に到達する実行パス。内部確認専用)
verifierの「完了条件の評価」を反映し、実装方法を指定せず、問題が解消されたと判断できる状態を完了条件に残す。
候補の重複統合はverifier前の1回だけとする。
Phase 2.3では、この確定指摘一覧だけを指摘内容の入力として扱う。
Phase 2.3: 指摘の校正とレビューレポートの作成
Phase 2.2の確定指摘一覧から、次の順でレビューレポートを作成する。
- PRのタイトルと本文から出力言語を決める。
- 主に日本語の場合は日本語
- それ以外または判定が曖昧な場合は英語
- 確定指摘一覧を、同じ件数と順序の校正済み指摘一覧へ変換する。
- 人間が一読で問題と実害を理解できる、平易で自然な表現にする
カテゴリは、問題の主な実害を表す1〜3語のラベルにし、出力言語に合わせる- 処理状態、広すぎる観点、原因や仕組み、重要度、確度はカテゴリにしない
要約は、問題の中心を一読で理解できる短い表現にする問題は、発生条件、原因、具体的な実害が自然に伝わる順序で記述する- 専門用語、略語、造語を使用せず、必要な技術概念は一般的な言葉で説明する
- 検証過程、証拠の列挙、重複した説明を取り除く
- 問題を理解するために必要な前提やコード上の名称は残す
完了条件は、問題が解消されたと判断できる状態を簡潔に記述する- 指摘の採否、技術的な意味、対象範囲、
完了条件の意味を変更しない
- 推測による情報、修正案、実装方法を追加しない
path、line、sideは変更しない
- Verdictを決める。
- 校正済み指摘が1件以上の場合は
REQUEST_CHANGES
- 校正済み指摘が0件の場合は
APPROVE
- self reviewを含め、レポート内では
COMMENTを使用しない。GitHub APIへ渡すeventはPhase 3.1で決める
- 出力言語に対応するテンプレートを読み込む。
- 日本語の場合は
references/report-ja.md
- 英語の場合は
references/report-en.md
- テンプレートを埋めてレポート本文を生成する。
<reviewer-name>: 実行中のレビュワー名。Claude CodeではClaude<short-sha>: <latest-commit-sha>の先頭7文字- CIが失敗している場合は概要に1行記載する
校正済み指摘一覧には、次の項目だけを含める。
path / line / sideカテゴリ要約問題完了条件
確定指摘一覧と証拠は、校正後も内部確認用として保持する。
レポート本文とinline commentの指摘部分は、校正済み指摘一覧だけから生成する。
Phase 2.4: 出力対象commitの確認
PRの現在のhead commit SHAを再取得し、Phase 1で保持した <latest-commit-sha> と一致することを確認する。
- 一致しない場合はレビュー結果を無効とし、Phase 3をスキップしてPhase 4に進む
- 一致し、
--dry-run が指定されている場合はPhase 3をスキップしてPhase 4に進む
- 一致し、
--dry-run が指定されていない場合はPhase 3に進む
Phase 3: レビューの投稿と置き換え
--dry-run が指定されていない場合のみ実行する。
Phase 3.1: event種別の決定
- self review モードでは
--event COMMENT を渡すが，body 内の Verdict 表記は元のまま(APPROVE または REQUEST_CHANGES)にする(GitHub の仕様で自分の PR に APPROVE / REQUEST_CHANGES は投稿できないため)。
- self review 以外の通常レビューでは、レビューレポートのVerdictが
APPROVE → --event APPROVE、REQUEST_CHANGES → --event REQUEST_CHANGES を渡す
Phase 3.2: inline commentの作成と投稿
Phase 2.3の校正済み指摘一覧について、(path, line, side)がPRのdiffに含まれるか検証し、diff内の指摘からinline comments JSONを生成する。
レポート本文を解析してinline commentsを作らず、レポートと同じ校正済み指摘一覧から生成する。
番号と内容はレポート本文に一致させ、内部確認用の証拠は含めない。
inline comments JSONは以下の形式とする。
[
{
"path": "src/auth.ts",
"line": 42,
"side": "RIGHT",
"body": "🔴 1: **[Category] Issue summary**\n\n問題: ...\n完了条件: ...\n\n---\nCommented by <reviewer-name>"
}
]
path / line / body は必須。side は既定 RIGHT とし、削除行など変更前ファイル側にコメントする場合のみ LEFT を明示する。
N: はレポート本文の N: 番号と一致させ、inline対象外の指摘があっても再採番しない。
レビュー実行ごとに mktemp -d で一意な <review-temp-dir> を作成する。
レポート本文を <review-temp-dir>/body.md、inline comments JSONを <review-temp-dir>/comments.json に保存し、scripts/post_review.sh に渡してGitHub API経由でレビューを投稿する。
inline commentsがない場合は --comments-file を省略する。
bash "<skill-dir>/scripts/post_review.sh" \
--repo "<owner/repo>" \
--pr "<number>" \
--commit "<latest-commit-sha>" \
--event "<APPROVE|REQUEST_CHANGES|COMMENT>" \
--body-file "<review-temp-dir>/body.md" \
--comments-file "<review-temp-dir>/comments.json"
- 成功時は PR レビューの URL が標準出力に出力される
- レビュー本文とinline commentはファイルで渡し、シェル引数にしない
- 重要:
gh pr review --body ...、gh api -f body=...、シェル上で組み立てた JSON 文字列の直接渡しは禁止
- Inline Coments のルール:
- 行番号は，
side が RIGHT(既定)の場合は変更後ファイル(diff の右側)の行に，LEFT の場合は変更前ファイル(diff の左側)の行に対応していなければならない
post_review.sh は防御的な再確認として、投稿前に PR の files API から各ファイルの patch を取得し，(path, line, side) が diff に含まれているかを検証する。invalid なエントリはinline対象から除外し、レポート本文は変更しない。残りのinline投稿は継続し、除外件数を標準エラーに Warning: として出力する
Phase 3.3: 以前のレビューの後始末
Phase 3.2の投稿が成功した後にのみ実行し、最新レビューだけを現在有効なレビューとして残す。投稿が失敗した場合は何もしない(古いレビューを残すことで「新規レビューなし」の空白状態を回避する)。初回レビュー時は対象0で自然にスキップされる。
既存レビューのdismiss
重要: 必ず Phase 1.2 で取得した <existing-review-ids>(投稿前のスナップショット)を --review-id で明示的に渡す。スクリプトはIDの自動検索を行わず、--review-id がない場合は失敗する。
bash "<skill-dir>/scripts/dismiss_my_reviews.sh" \
--repo "<owner/repo>" \
--pr "<number>" \
--review-id "<id1>" --review-id "<id2>"
<existing-review-ids> が空の場合は dismiss スクリプトを呼び出さない。
以前のinline commentのresolve
Phase 1.2 で取得した <existing-thread-ids> のthreadを、outdatedかどうかに関係なくすべてresolveする。最新headへの新しいレビューが投稿済みのため、以後は新しいレビューだけを対応対象とする。
bash "<skill-dir>/scripts/resolve_review_threads.sh" \
--thread-id "<id1>" --thread-id "<id2>"
<existing-thread-ids> が空の場合はresolveスクリプトを呼び出さない。
スクリプトは指定されたthread IDだけをresolveする。
Phase 4: 終了処理
まず、レビュー用に作成したworktreeと一時Git refを削除する。投稿用の <review-temp-dir> を作成している場合は、それも削除する。
処理が中断した場合も、作成済みのworktreeと一時Git ref、<review-temp-dir> を必ず削除する。
クリーンアップの成否にかかわらず、続けて結果を報告する。失敗した場合は、その内容も含める。
Phase 2.4でhead commit SHAが一致しなかった場合は、レビュー内容を提示せず、PR更新後の再レビューが必要なことを報告する。
一致した場合は、以下をまとめてユーザーに提示して終了する。
- Verdict、要修正事項の件数、レポート本文
- レビューURL(
post_review.sh の標準出力)。--dry-run または投稿失敗時は、投稿されていない旨を明記する
- dismissした既存レビューとresolveした以前のthreadの件数(Phase 3.3を実行した場合のみ)
