pr-reviewer

PR レビュースキル

業界標準の基準と自動化ツールを使用して、GitHub プルリクエストに対する包括的でプロフェッショナルなコードレビューを実施します。

目次

• 目的
• 使用するタイミング
• レビュープロセスのワークフロー
• 参照ドキュメント
• スクリプトリファレンス
• ベストプラクティス
• クイックリファレンスコマンド
• 効果的なレビューのためのヒント
• リソース

目的

このスキルは以下によってコードレビューを実行します。

1. データ収集の自動化 - PR 関連のすべての情報 (メタデータ、diff、コメント、コミット、issue) を取得
2. レビューワークスペースの整理 - すべての成果物を含む構造化されたディレクトリを作成
3. 体系的な基準の適用 - 包括的な品質チェックリストに照らしてレビュー
4. インラインフィードバックの促進 - オプションで PR のコードに直接コメントを追加
5. 完全性の確保 - 機能性、セキュリティ、テスト、保守性をチェック

使用するタイミング

以下の場合にこのスキルを有効化します。

• レビュー依頼とともに GitHub PR の URL が提供されたとき
• 「この PR をレビューして」または「コードレビュー」のリクエストを受け取ったとき
• マージ前に PR の品質をチェックするとき
• 提案された変更に対して体系的なフィードバックを提供するとき
• あらゆる文脈で GitHub PR レビューが言及されたとき

レビュープロセスのワークフロー

重要: このスキルは 2 段階の承認プロセス を使用します。/send または /send-decline による明示的な承認があるまで、GitHub には何も投稿されません。

概要

1. PR データを取得 - すべての情報を収集
2. レビューファイルを生成 - 詳細版、human 版、インラインコメントファイルを作成
3. レビューと編集 - ファイルを確認し、必要に応じて変更 (/show を使用)
4. 承認と投稿 - /send (承認) または /send-decline (変更リクエスト) を使用

ステップ 1: PR データを取得

fetch_pr_data.py を使用して、すべての PR 情報を自動的に収集します。

python scripts/fetch_pr_data.py <pr_url> [--output-dir <dir>] [--no-clone]

実行されるアクション:

• PR の URL を解析して owner、repo、PR 番号を抽出
• ディレクトリ構造を作成: <output-dir>/PRs/<repo-name>/<PR-NUMBER>/
• PR メタデータ (タイトル、作成者、状態、ブランチ、ラベル) を取得
• PR の diff とコミット履歴をダウンロード
• すべての PR コメントとレビューを取得
• チケット参照 (JIRA、GitHub issue) を抽出
• オプションでソースブランチをクローンし、git diff を生成

例:

python scripts/fetch_pr_data.py https://github.com/facebook/react/pull/28476

# Custom output directory
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123 --output-dir /tmp/reviews

# Skip cloning (faster, no git diff)
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123 --no-clone

出力構造:

/tmp/PRs/<repo-name>/<PR-NUMBER>/
├── metadata.json           # PR metadata (title, author, branches)
├── diff.patch             # PR diff from gh CLI
├── git_diff.patch         # Git diff (if cloned)
├── comments.json          # Review comments on code
├── commits.json           # Commit history
├── related_issues.json    # Linked GitHub issues
├── ticket_numbers.json    # Extracted ticket references
├── SUMMARY.txt            # Human-readable summary
└── source/                # Cloned repository (if not --no-clone)

ステップ 2: PR データを分析

取得後、収集したデータをレビュー基準に照らして分析します。

1. SUMMARY.txt を読む - 概要
2. metadata.json を確認 - PR のコンテキスト、ラベル、担当者
3. diff.patch を確認 - コードの変更
4. comments.json をチェック - 既存のフィードバック
5. commits.json を確認 - コミットの品質とメッセージ
6. related_issues.json をチェック - リンクされたチケット/issue
7. レビュー基準を適用 - 包括的なチェックリストに照らして評価

Read ツールを使用してファイルを確認します。

Read /tmp/PRs/<repo-name>/<PR-NUMBER>/SUMMARY.txt
Read /tmp/PRs/<repo-name>/<PR-NUMBER>/metadata.json
Read /tmp/PRs/<repo-name>/<PR-NUMBER>/diff.patch

