review-gitcode-pr

GitCode PR をレビューする

レビューが GitCode PR の参照から始まり、oh-gc の成果物とローカルリポジトリの調査を組み合わせる必要がある場合は、このスキルを実行します。

ワークフロー

1. PR を特定する

まず、ユーザー入力を正規化します。

• ユーザーが PR 番号を指定した場合は、その番号をそのまま使用します。
• ユーザーが URL を指定した場合は、PR 番号と、可能であれば OWNER/REPO を抽出します。
• 正規化した結果に OWNER/REPO が含まれない場合、scripts/collect_pr_context.py は現在のリポジトリの GitCode リモート URL から推定を試みます。
• リモートの推定が曖昧な場合、または現在のチェックアウトが GitCode のクローンではない場合は、--repo OWNER/REPO を明示的に渡します。
• この正規化の手順には scripts/normalize_pr_ref.py を使用します。

2. リモートコンテキストを収集する

コードを手動でレビューする前に、scripts/collect_pr_context.py を使用して PR のコンテキストを取得し、保存します。

このスクリプトは以下を収集します。

• oh-gc pr:view NUMBER --json
• oh-gc pr:diff NUMBER --json
• oh-gc pr:diff NUMBER --name-only
• oh-gc pr:diff NUMBER --color never
• oh-gc pr:comments NUMBER --json --comment-type pr_comment
• oh-gc pr:comments NUMBER --json --comment-type diff_comment

指摘を行う前に、生成された成果物ディレクトリを確認します。以下の順に成果物を読みます。

1. summary.json を読み、変更されたファイル、解析済みのハンク、コメント可能な新側の行、既存の正規化済みコンテキストを特定します。
2. 指摘候補について、pr-diff.txt を読み、差分の正確な内容とハンクの境界を確認します。
3. PR のタイトル、説明、ブランチ、概要レベルのメタデータについて、pr-view.json を読みます。
4. 正規化済みの要約だけでは不十分な場合に限り、pr-diff.json または未加工のコメント出力を読みます。

既定では、すべての成果物を読み込まないでください。まず summary.json を確認し、指摘の裏付けにさらなる根拠が必要な場合にのみ、詳細を調べてください。

3. ローカルコードを読む

差分だけを見てレビューしないでください。

深度、停止条件、リスクに応じたレビューの確認項目については、必須チェックリストである references/deep-review-checklist.md を使用してください。

完了する前に、変更された各ファイルに対して、次のレビュー状況を必ず1つだけ割り当ててください。

• reviewed：指摘事項、または指摘なしという結論を裏付けるのに十分な深さで、そのファイルと関連するコンテキストを確認した
• mechanical-low-risk：チェックリストに照らして検証した結果、変更が機械的かつ低リスクであることを実証できた
• skipped-with-reason：ファイルを詳細にはレビューせず、その理由と残存リスクを明示した

1つか2つの問題を見つけただけでレビューを終えないでください。変更されたすべてのファイルに、上記のいずれかの状況が付くまでレビューを続けてください。

重要な変更ファイルごとに、次のことを行ってください。

• 変更されたハンクを読む。
• 現在のリポジトリ内で、周辺のローカルコードを読む。
• 動作を検証するために必要な範囲で、インポート、ヘルパー、テスト、呼び出し元を確認する。最初の疑念を抱くためだけの確認で終わらせない。

深度に関する最低要件：

• 本番コードの変更では、直接の呼び出し元、直接の呼び出し先、関連テストのうち、少なくとも1つを確認する。
• API、スキーマ、永続化、並行処理、権限、キャッシュ、状態機械、エラー処理に関する変更では、それらのうち少なくとも2つの領域を確認する。差分だけを見て判断しない。
• ロジックの削除または移動では、以前の役割が妥当な場所に残っていること、または呼び出し元が適切に更新されていることを確認する。
• 新しい分岐や新たな失敗経路では、成功経路と新しい分岐の両方をテストがカバーしているかを確認する。確認できない場合は、その理由を説明する。

優先する項目：

• 正確性の不具合
• 動作のリグレッション
• 呼び出し箇所における前提の破綻
• 不足している、または無効なテスト
• セキュリティやデータ取り扱いに関する問題

