resolve-human-reviews

現在の PR に対する人間のレビューコメントを自動的に解決します。未回答の人間からのフィードバックを取得し、各コメントを評価して、適切な場合は修正を適用し、すべてのコメントに結果を返信します。

前提条件

以下のコマンドはすべて 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 --humans-only --unanswered --expanded を実行します。

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

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

コメントが 0 件の場合は、「未回答の人間のコメントは見つかりませんでした」と出力し、フェーズ 2 に進みます。

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

詳細表示された出力に含まれるコメントごとに、次の処理を行います。

A. フィードバックを評価する

参照されているコードとレビュアーのコメントを確認します。人間のレビュアーは一般に、ボットより正確で、コンテキストをよく理解しています。フィードバックを適切に重視してください。次のいずれかに分類します。

1. 対応が必要 — レビュアーが実際の問題を指摘したか、具体的な変更を求めています
2. 要相談 — コメントは妥当な指摘ですが、適切な対応方法が明確ではありません
3. 対応済み — 懸念事項はすでに修正されているか、もはや該当しません

対応が必要な可能性が高いケース：

• レビュアーがバグやロジックの誤りを指摘している
• レビュアーが具体的なコード変更を求めている
• レビュアーが考慮されていないエッジケースやエラー処理を指摘している
• レビュアーが、明確な修正方法とともに命名、API、またはアーキテクチャ上の懸念を指摘している
• レビュアーが根拠を示して、より良い方法を提案している

要相談となる可能性が高いケース — ユーザーに確認してください：

• レビュアーが、確信を持てないアーキテクチャの変更を提案している
• コメントがトレードオフ（パフォーマンスと可読性など）に関わる
• レビュアーの提案が、コードベースの他の箇所で使われているパターンと矛盾している
• チーム内の合意がないまま、スタイルや命名の好みといった主観的なフィードバックが寄せられている
• フィードバックに異論があり、作成者の意見を求めたい

対応済みである可能性が高いケース：

• レビューの投稿後にコードが変更されている
• 別のコミットですでに問題が修正されている
• コメントが、すでに存在しないコードを指している

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

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

要相談の場合： ユーザーに PR の作成者へ相談するよう依頼します。ユーザーの判断に従って対応し、その内容を記録します。

対応済みの場合： コメント ID と、対応済みと判断した理由を記録します。

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

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

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

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

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

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

Step 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 上でレビューのスレッドを解決済みにします。会話を終了するとき（議論が完了した、すでに対応済みなど）にのみ使用し、レビュアーによる確認がまだ必要な新たな修正には使用しないでください。

各 ACTIONABLE について（修正済み。レビュアーが確認できるよう、スレッドは未解決のままにします）：

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

各 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 を実行します。

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

---

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

---

Phase 2: 追加コメントをポーリングする（静かになるまでループ）

新しいコメントが見つかると、ウォッチャーは（一括投稿を検出するための 5s の猶予期間後に）直ちに終了します。そのため、ループで実行します。ウォッチャーを起動し、返されたコメントを処理してからウォッチャーを再起動し、新しいコメントがないままタイムアウトするまで繰り返してください。

ステップ 6：ウォッチャーループを開始する

ウォッチャーが新しいコメントなしで終了するまで、以下を繰り返します。

6a. ウォッチャーをバックグラウンドで起動します。

npx agent-reviews --watch --humans-only --unanswered をバックグラウンドタスクとして実行します。

起動時に、EXISTING COMMENTS と、この実行ですでに処理した ID、および --detail で確認した最新の返信を照合し、すでに記録済みの結果を再処理しないでください。ベースラインには、フェーズ 1 とウォッチャー起動の間に投稿された、未処理の指摘が含まれる場合があります。含まれていた場合は、ウォッチャーを停止し、その指摘をステップ 3～5 で処理してから再起動します。この実行ですでにスキップしたスレッド化できないコメントも記録し、再起動ループが発生しないようにします。ベースラインとの照合が済んだら、ウォッチャー終了時に EXITING WITH NEW COMMENTS とともに報告された ID を処理します。

6b. バックグラウンドコマンドが完了するまで待ちます（デフォルトは 10 分です。--timeout で変更できます）。

6c. 出力を確認します。

• 新しいコメントが見つかった場合（出力に EXITING WITH NEW COMMENTS が含まれる場合）：

  1. --detail <id> を使って、新しい各コメントの詳細を確認します
  2. フェーズ 1 のステップ 3～5 と同じ手順で処理します（評価、修正、コミット、プッシュ、返信）
  3. ステップ 6a に戻り、ウォッチャーを再起動します

• 新しいコメントがない場合（出力に WATCH COMPLETE が含まれる場合）： ループを終了し、概要レポートに進みます。

---

概要レポート

両方のフェーズが完了したら、概要を報告します。

## PR Review Resolution Summary

### Results
- Fixed: X issues
- Already addressed: X
- Discussion resolved: X
- Skipped per user: X

### By Reviewer
#### @reviewer-name
- {description} - Fixed in {commit}
- {description} - Already addressed

### Status
All review comments addressed. Watch completed.

重要な注意事項

返信ポリシー

• すべてのコメントに返信します ― 黙って無視しないでください
• 返信によりレビュアーに状況を伝え、承認を進めやすくします
• 「対応済み」のコメントにも、必ず確認したことを伝えてください

ユーザーとのやり取り

• 適切な対応が明確でない場合は、ユーザーに確認してください
• 人間のレビュアーは、あなたにない背景情報を持っていることがよくあります。不確かな場合は作者の判断を優先してください
• 作者が承認しないような変更を加えるより、質問するほうが適切です

ベストプラクティス

• 一般に、人間のレビュアーはボットより正確です。基本的にはフィードバックを信頼してください
• 修正は最小限かつ的を絞り、無関係なコードのリファクタリングは避けてください
• コミットする前に、型チェックとリンターを通してください
• 関連する修正は 1 つのコミットにまとめてください
• レビュアーが具体的なコード変更を提案した場合、問題が生じない限り、その案を優先してください