ステップ 3: レビューファイルを生成

最重要: 分析後、generate_review_files.py を使用して構造化されたレビュードキュメントを作成します。

python scripts/generate_review_files.py <pr_review_dir> --findings <findings_json> [--metadata <metadata_json>]

pr_review_dir/pr/ に 3 つのファイルを作成します。

1. pr/review.md - 絵文字と行番号付きの詳細な内部レビュー
2. pr/human.md - 投稿用のクリーンなレビュー (絵文字、em ダッシュ、行番号なし)
3. pr/inline.md - コードスニペット付きのインラインコメント案

また、スラッシュコマンドを作成します (.claude/commands/ 内):

• /send - human.md を投稿して PR を承認
• /send-decline - human.md を投稿して変更をリクエスト
• /show - VS Code でレビューディレクトリを開く

findings の JSON 構造:

{
  "summary": "Overall assessment of the PR...",
  "metadata": {
    "repository": "owner/repo",
    "number": 123,
    "title": "PR title",
    "author": "username",
    "head_branch": "feature",
    "base_branch": "main"
  },
  "blockers": [
    {
      "category": "Security",
      "issue": "SQL injection vulnerability",
      "file": "src/db/queries.py",
      "line": 45,
      "details": "Using string concatenation for SQL query",
      "fix": "Use parameterized queries",
      "code_snippet": "result = db.execute('SELECT * FROM users WHERE id = ' + user_id)"
    }
  ],
  "important": [...],
  "nits": [...],
  "suggestions": ["Consider adding...", "Future enhancement..."],
  "questions": ["Is this intended to...", "Should we..."],
  "praise": ["Excellent test coverage", "Clear documentation"],
  "inline_comments": [
    {
      "file": "src/app.py",
      "line": 42,
      "comment": "Consider edge case handling for empty input",
      "code_snippet": "def process(data):\n    return data.strip()",
      "start_line": 41,
      "end_line": 43,
      "owner": "owner",
      "repo": "repo",
      "pr_number": 123
    }
  ]
}

ステップ 4: ファイルをレビューして編集

/show を使用して VS Code でレビューディレクトリを開きます。

利用可能なアクション:

• pr/review.md を読む - 詳細な分析
• pr/human.md を編集 - 投稿前に修正
• pr/inline.md を確認 - コメント案をチェック
• 必要に応じて任意の内容を調整

ステップ 5 で明示的に承認するまで、何も投稿されません。

ステップ 5: 承認して投稿する

準備ができたらレビューを投稿します:

オプション A: PR を承認する

/send

• pr/human.md をコメントとして投稿します
• PR を承認します
• アクションを確認します

オプション B: 変更をリクエストする

/send-decline

• pr/human.md をコメントとして投稿します
• PR に対して変更をリクエストします
• アクションを確認します

インラインコメントの投稿 (任意、/send または /send-decline の後): pr/inline.md を確認し、特定のコードコメントについて提供されたコマンドを実行します。

ステップ 6: レビュー基準を適用する

包括的なチェックリストについては references/review_criteria.md を参照してください。以下のカテゴリに照らしてレビューします:

カテゴリ	主要な質問
機能性	コードは問題を解決していますか? バグは? エッジケースは?
可読性	明確なコードですか? 意味のある名前ですか? DRY ですか?
スタイル	linter のルールに従っていますか? コードベースと一貫していますか?
パフォーマンス	効率的なアルゴリズムですか? スケーラブルですか?
セキュリティ	脆弱性は対処されていますか? シークレットは保護されていますか?
テスト	テストはありますか? ハッピーパスとエッジケースをカバーしていますか?
PR の品質	スコープは絞られていますか? コミットはクリーンですか? 説明は明確ですか?

指摘事項の優先度マーカー:

• Blocker: マージ前に必ず修正する必要があります
• Important: 対処すべきです
• Nit: あると良い、任意です
• Suggestion: 今後検討してください
• Question: 明確化が必要です
• Praise: 良い仕事です

詳細な基準について: references/review_criteria.md をお読みください

リファレンスドキュメント

このスキルには包括的なリファレンスガイドが含まれています:

