resolve-agent-reviews

現在の PR に対する PR レビューボット（Copilot、Cursor Bugbot、CodeRabbit など）の指摘を自動的に解決します。2 段階のワークフローを使用します。まず既存の問題をすべて修正し、その後、ボットの指摘がなくなるまで新たな指摘を確認します。

前提条件

以下のすべてのコマンドでは npx agent-reviews を使用します。プロジェクトで別のパッケージマネージャーを使用している場合は、適切なランナーに置き換えてください（例：pnpm の場合は pnpm dlx agent-reviews、Yarn の場合は yarn dlx agent-reviews、Bun の場合は bunx agent-reviews）。全体を通じて、ユーザーのパッケージマネージャーの設定を尊重してください。

クラウド環境のみ（Codespaces、リモートエージェントなど）：CI チェックでコミットとユーザーを紐付けられるように、Git の作成者 ID を確認してください。git config --global --get user.email を実行し、値が空またはプレースホルダーの場合は手動で設定します。ローカル環境ではこの確認を省略してください。

フェーズ 1：取得と修正（同期）

ステップ 1：すべてのボットコメントを取得する（詳細表示）

npx agent-reviews --bots-only --unanswered --expanded を実行します。

CLI は現在のブランチを自動検出し、関連する PR を見つけて、gh CLI または環境変数を使って認証します（トークンがない、PR がない、CLI がインストールされていないなどの問題が発生した場合は、明確なエラーメッセージを表示して終了します）。

未回答のボットコメントのみが、詳細とともに表示されます。詳細には、コメント本文全体（省略なし）、差分のハンク（コードのコンテキスト）、すべての返信が含まれます。各コメントの ID は角括弧内に表示されます（例：[12345678]）。

コメントが 1 件も返されない場合は、「No unanswered bot comments found」と表示し、フェーズ 2 に進みます。

ステップ 3：未回答のコメントを 1 件ずつ処理する

詳細表示の各コメントについて、次の手順に従います。

A. 指摘内容を評価する

該当するコードを確認し、次のいずれかを判断します。

1. 真陽性 - 修正が必要な実際のバグ
2. 偽陽性 - 実際にはバグではない（意図された動作、ボットの誤解など）
3. 判断できない - 確信が持てない場合は、ユーザーに確認する

真陽性の可能性が高い例：

• コードが明示された動作に明らかに違反している
• 未定義の可能性がある値に対する null チェックが不足している
• 型の不一致や、誤った関数シグネチャ
• 条件分岐のロジックエラー
• ドキュメントに記載された失敗ケースに対するエラー処理が不足している

偽陽性の可能性が高い例：

• ボットがフレームワークやライブラリのパターンを理解していない
• コードが意図的にそのように構成されている（理由を説明するコメントがある）
• ボットがバグではなく、スタイル上の好みを指摘している
• 「バグ」が実際には機能、または意図された動作である
• ボットがコードの処理フローを誤読している

判断できない場合 — ユーザーに確認する：

• 修正にアーキテクチャの変更が必要になる
• 動作が意図的なものか、本当に判断できない
• 「バグ」が、十分に理解できていないビジネスロジックに関係している
• 複数の解釈が妥当である
• 修正によって意図しない副作用が生じる可能性がある

B. 評価に基づいて対応する

真陽性の場合： コードを修正します。コメント ID と修正内容の簡単な説明を記録します。

偽陽性の場合： コードは変更しません。コメント ID と、実際のバグではない理由を記録します。

判断できない場合： ユーザーに確認します。ユーザーがスキップすると回答した場合は、スキップとして記録します。

まだコメントには返信しないでください。返信はコミット後に行います（ステップ 5）。

ステップ 4：コミットしてプッシュする

未回答のコメントをすべて評価し、修正した後、次の手順を実行します。

1. プロジェクトの lint と型チェックを実行する
2. ステージングし、コミットしてプッシュする：

   git add -A
   git commit -m "fix: address PR review bot findings
   
   {List of bugs fixed, grouped by bot}"
   git push
   

