read-only-gh-pr-review

PR レビュー（バックエンド、GitHub CLI）

概要

ローカルでのコード分析と GitHub CLI API 呼び出しを使用して、バックエンドのプルリクエストをエンドツーエンドでレビューします。報告するのは、対応可能で重要度の高い指摘事項のみです。

ツールの制約

• 使用できるのは次のものだけです：SemanticSearch、WebSearch、Grep、LS、Glob、Read、Shell、GitHub CLI。
• gh コマンドを実行する前に、読み取り専用環境スクリプトを読み込んでセキュリティの強制を有効にしてください。

  source "<SKILL_DIR>/scripts/activate-gh-readonly.sh"
  

  <SKILL_DIR> を、このスキルディレクトリの絶対パスに置き換えてください。
• 読み込み後は、読み取り専用ラッパーによって傍受されるため、gh コマンドを直接使用してください。
• まず gh auth status で CLI の認証状態を確認してください。未認証の場合は、ユーザーに gh auth login の実行を依頼してください。
• 常に厳格な読み取り専用モードを徹底してください。
• コメント、レビュー、編集、割り当て、マージ、クローズ、再オープン、API の変更など、書き込み操作は一切試みないでください。
• 要求されたコマンドがラッパーによってブロックされた場合、状態を変更する可能性のある代替手段を試してはいけません。
• 読み取り専用ラッパーは command gh や、その他の回避手段をブロックします。

ワークフロー

1. 読み取り専用環境を有効にします。
   • 環境スクリプトを読み込みます：source "<SKILL_DIR>/scripts/activate-gh-readonly.sh"
   • このシェルセッションで以降に実行するすべての gh コマンドは保護されます。
2. レビューのコンテキストを準備します。
   • ユーザー情報と認証を確認します：gh auth status、gh api user。
   • 現在のリポジトリからリポジトリのオーナー名とリポジトリ名を特定するか、-R <OWNER>/<REPO> を指定します。
3. 対象の PR を特定します。
   • PR 番号がわかっている場合は gh pr view <PR_NUMBER> [--json <fields>] を使用します。
   • わからない場合は gh pr list [flags] で候補を絞り、対象の PR を選びます。
4. ローカルリポジトリを最新の PR ブランチのコードに同期します。
   • コードをレビューする前に、PR のヘッドブランチの最新のリモート状態を取得します。
   • 手順の例：
     • PR のメタデータからヘッドブランチ名（headRefName）を取得します。
     • git fetch --prune origin <HEAD_BRANCH> を実行します。
     • FETCH_HEAD のファイルをレビューするか、そこからローカルのレビュー用ブランチをチェックアウトします。
5. 判断する前に、PR の証拠をすべて収集します。
   • メタデータ：gh pr view <PR_NUMBER> [--json <fields>]
   • 差分：gh pr diff <PR_NUMBER> [--patch|--name-only]
   • 変更ファイル：gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/files --paginate
   • レビュー：gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews --paginate
   • チェック：gh pr checks <PR_NUMBER> [--json <fields>]
   • コメント：
     • gh pr view <PR_NUMBER> --comments
     • gh api repos/<OWNER>/<REPO>/issues/<PR_NUMBER>/comments --paginate
     • gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments --paginate
6. 変更されたバックエンドコードを詳細に調査します。
   • リスクの高い変更箇所を含むファイルをすべてローカルで読み込み（Read、Grep）、差分の該当箇所と照合します。
   • リクエストハンドラー／コントローラー、ビジネスサービス、認可ロジック、データベースクエリ、マイグレーション、バックグラウンドジョブ、キュー／イベントハンドラーを優先します。
   • 冪等性、トランザクションの安全性、並行処理の動作、リトライの動作、公開 API 契約の後方互換性を検証します。
   • リモート上の正確なコンテンツが必要な場合は gh api repos/<OWNER>/<REPO>/contents/<PATH>?ref=<REF> を使用します（通常、.content 内のコンテンツは base64 形式です）。
7. リスクの高い項目から順にレビュー用チェックリストを適用します。
   • references/review-checklist.md を使用します。
   • スタイル上の懸念より先に、セキュリティ、正確性、データ整合性、API 互換性、パフォーマンス、テストの十分性を確認します。
8. 対応可能なレビュー結果を作成します。
   • 欠陥、リグレッション、保守性のリスクである可能性が高い問題のみを報告します。
   • 各問題は、報告する前に以下の「証拠と検証」のルールを満たす必要があります。
   • 正確な file:line、影響、具体的な修正方法を含めます。
   • 残存リスクと、実施されていない検証／テストに関する前提を最後に記載します。
   • 指摘事項はチャット内でのみ返し、GitHub にコメントやレビューを書き込まないでください。

エビデンスと検証

報告するすべての問題について、検証済みの事実と推測を分けてください。推測を事実として提示してはいけません。

• 事実：実際のコード、差分、またはコマンド出力を確認して検証した動作です。すべての事実について file:line を引用してください。
• 推測：検証されていない推論です。実行時の動作、未確認の設定、外部サービスの動作、データ量、デプロイ構成、差分外の呼び出し元の動作などが該当します。

ルール：

• 問題を報告する前に、呼び出し元、依存関係、既存のガードを含め、コードの処理経路全体を追跡してください。別の箇所にあるガードや検証で防がれている問題は報告しないでください。まず、そのコードを見つけて読んでください。
• 周辺のファイルや呼び出し元を確認できる場合、差分の該当部分だけを根拠に問題を報告しないでください。
• 指摘の根拠となるすべての推測にラベルを付け、確認方法を明記してください。
• 利用可能なエビデンスで検証できない疑念は、推測であることを明示して質問として報告するか、報告を見送ってください。不具合として報告してはいけません。
• 行番号、シンボル、コードスニペット、動作を決して捏造しないでください。実在するコードのみを引用してください。
• エビデンスが不完全な場合（ファイルが途中で切れている、コマンドが失敗した、参照先が利用できないなど）は、推測で補わず、指摘の中でその旨を伝えてください。

回答形式

以下の順序でセクションを使用してください。

1. Critical Issues (Must Fix)
2. Important Issues (Should Fix)
3. Suggestions (Consider)

各問題について、次の形式を使用してください。

Issue: <brief description>
Location: <file:line>
Severity: <Critical|High|Medium|Low>
Facts: <verified behavior with file:line evidence>
Assumptions: <unverified inferences this finding depends on, and how to confirm them; "None" if fully verified>
Problematic Code: <snippet quoted from the actual code>
Suggestion: <specific fix>
Example: <optional patch-style snippet>

Assumptions: None の指摘は、確認済みの不具合です。推測に依存する指摘は、「X が上流で強制されていない場合、…」のように条件付きで記述してください。

GitHub CLI API の同等コマンド

references/github-cli-map.md のコマンド対応表を使用してください。

レビューのトーン

• 建設的かつ具体的にしてください。
• 影響と根拠を説明してください。
• 善意を前提にしてください。
• 簡潔で、確信度の高いフィードバックを優先してください。
• 不確実性は率直に示してください。確信を持って推測するより、推測にラベルを付けてください。