リファレンス	目的
references/review_criteria.md	機能性、セキュリティ、テストなどをカバーする完全なチェックリスト
references/gh_cli_guide.md	GitHub CLI コマンドのクイックリファレンス
references/scenarios.md	一般的なレビューシナリオの詳細なワークフロー
references/troubleshooting.md	よくある問題と解決策

スクリプトリファレンス

scripts/fetch_pr_data.py

PR データの自動取得と整理。

python scripts/fetch_pr_data.py <pr_url> [options]

Options:
  --output-dir DIR    Base output directory (default: /tmp)
  --no-clone         Skip cloning repository

scripts/generate_review_files.py

分析の指摘事項から構造化されたレビューファイルを生成します。

python scripts/generate_review_files.py <pr_review_dir> --findings <findings_json> [--metadata <metadata_json>]

作成されるもの:

• pr/review.md - 詳細な内部レビュー
• pr/human.md - 投稿用の整形されたレビュー
• pr/inline.md - コマンド付きの提案インラインコメント
• .claude/commands/send.md - 承認して投稿するためのスラッシュコマンド
• .claude/commands/send-decline.md - 変更をリクエストするためのスラッシュコマンド
• .claude/commands/show.md - VS Code で開くためのスラッシュコマンド
• REVIEW_READY.txt - 次のステップの概要

scripts/add_inline_comment.py

PR 内の特定の行にインラインコードレビューコメントを追加します。

python scripts/add_inline_comment.py <owner> <repo> <pr_number> <commit_id> <file_path> <line> "<comment>" [options]

Options:
  --side RIGHT|LEFT       Side of diff (default: RIGHT)
  --start-line N         Starting line for multi-line comment
  --start-side RIGHT|LEFT Starting side for multi-line comment

ベストプラクティス

コミュニケーション

• フィードバックは批判ではなく提案として伝えます
• 何が間違っているかだけでなく、なぜその問題が重要かを説明します
• 優れた実践を認めます
• ブロッカーを最優先し、スタイルの問題は最後にします

レビューの効率

• スクリプトを使用してデータ取得とコメント投稿を自動化します
• review_criteria.md をチェックリストとして参照します
• 優先順位: 重大な問題 > 重要 > あると良い
• 迅速にレビューします (可能であれば 24 時間以内)

インラインコメント

• 正確な行とファイルを参照します
• より良い代替案を提供します
• まずテスト PR でインラインコメントをテストします
• 圧倒しないよう控えめに使用します

PR のサイズへの対処

• 大きな PR (400 行超): 分割を提案します
• 論理的なまとまりごとにレビューします
• 大きな変更ではアーキテクチャに注目します

詳細なシナリオについて: references/scenarios.md をお読みください

クイックリファレンスコマンド

# Fetch PR data
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123

# Add inline comment
python scripts/add_inline_comment.py owner repo 123 latest "src/app.py" 42 "Comment"

# View PR in browser
gh pr view 123 --repo owner/repo --web

# Check PR status
gh pr checks 123 --repo owner/repo

# View existing comments
gh api /repos/owner/repo/pulls/123/comments --jq '.[] | {path, line, body}'

効果的なレビューのためのヒント

1. コンテキストから始めます: PR の説明、リンクされた issue、コミットメッセージを読みます
2. 意図を理解します: 解決しようとしている問題を特定します
3. まずテストを確認します: テストが修正/機能を実証していることを検証します
4. パターンを探します: 繰り返される問題はアーキテクチャの問題を示唆します
5. 代替案を検討します: よりシンプルなアプローチを評価します
6. 保守性を考えます: 将来の変更のしやすさを評価します
7. 人間であることを忘れないでください: 親切さ、敬意、建設的なトーンを保ちます

トラブルシューティングについて: references/troubleshooting.md をお読みください

リソース

• レビュー基準: references/review_criteria.md
• gh CLI ガイド: references/gh_cli_guide.md
• シナリオ: references/scenarios.md
• トラブルシューティング: references/troubleshooting.md
• GitHub PR レビューのドキュメント: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests
• Google エンジニアリングプラクティス: https://google.github.io/eng-practices/review/
• OWASP Top 10: https://owasp.org/www-project-top-ten/