3. 出力からコミットハッシュを取得する。

ステップ 5：すべてのコメントに返信する

インラインレビューコメントに投稿する前に、npx agent-reviews --detail <comment_id> を実行して最新の返信を確認します。PR レベルの課題コメントとレビューの概要にはスレッド形式の返信一覧がありません。これらの種類で一覧が空でも、結果が記録されていないということではありません。CLI はこれらの種類への返信をスキップします。スキップしたことを記録し、代わりのトップレベルコメントを作成したり、別のツールで回避したりしないでください。同じ結果がすでに記録されている場合は、再度投稿しないでください。セッションを再開したときは、以前のセッションの作業キューを再実行するのではなく、最新の未回答一覧を使用してください。新たな議論またはユーザーの依頼があった場合に限り、判断を見直してください。

複数行または複雑な返信の場合は、リポジトリ外の一時ディレクトリに一意の名前を付けた UTF-8 ファイルを作成し、npx agent-reviews --reply <comment_id> --body-file <path_to_reply_file> を使用します（以下で適切な場合に限り --resolve を追加します）。CLI は絶対パスと相対パスを受け付けます。リポジトリ外の一時ファイルには、絶対パスを使用してください。シェルのコマンド置換を使わず、ファイルパスを直接指定してください。返信が成功したら一時ファイルを削除します。投稿に失敗した場合も、一時ファイルはリポジトリ外に置いたままにしてください。後で実行する git add -A コマンドでファイルがコミットされるのを防ぐためです。

コミットハッシュが確定したので、処理したすべてのコメントに返信します。--resolve フラグは GitHub でレビュースレッドを解決済みにします。会話を終了するとき（誤検知とユーザーがスキップした指摘）に限り使用し、レビュー担当者が引き続き確認する必要のある修正には使用しないでください。

TRUE POSITIVE ごと（修正済み。レビュー担当者やボットが確認できるよう、スレッドは未解決のままにします）：

npx agent-reviews --reply <comment_id> "Fixed in {hash}. {Brief description of the fix}" を実行します

FALSE POSITIVE ごと（会話を終了します）：

npx agent-reviews --reply <comment_id> "Won't fix: {reason}. {Explanation of why this is intentional or not applicable}" --resolve を実行します

SKIPPED ごと（ユーザーが対応しないことを選択しました）：

npx agent-reviews --reply <comment_id> "Skipped per user request" --resolve を実行します

スレッド化できないコメント： 指摘が PR レベルの課題コメントまたはレビュー概要の投稿として行われた場合（特定の行に対するインラインレビューコメントではない場合）、CLI はスレッド形式で返信できず、⊘ Skipped reply: comment is not part of a review thread と表示します。これは想定どおりの動作です。結果を概要に記録して次に進み、再試行しないでください。

---

すべての返信を投稿するまで、フェーズ 2 を開始しないでください。

---

フェーズ 2：HEAD コミットのチェックが完了するまで待機する（クリーンな状態になるまでループ）

多くのレビューボット（Greptile、Cursor Bugbot、CodeRabbit など）は、CI と並んでコミットのチェックとして結果を報告します。そのため、コミットのチェックが完了した時点でレビューも完了します。--wait-checks はその時点まで待機し、その後、対応が必要な内容だけを出力します。

ステップ 6：待機してからレポートに対応する

パスが 0 で終了するまで繰り返します。

6a. npx agent-reviews --wait-checks --bots-only --unanswered をバックグラウンドタスクとして実行し、終了するまでほかの作業を続けます。gh pr checks --watch、スリープループ、または一覧の繰り返し表示でポーリングしてはいけません。

プレビューのデプロイ後にのみ開始されるものなど、チェックの登録が遅れるレビュアーごとに --expect "<check name>" を追加し、報告前に待機が終了しないようにします。ドラフト PR では、レビューボットは通常レビューをスキップするため、期待するチェックの完了を待ちません。

