review-pr

PR レビュースキル

現在のプルリクエストをレビューし、結果を review.json に書き込みます。

コンテキスト

• 作業ディレクトリは、PR ブランチのチェックアウト先です。
• ワークフローでは通常、注釈付きの差分が pr_diff.txt に用意されます。
• ワークフローでは通常、PR の説明が pr_description.txt に用意されます。
• spec_context.md が存在する場合、実装と仕様の整合性を検証するための仕様コンテキストが記載されています。
• プロンプトで .agents/skills/review-pr/scripts/resolve_spec_context.py が指定されている場合は、プロンプトに仕様の内容が埋め込まれていると想定せず、そのスクリプトを使って必要に応じて spec_context.md を生成してください。
• この PR で変更されたファイルと行に焦点を当ててください。
• GitHub に直接コメントやレビューを投稿しないでください。

レビューの範囲

• 正確性、セキュリティ、エラー処理、重大なパフォーマンス上の問題を優先してください。
• コメントの品質とテストの品質は、これらと並ぶ最優先のレビュー項目として扱ってください。時間がある場合だけ触れる任意の細かな指摘ではありません。最終判断の前に、リポジトリ独自の規約に照らして両方を確認してください。
• 利用側のリポジトリに security-review-pr という補助スキルがある場合、またはプロンプトでセキュリティレビューが求められている場合は、コード PR に対する補足ガイダンスとして適用し、セキュリティ上の指摘を同じ review.json にまとめてください。別の出力としては作成しないでください。
• spec_context.md が存在する場合は、利用側のリポジトリに check-impl-against-spec スキルがあれば使用し、仕様との重大な乖離をレビュー上の問題として扱ってください。
• スタイルや細かな指摘は、具体的な提案ブロックを提示できる場合に限ってコメントしてください。
• 問題が未変更のコードに関わる場合は、インラインコメントではなくトップレベルの body に記載してください。
• 既存のテストが有意義な動作をすでに検証している場合、コンストラクターの入力や構造体のフィールドだけを変えたテストの追加は提案しないでください。新しいテストの提案は、異なるコードパスやエッジケースを検証する場合に限ってください。
• PR が明らかに V0 または初期実装の場合、タイムアウト、再試行、ライフサイクル管理などの堅牢性に関する提案は、正確性、セキュリティ、データ損失に影響する場合を除き、将来に向けた任意の改善として提示してください。

リポジトリ固有のガイダンス

レビューを始める前に、このスキルをリポジトリ独自の規約に合わせて拡張する review-pr-local 補助スキルが利用側のリポジトリにあるか、必ず確認してください。プロンプトで場所が指定されている場合はそこで読み、指定がない場合はリポジトリ内を探してください（例：.agents/skills/review-pr-local/SKILL.md。リポジトリによって場所や名称が異なる場合があります）。補助スキルがあれば、そのガイダンスを読み、レビューに適用してください。どちらの方法でも見つからなければ、このスキルの基本ルールだけに従ってください。

補助スキルでは、そのリポジトリ独自の規約に沿って、コメントとテストに関するガイダンスを具体化することが想定されています。ただし、このスキルで別途定める出力 JSON スキーマ、重大度ラベル、安全規則、根拠に関する規則、提案ブロックの制約、差分行への注釈付けに関する契約を変更してはなりません。

差分行の注釈

差分ファイルでは、次の接頭辞が使われています。

• 削除された旧側の行は [OLD:n] です。"LEFT" を使用してください。
• 追加された新側の行は [NEW:n] です。"RIGHT" を使用してください。
• 変更されていないコンテキスト行は [OLD:n,NEW:m] です。行番号 m とともに "RIGHT" を使用してください。

インラインコメントの位置情報は、これらの注釈だけを根拠にしてください。インラインコメントを出力する場合は、それぞれについて、まず pr_diff.txt（またはインライン表示された PR 差分）内の該当する注釈付き行を特定し、そのパス、側、行番号を review.json に転記してください。説明文、GitHub の表示画面、ファイルの行数、周辺の仕様テキスト、注釈のないコード片から行番号を推測してはなりません。該当する [NEW:n]、[OLD:n]、または [OLD:n,NEW:m] の行を特定できない場合は、その指摘を comments ではなくトップレベルの body に記載してください。

コメントの要件

すべてのコメント本文は、次のいずれかのラベルで始めてください。

• 🚨 [CRITICAL] バグ、セキュリティ上の問題、クラッシュ、またはデータ損失の場合。
• ⚠️ [IMPORTANT] ロジックの問題、エッジケース、またはエラーハンドリングの不足の場合。
• 💡 [SUGGESTION] 有益な改善や、より適切なパターンを提案する場合。
• 🧹 [NIT] コメントに提案ブロックを含める場合に限り、クリーンアップのみを指摘する場合。

リポジトリのコメントまたはテストのガイドラインへの違反が確認された場合、PR のほかの部分がどれほど整っていても、それだけで ⚠️ [IMPORTANT] に値することがあります。周囲のコードが良好に見えるという理由だけで、これらの違反を安易に 🧹 [NIT]／💡 [SUGGESTION] として扱わないでください。

コメントは、次の制約に従って記述してください。

• 簡潔で、直接的かつ実行可能な内容にしてください。
• 褒め言葉や曖昧な表現を加えないでください。
• 1 行のコメントを優先してください。
• 範囲は最大 10 行にしてください。
• インラインコメントは、注釈を付ける PR の差分に明示的に含まれる行に限定してください。
• ファイルレベルまたはインラインのコメントは、この PR の差分に存在するファイルにのみ付けてください。
• 関連するファイルまたは行が差分に含まれていない場合は、comments ではなくトップレベルの body にフィードバックを記載してください。
• 各コメントオブジェクトを追加する前に、その path、side、line、および任意の start_line／start_side が、同じファイルの差分セクションにある実際の注釈位置に対応していることを確認してください。