スタイルに関するコメントより、重要度の高い指摘を優先してください。

深度に関する期待事項：

• リスクが低そうなファイルについては、直感で判断せず、コードのコンテキストやテストでそれを裏付けてください。
• リスクが高そうなファイルについては、指摘なしと判断する前に、確認の深度を上げてください。
• リポジトリのコンテキストが不十分な場合は、黙って確認の深度を下げず、レビュー上の制約として報告してください。

候補となる問題が実際の指摘に当たるか、重大度をどう設定するか、指摘が確認されなかった場合の残存リスクをどう説明するかを判断する際は、references/review-rubric.md を使用してください。

4. 指摘を提示する

デフォルトの出力は、広範な概要ではなく、問題を中心としたレビューです。

ユーザーに提示する各指摘には、次のテンプレートを使用してください。

重大度 | パス:行 | 問題 | 根拠 | 修正方法

次の情報を含めてください。

• 重大度：high、medium、low のいずれか
• パス
• 差分の追加側における、可能な限り正確な行番号
• 問題：何が誤っており、なぜ重要なのか
• 根拠：具体的なコード経路、動作、またはテストによる裏付けの不足
• 修正方法：問題を解消する変更

有効な差分行に紐付けられない場合は、次の順で代替してください。

1. path を含むファイル単位のコメント
2. 一般的なPRコメント

差分の行番号を捏造しないでください。

有効な指摘が見つからなかった場合は、そのことを明示し、次の情報を含めてください。

• 変更された各ファイルまたはファイルグループのレビュー状況
• 確認した主なコード経路、呼び出し元、呼び出し先、またはテスト
• 検証できなかったチェックリストのカテゴリ
• スタイルに関する指摘で埋め合わせるのではなく、残存する不確実性やテスト上の不足

確認対象の範囲について、ファイルの網羅性とチェックリストの確認が完了していない限り、「対応が必要な問題は見つかりませんでした」と述べないでください。

確認対象の範囲で指摘が確認されなかった場合は、デフォルトの出力形式として references/no-finding-template.md を使用してください。

GitCode に送信する可能性のあるコメントを書く際は、次の点に従ってください。

• ユーザーが別の言語を明示的に指定しない限り、デフォルトでは中国語で書く。
• 1つのパイプ区切り文ではなく、簡潔なMarkdownを使用する。
• 結論、問題の分析、修正案を、短い段落または箇条書きに分ける。
• パラメーター、ファイル、ステータスコードなどの識別子はバッククォートで囲む。

5. 提出用ドラフトを準備する

このスキルでは、2 段階の提出フローを使用します。

デフォルトの動作：

• PR をレビューする
• ユーザーに所見を提示する
• ユーザーが提出を希望する場合は、まず構造化されたドラフトを作成する

ドラフトの形式には references/review-draft-schema.md を使用し、収集したコンテキストに照らした検証には scripts/prepare_review_submission.py を使用します。

ドラフトには、次の項目を含めることができます。

• PR 全体へのサマリーコメントを 1 件
• path と line を指定した差分コメントを 0 件以上
• 任意の承認意図

承認ゲート：

• ブロッキングまたは重大度の高い所見が残っておらず、かつユーザーが明示的に承認を希望する場合に限り、approve: true を設定します。
• レビューにブロッキング所見が含まれる場合は、コメントのみを送信し、oh-gc pr:review は呼び出さないでください。

重要：oh-gc pr:review がサポートするのは承認のみです。一般的な「レビューを送信」するためのエンドポイントではありません。

コメントを送信する場合は、references/review-draft-schema.md の Markdown および中国語の記述ルールに従ってください。

6. 確認後にのみ送信する

GitCode への送信は、暗黙的に行わないでください。

ユーザーから明示的に送信を依頼された場合：

1. ドラフト JSON を作成する
2. --execute を指定せずに prepare_review_submission.py を実行し、コマンドをプレビューする
3. 投稿する予定の正確なサマリーとコメント数をユーザーに提示する
4. 確認を得た後、同じコマンドを --execute を指定して実行する

