resolve-reviews

現在の PR に対するレビューコメント（人間とボットの両方）をすべて自動的に解決します。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 --unanswered --expanded を実行します。

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

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

コメントが 0 件の場合は、「未回答のコメントはありません」と表示し、フェーズ 2 に進みます。

ステップ 3：未回答のコメントをそれぞれ処理

詳細表示の出力に含まれるコメントごとに、投稿者がボットか人間かに応じた適切な評価を行います。

ボットのコメントの場合

参照先のコードを読み、次のいずれかを判断します。

1. 真の問題 - 修正が必要な実際のバグ
2. 誤検知 - 実際にはバグではない（意図した動作、ボットの誤解）
3. 判断不能 - 確信が持てない。ユーザーに確認する

真の問題である可能性が高いケース：

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

誤検知である可能性が高いケース：

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

人間のコメントの場合

参照先のコードとレビュー担当者のコメントを読みます。人間のレビュー担当者は、一般にボットよりも正確で、文脈をよく理解しています。次のいずれかを判断します。

1. 対応が必要 - レビュー担当者が実際の問題を特定した、または具体的な変更を依頼した
2. 議論が必要 - コメントは妥当な指摘だが、適切な対応方法が明確でない
3. 対応済み - 懸念点はすでに修正されている、または該当しなくなっている

対応が必要である可能性が高いケース：

• レビュー担当者がバグやロジックエラーを指摘している
• レビュー担当者が具体的なコード変更を依頼している
• レビュー担当者がエッジケースやエラー処理の不足を指摘している

議論が必要なケース（ユーザーに確認）：

• レビュー担当者が、確信の持てないアーキテクチャ変更を提案している
• コメントがトレードオフ（パフォーマンスと可読性など）に関わる
• チーム内で合意がないまま、主観的なフィードバックが寄せられている

判断に迷った場合（ユーザーに確認）

ボットと人間のどちらのコメントでも、次の場合はユーザーに確認します。

• 修正にアーキテクチャの変更が必要となる
• 動作が意図的なものか、本当に判断できない
• 複数の妥当な解釈がある
• 修正によって意図しない副作用が生じる可能性がある

評価に基づいて対応

真の問題／対応が必要： コードを修正します。コメント ID と、修正内容の簡潔な説明を記録します。

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

議論が必要： ユーザーに PR の作成者への確認を依頼します。ユーザーの判断に従って対応し、その内容を記録します。

対応済み： コメント ID と、その理由を記録します。

判断不能： ユーザーに確認します。スキップするよう指示された場合は、スキップとして記録します。

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

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

未回答のコメントをすべて評価し、修正した後に：

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

   git add -A
   git commit -m "fix: address PR review findings
   
   {List of changes made, grouped by reviewer/bot}"
   git push
   

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

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

インラインレビューコメントに投稿する前に、npx agent-reviews --detail <comment_id> を実行して最新の返信を確認します。PR レベルの issue コメントとレビューの要約にはスレッド形式の返信リストがありません。これらの種類でリストが空でも、対応結果が記録されていない証拠にはなりません。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 を実行します

各 DISCUSSION について（ユーザーの判断後。判断をもってスレッドを終了します）：

npx agent-reviews --reply <comment_id> "{Outcome}. {Explanation of the decision and any changes made}" --resolve を実行します

各 ALREADY ADDRESSED について（追加対応は不要です）：

npx agent-reviews --reply <comment_id> "Already addressed. {Explanation of when/how this was fixed}" --resolve を実行します

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

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

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

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

---

フェーズ 2：HEAD コミットのチェックを待つ（クリーンになるまでループ）

ほとんどのレビューボット（Greptile、Cursor Bugbot、CodeRabbit など）は、CI と並行してコミットのチェックとして結果を報告するため、コミットのチェックが完了した時点でレビューも完了します。--wait-checks はその完了を待ち、対応が必要な項目だけを表示します。

Step 6: 待機してからレポートに対応する

終了コードが 0 になるまで繰り返します。

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

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

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

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

待機中にプッシュした場合は、自動的に新しい HEAD コミットを追跡します。

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

チェックを伴わずに投稿するレビュアー（たとえば Copilot）には、コメントウォッチャーを使います。--wait-checks が問題なく完了したら、npx agent-reviews --watch --unanswered --timeout 180 を 1 回実行します。指摘事項が返された場合は、フェーズ 1 のステップ 3～5 と同じ手順で対応し、新しいコミットのチェックも待機するため、ステップ 6a に戻ります。

---

サマリーレポート

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

## PR Review Resolution Summary

### Results
- Fixed: X issues
- Already addressed: X
- Won't fix (false positives): X
- Discussion resolved: X
- Skipped per user: X

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

#### @reviewer-name
- {description} - Fixed in {commit}

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

重要な注意事項

返信ポリシー

• すべてのコメントに返信する — 黙って無視しないでください
• ボットの場合：返信はボットの学習に役立ち、誤検知の再報告を防ぎます
• 人間の場合：返信によりレビュアーに状況を伝え、承認を妨げる問題を解消できます

ユーザーとのやり取り

• 指摘事項に確信が持てない場合は、ユーザーに確認してください
• アーキテクチャやビジネスロジックに関する質問を推測で判断しないでください
• 誤った修正や却下をするより、質問するほうが適切です
• 人間のレビュアーにはあなたが知らない背景情報があることが多いため、確信が持てない場合は作成者の判断を優先してください

ベストプラクティス

• 修正する前に指摘事項を検証してください。ボットは誤検知することがありますが、人間の指摘が誤検知であることはまれです
• 修正は最小限かつ対象を絞り、無関係なコードをリファクタリングしないでください
• コミット前に型チェックとリンターを通してください
• 関連する修正は 1 つのコミットにまとめてください
• Copilot の suggestion ブロックには、そのまま使える修正案が含まれていることがよくあります
• 人間のレビュアーが具体的なコード変更を提案した場合、問題が生じない限り、その案を優先してください