提案ブロック

コード変更を提案する場合は、次を使用してください。

<replacement code here>

ルール：

• 元のファイルと同じインデントにしてください。
• 置き換えるコードだけを含めてください。
• ブロックの内容は、行 start_line～line を含む範囲と正確に置き換わります。ブロック内の各行がその範囲の新しいファイル内容となり、GitHub はそれ以外の箇所を変更しません。
• その範囲の外にある行は含めないでください。start_line より前や line より後の行はファイルに残ります。提案内にそれらの行を繰り返すと、提案が適用された後に重複して表示されます。
• start_line の直前にある行でブロックを始めたり、line の直後にある行でブロックを終えたりしないでください。これらの行を基準として含める必要がある場合は、実際に置き換える範囲に含まれるように start_line または line を広げてください。
• 元の置換対象の行全体で、波括弧、角括弧、丸括弧、ブロック区切り（{、[、(、end など）の深さを数え、置換後も同じ深さで終わることを確認してください。存在しない閉じトークンを出力したり、必要なトークンを削除したりしないでください。
• 周囲の文脈が不確かな場合は、推測で周辺のトークンを扱うのではなく、差分内の実際の行を十分に含めるように start_line／line を広げてください。
• 複数行の提案では、最初の行に start_line と start_side を設定し、最後の行に line と side を設定してください。

出力形式

次の形式で review.json を作成してください。

{
  "verdict": "REJECT",
  "body": "## Overview\n...\n\n## Concerns\n- ...\n\n## Verdict\nFound: 1 critical, 2 important, 3 suggestions\n\n**Request changes**",
  "comments": [
    {
      "path": "path/to/file",
      "line": 42,
      "side": "RIGHT",
      "start_line": 40,
      "start_side": "RIGHT",
      "body": "⚠️ [IMPORTANT] Short explanation\n\n```suggestion\nreplacement\n```"
    }
  ]
}

フィールドのルール：

• verdict は必須で、値は文字列 "APPROVE" または "REJECT" に正確に一致する必要があります（大文字）。最終的な推奨を次のように対応させてください。Approve または Approve with nits → "APPROVE"、Request changes → "REJECT"。verdict とトップレベルの body に記載する人間向けの推奨は一致させてください。
• トップレベルの body は GitHub のレビュー本文であり、必須です。レビューの概要と最終的な推奨には、summary ではなく body を使用してください。
• comments は必須で、配列でなければなりません。インラインコメントがない場合は空の配列を使用してください。
• path はリポジトリルートからの相対パスでなければなりません。
• line は必須で、正しい側を対象にしなければなりません。
• start_line は任意で、複数行の範囲にのみ使用します。start_line を指定する場合は、start_side も必須で、値は "LEFT" または "RIGHT" でなければなりません。
• side は "LEFT" または "RIGHT" でなければなりません。

本文の要件

トップレベルの body には、次の内容を含める必要があります。

• PR の概要。
• 重要な懸念点、およびインラインでコメントできなかった未変更コードに関する懸念点。
• Found: X critical, Y important, Z suggestions 形式の問題件数。
• Approve、Approve with nits、Request changes のいずれかによる最終的な推奨。この推奨は、トップレベルの verdict フィールド（Approve / Approve with nits → "APPROVE"、Request changes → "REJECT"）と一致している必要があります。

判定前の監査

トップレベルの body を作成したり verdict を選んだりする前に、この監査を完了してください。差分全体を一通り読むだけでは不十分です。

• コメント：差分で追加または変更されたコメント（ドキュメントコメントまたはインラインコメント）をすべて、1 件ずつファイル名と行番号を添えて列挙してください。それぞれについて、リポジトリ独自のコメントガイドライン（どのような形式であっても）に照らして個別に確認してください。ガイドラインが定められていない場合は、プロジェクト内の既存コードにおけるコメントの分布（密度、文体、既存コメントで説明していることと省略していること）に照らして判断してください。コメントの文章の質、技術的な正確さ、または説明対象の問題がどれほど巧妙・重要かとは切り離して、準拠状況を評価してください。これらの要素は、適用されるガイドラインやコードベース独自の規範との明らかな不一致を正当化しません。
• テスト：差分で追加または変更されたすべてのテストを、リポジトリ独自のテストガイドラインに照らして確認してください。

最終確認

review.json を返す、またはアップロードする前に、次の確認を行ってください。

• 検証で失敗した場合は、無効な JSON を修正してください。
• 行番号が注釈付き差分と一致していることを確認してください。
• レビューしたものと同一の注釈付き差分に対して、同梱のバリデーターを実行してください。

  python3 .agents/skills/review-pr/scripts/validate_review_json.py --review-json review.json --diff pr_diff.txt
  

  スクリプトが無効なコメントを報告した場合は、review.json を修正して再実行してください。このバリデーターの検証に合格するまで、review.json を返したりアップロードしたりしないでください。スクリプトが指定された場所にない場合は、読み込まれた review-pr スキルディレクトリ内で validate_review_json.py を探し、同じ引数でそのコピーを実行してください。
• GitHub に投稿する gh pr review、gh pr comment、gh api、その他のコマンドは実行しないでください。

出力は最終的な review.json のみとしてください。