6b. レポートを読みます。1 行目にはコミットと結果が記載され、その下には失敗したチェックとリンク、報告されなかった期待するチェック、未回答のインラインコメント、PR レベルのコメントが記載されます。PR レベルのコメント（issue コメント、レビューの要約）には返信用のスレッドがないため、毎回一覧に表示されます。この実行中にまだ対応していない ID のみ処理してください。終了コードに応じて対応します。

• 0：すべてのチェックに合格し、コメント待ちもありません。サマリーレポートに進みます。
• 1：チェックが失敗した、期待するチェックが報告されなかった、またはインラインコメントが未対応です。Phase 1 の Steps 3-5 と同じようにコメントを処理します（評価、修正、コミット、プッシュ、返信）。失敗したチェックも指摘事項です。ログを読み（GitHub Actions の場合は gh run view <id> --log-failed、レビューボットや外部ステータスの場合はリンクを開く）、修正してコミットし、プッシュします。その後、Step 6a に戻ります。問題が報告されていない期待するチェックだけの場合は、再度待機せず、サマリーレポートにその名前を記載して終了します。
• 2：PR がベースブランチと競合しているため、CI は実行されません。ベースブランチをマージまたはリベースし、プッシュしてから Step 6a に戻ります。
• 3：チェックが実行中のままタイムアウトしました（デフォルトは 30 分、--timeout <seconds>）。保留中のチェックを報告します。
• 4：コミットに登録されたチェックがありません。その旨を報告します。このブランチではリポジトリに CI が設定されていない可能性があります。

待機中にプッシュすると、自動的に新しいヘッドコミットを追跡します。

ラウンド上限。 このフェーズでの修正プッシュは、指摘事項が 6b と下記のコメントウォッチャーのどちらから届いたかにかかわらず、1 ラウンドとして数えます。以前の修正コミットで変更した行に新たな指摘が続けて届く場合、それぞれの修正が次のエッジケースを生み出しており、パッチを追加しても収束しません。そのようなラウンドが 2 回に達したら終了し、それ以上の修正をプッシュしないでください。残っている指摘事項と各修正ラウンドで変更した内容をユーザーに報告し、続行する前に、たとえば敵対的な設計レビューなどで設計全体を見直すことを提案します。以前の修正で触れていないコードに対する指摘は、上限に数えません。

チェックを伴わずに投稿するレビュアー（たとえば Copilot）に限り、コメントウォッチャーを使用します。--wait-checks が問題なく完了したら、npx agent-reviews --watch --bots-only --unanswered --timeout 180 を 1 回実行します。指摘事項が返された場合は、Phase 1 の Steps 3-5 と同じように処理し、Step 6a に戻って新しいコミットのチェックも待機します。

---

サマリーレポート

両方のフェーズが完了したら、サマリーを提示します。

## PR Review Bot Resolution Summary

### Results
- Fixed: X bugs
- Already fixed: X bugs
- Won't fix (false positives): X
- Skipped per user: X

### By Bot
#### cursor[bot]
- BUG-001: {description} - Fixed in {commit}
- BUG-002: {description} - Won't fix: {reason}

#### Copilot
- {description} - Fixed in {commit}

### Status
All findings addressed. Every check on the head commit passed.

重要な注意事項

応答ポリシー

• すべての指摘事項に返信すること - 黙って無視しないでください
• 返信はボットの学習に役立ち、判断の記録にもなります
• 「修正しない」という返信をすれば、同じ誤検知が再度指摘されるのを防げます

ユーザーとのやり取り

• 指摘事項について判断に迷ったら、ユーザーに尋ねてください
• アーキテクチャやビジネスロジックに関する質問を推測で判断しないでください
• 誤った修正や誤った却下をするより、尋ねるほうが適切です

ベストプラクティス

• 修正前に指摘事項を検証してください。ボットには誤検知があります
• 修正は最小限に絞り、関連のないコードのリファクタリングは避けてください
• コミット前に型チェックと lint を通してください
• 関連する修正は 1 つのコミットにまとめてください
• Copilot の suggestion ブロックには、そのまま使える修正案が含まれていることがよくあります