実行が途中で失敗した場合は、どのコメントが成功し、どのコメントが成功しなかったかを正確に報告します。

クイックフロー

上記のワークフローを読んだ後、簡潔なリマインダーとしてのみ、次のコマンドを使用してください。

python3 skills/review-gitcode-pr/scripts/collect_pr_context.py 123

主なレビュー成果物：

• summary.json
• pr-diff.txt
• pr-view.json

レビューの深さに関する注意：

1. summary.json を読む
2. references/deep-review-checklist.md を使って、変更された各ファイルのリスクを分類する
3. すべてのファイルに最終ステータスが付くまでレビューする
4. その後でのみ、レビューに所見がないかどうかを判断する

提出用ドラフトをプレビューする：

python3 skills/review-gitcode-pr/scripts/prepare_review_submission.py \
  --context-dir .review-gitcode-pr/pr-123 \
  --draft review-draft.json

ユーザーの明示的な確認後にのみ実行する：

python3 skills/review-gitcode-pr/scripts/prepare_review_submission.py \
  --context-dir .review-gitcode-pr/pr-123 \
  --draft review-draft.json \
  --execute

失敗時の対応

失敗には明示的に対処します。各ブロッカーについて、次の項目を報告してください。

• Blocker：何が失敗したか、どのコマンドまたは前提が失敗したか
• Fallback：どの範囲のレビューなら続行できるか
• Next step：ユーザーまたはエージェントが次に行うべきこと

oh-gc を利用できない

• Blocker：oh-gc が PATH にないか、実行できません。
• Fallback：GitCode からの取得や提出を試みないでください。以前に収集した成果物のディレクトリがローカルにすでに存在し、提出を伴わないレビューに十分な場合に限り、続行してください。
• Next step：ユーザーに oh-gc をインストールするか、利用可能にするよう依頼するか、オフラインレビューに使用する既存の成果物を指定するよう依頼してください。

認証または権限のエラー

• Blocker：PR の表示、差分、コメントについて、oh-gc が認証、認可、または API 権限のエラーを返します。
• Fallback：すでに収集した部分的な成果物は保持します。取得に成功した差分やコンテキストで提出を伴わないレビューに十分な場合に限り、続行してください。提出は試みないでください。
• Next step：失敗したコマンドをユーザーに伝え、リモートレビューまたは提出を続行するには再認証するかアクセス権を取得する必要があることを伝えてください。

ローカルリポジトリの不一致

• Blocker：現在のリポジトリが PR のリポジトリ、ブランチ構成、またはファイル一式と十分に一致しておらず、ローカルコードで動作を検証できません。
• Fallback：差分だけの確認からコードレベルの確信があるとは主張しないでください。ユーザーが希望する場合に限り、差分のみの限定的なレビューであることを明示して、レビュー結果を提示できます。
• Next step：完全なレビューを続ける前に、ユーザーに一致するリポジトリのチェックアウトへ切り替えるか、正しいローカルワークスペースを提供するよう依頼してください。

Diff JSON が欠落している、不正な形式である、または不完全である

• ブロッカー：pr:diff --json の形式が変わっている、ハンクが省略されている、または構造化された行マッピングに十分な精度で解析できません。
• フォールバック：差分の判断には pr-diff.txt を信頼できる情報源として使用します。新しい側の行を生の差分テキストから確実に検証できる場合に限り、行コメントを出力します。それ以外の場合は、ファイル単位または全般的なコメントに切り替えます。
• 次のステップ：構造化された差分の解析が劣化しており、JSON 形式が修正されるまで提出の精度が低下する可能性があることをユーザーに伝えます。

提出プレビューまたは実行の失敗

• ブロッカー：prepare_review_submission.py の検証に失敗する、プレビューコマンドが下書きと一致しない、または一部のコメントで --execute が失敗します。
• フォールバック：検証済みの下書きと、部分的に提出が成功した場合はその結果を保持します。意味を変更して、暗黙に再試行しないでください。
• 次のステップ：失敗したコメントまたはコマンドを正確に報告し、すでに投稿されたコメントと、再試行の前に修正が必要な内容を伝えます。