address-review-bots

レビューボットへの対応

使用するタイミング

PR の作成後またはプッシュ後に、ユーザーが Claude、Devin などのレビューボットからのフィードバックを待つこと、ボットのコメントに対応すること、またはボットのレビューで問題がなくなるまで反復することを求めた場合に使用します。

これはローカルでの検証を補完するものです。対象リポジトリで通常行うプッシュ前またはマージ前のチェックに代わるものではありません。

基本的な手順

1. 現在のブランチに PR があることを確認します。

gh pr view --json number,url,headRefOid,headRefName

PR がない場合は停止し、このスキルには既存の PR が必要であることをユーザーに伝えます。

2. プッシュの直前または直後に、レビュー対象期間を記録します。

REVIEW_BOT_SINCE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

3. レビューボットのチェックを待ち、新しいコメントをスナップショットします。

mkdir -p .context
node scripts/review-bot-snapshot.mjs \
  --wait \
  --since "$REVIEW_BOT_SINCE" \
  --json > .context/review-bot-snapshot.json

このスキルのディレクトリから、同梱されている scripts/review-bot-snapshot.mjs を実行します。エージェントがスキルのディレクトリを基準に実行できない場合は、まずこの SKILL.md があるディレクトリを特定してから、スクリプトのパスを明示して渡します。

すでに投稿されたコメントを対象にしていて、プッシュ時刻を記録していない場合は、--since を省略します。

4. 新しいボットコメントを分類します。

• valid_actionable：マージ前に修正すべき実際の問題をボットが見つけたものです。
• already_fixed_or_stale：現在のヘッドでは問題が存在しないか、コメントが古いヘッドを指しているものです。
• false_positive：ボットの指摘が誤っているものです。具体的なコード上の根拠を集めます。
• needs_user_decision：明白な正確性の修正ではなく、プロダクト、UX、アーキテクチャに関する方針に関わる変更です。
• valid_low_risk_cleanup：マージを妨げるものではありませんが、低コストで客観的に実施でき、リポジトリの規約にも沿った、実際の改善点をボットが見つけたものです。
• non_actionable：要約、称賛、進捗報告、「問題なし」といったコメントです。

「ブロッキングではない」「細かな指摘」「インラインで変更するほどのものはない」などの表現だけを根拠に、自動的に non_actionable と分類しないでください。コメントに具体的なコードへの言及、もっともらしい障害の可能性、一貫性の問題、または保守性に関する懸念が含まれている場合は、該当コードを確認し、内容に基づいて分類します。

valid_actionable のコメントは自動で修正します。また、変更範囲が明確に限定されており、ユーザーの判断が必要な形でプロダクト、UX、アーキテクチャの方針、または公開される挙動を変えない場合は、valid_low_risk_cleanup のコメントも自動で修正します。リポジトリの規約から判断が明白でない限り、プロダクト、UX、アーキテクチャに関するトレードオフはユーザーに委ねます。

次に進む前に、実質的なボットの指摘すべてについて、メモまたは最終回答に簡潔な分類表を作成します。

permalink | isOutdated or n/a | claim | classification | evidence | reply/resolution action or why left open

5. valid_actionable のコメントに対して、対象を絞った修正と関連するテストを追加します。

6. 差分をセルフレビューしてから、リポジトリの最終検証コマンドを実行します。

ユーザーが REVIEW_BOT_VALIDATION_COMMAND を設定している場合は、そのコマンドをそのまま使用します。設定されていない場合は、以下の順に検証方法を特定します。

1. リポジトリの指示または CI で必須とされているコマンドを使用します。
2. 該当するパッケージのマニフェストを確認します。リポジトリのルートから開始し、変更したパッケージについてはワークスペースの設定に従います。パッケージマネージャーは、ルートのマニフェストにある packageManager フィールド、次にロックファイル（pnpm-lock.yaml、yarn.lock、package-lock.json、npm-shrinkwrap.json、bun.lock、bun.lockb）から判定します。別の実行ファイルが利用可能だからといって、パッケージマネージャーを切り替えてはいけません。
3. precommit パッケージスクリプトがある場合は、判定したパッケージマネージャーで実行します。例：pnpm run precommit、yarn run precommit、npm run precommit、bun run precommit。
4. precommit がない場合は、利用可能な lint と test の各パッケージスクリプトを、同じパッケージマネージャーで実行します。存在しないスクリプトは実行せず、そのスクリプトがないことを検証失敗として扱ってはいけません。
5. どちらのスクリプトもない場合は、リポジトリに記載された JavaScript 以外のチェック、または CI に相当するチェックを使用します。見つからない場合は、コマンドを独自に作らず、検証できる範囲がないことを報告します。

反復中は対象を絞ったチェックを使用できますが、レビュー修正をコミットまたはプッシュする前に、最後のコード変更後、特定した最終検証コマンドをすべて実行してください。

7. 修正を行った場合はコミットしてプッシュします。

git add <fixed-files>
git commit -m "fix: address review bot feedback"
git push

8. 有効で対応可能な新しいコメント、または有効でリスクの低いクリーンアップに関するボットコメントがなくなるまで、あるいは残ったコメントが古いもの、対応不要なもの、誤検知、ユーザーの判断が必要なものになるまで、またはそれ以上の変更が推測に基づくものになるまで、ステップ 2 から繰り返します。

9. 安定した最新のヘッドごとに、未解決の対象範囲内のレビュー スレッドを確認し、ボットのループがクリーンだと宣言する前に、以下のレビュー スレッドのクリーンアップ方針を適用します。

ユーザーが継続を明示的に求めていない限り、修正をプッシュするループは最大 8 回までとします。

レビューの判断

レビュー ボットからのコメントは判断材料として扱い、絶対的な権威とはみなしません。有効なコメントには、コード、テスト、生成された成果物、またはリポジトリの慣例に基づく具体的な根拠が必要です。重要な指摘を修正または却下する前に、参照されたファイルと周辺のコードを確認してください。

レビュー ボットは、新しいレビュー コメントを作成する代わりに、既存のトップレベルの概要コメントを更新する場合があります。新しいボットのステータスコメントにレビュー概要が投稿または更新されたと記載されている場合は、その概要の createdAt が現在のレビュー期間より前で、スナップショットでは古いコメントとして分類されていても、その概要を確認してください。その場合は、updatedAt とステータスコメントの内容を基に、概要を分類する必要があるか判断します。

古いインラインコメントについては、スナップショットのヘッド SHA、コメントのコミット ID、現在のコードを比較します。

解決可能なレビュー スレッド外のコメントについては、却下の理由を今後のレビュアーが理解する助けになる場合、PR に短い返信を残してください。レビュー スレッドについては、以下のより厳格な「返信してから解決」のルールに従ってください。

レビュー スレッドのクリーンアップ

GitHub の isResolved フィールドと isOutdated フィールドを取得できるツールを使用して、未解決のレビュー スレッドを照会します。スナップショット ヘルパーの新しい／古いコメントの分類は、コメントの SHA と時刻に基づくものであり、GitHub の isOutdated 値の代わりにはなりません。スレッドを変更する前に、PR のヘッドが引き続き想定した現在の SHA であることを確認してください。

解決する前に、未解決の対象範囲内の各スレッドについて現在のコードを確認し、分類してください。

• isOutdated: true の場合は、現在のヘッドで問題が修正済みであるか、関連性がなくなっていることを確認します。その確認が済んでからスレッドを解決してください。追加の背景情報が役立つ場合を除き、PR への返信は不要です。問題が引き続き関連している場合、判断が曖昧な場合、またはユーザーの判断が必要な場合は、スレッドを未解決のままにしてください。
• isOutdated: false の場合は、返信せずに解決してはいけません。問題が修正済みまたは古くなっている場合は、まず同じレビュー スレッドに、懸念に対処する関数や挙動、および関連するテストなど、現在のヘッドに基づく具体的な根拠を示した簡潔な説明を返信してください。GitHub が返信の投稿を確認してから、スレッドを解決します。返信に失敗した場合は、スレッドを未解決のままにし、失敗を報告してください。
• 指摘が依然として有効な場合、適切な修正が曖昧な場合、根拠が弱い場合、または解決にプロダクト、UX、公開 API、アーキテクチャに関する判断が必要な場合は、スレッドを未解決のままにしてください。パーマリンクと、未解決のままにする理由を報告してください。

false_positive という分類だけを理由に、古くなっていないスレッドを解決してはいけません。現在のヘッドに基づく具体的な根拠によって懸念が古くなっている、または該当しなくなっていると確認できる場合に限り解決し、その根拠を先にスレッド内へ返信してください。

返信の例：

現在のヘッドで対応済みです。addOrReplaceNewerTarget は mergeReopenTargetFields に委譲するようになり、フォーカス中のウィンドウを対象とするターゲットがイベント由来のターゲットを置き換える際に、bundleId が保持されます。tools.test.ts でテスト済みです。

プッシュ前のセルフレビュー

レビューボットの修正を適用した後、コミットまたはプッシュする前に、別のエンジニアが変更したかのように立ち止まってレビューしてください。自分で書いたからといって、パッチが正しいと思い込まないでください。

git diff 全体、編集したすべてのファイル、関連する呼び出し元やテスト、修正がボットの例だけでなく根本的な問題に対処しているかどうか、新たなエッジケースやテスト不足を招いていないかを確認してください。

目標は、8回すべてのループを使い切ることではありません。レビューボットやCIに再修正させずに済む修正をプッシュすることです。

プッシュ後に新たな有効で対応可能なボットの指摘があった場合は、次のセルフレビューをより掘り下げてください。まず差分を重点的にレビューし、次に関連ファイルやテストを確認し、見落としが続く場合はモジュールレベルの前提や障害モードを確認します。見落としが繰り返される場合は、ローカルレビューで確認しているコンテキストが不足しています。ペースを落とし、プッシュ前にサブシステム全体を調べてください。

待機ルール

GitHub の待機は必要な場合に限ってください。このスキルはプッシュ後の PR レビュー自動化向けです。通常の実装作業では、通常、リポジトリのローカル検証コマンドのほうが迅速な確認手段になります。このヘルパーは Claude、Devin、または review パターンに一致するレビュー形式のチェックを待機し、無関係な CI のために無期限に待機することはありません。

ヘルパーのデフォルトの待機上限は 35 分です。これは Claude のレビューワークフローのジョブ上限である 30 分を超えるよう設定されています。どちらかの上限を変更する場合は、両方の値を連動させてください。

ヘルパースクリプト

GitHub API コマンドを書き直すのではなく、scripts/review-bot-snapshot.mjs を使用してください。デフォルトのボットは Claude と Devin です。必要に応じて --bot-logins または REVIEW_BOT_LOGINS で上書きしてください。

一般的なオプション：

node scripts/review-bot-snapshot.mjs --help
node scripts/review-bot-snapshot.mjs --wait
node scripts/review-bot-snapshot.mjs --wait --json
node scripts/review-bot-snapshot.mjs --pr 123 --bot-logins "claude[bot],devin-ai-integration[bot]"

最終回答

次の内容を報告してください。

• 実行したレビューボットのループ数。
• 修正したボットのコメント。
• 棄却したコメント、またはユーザーの判断に委ねたコメントと、そのパーマリンク。
• 実質的なボットの指摘それぞれの分類と、その理由。
• プッシュしたコミット SHA。
• 最終検証コマンドとその結果。
• 解決したレビュー スレッドの数。
• GitHub が isOutdated: true としてマークしたため、通知なしで解決した件数。
• スレッド内で説明の返信を投稿した後に解決した件数。
• 未解決のまま残したすべてのスレッドと、そのパーマリンクおよび理由。

有効なコメントが残っていない場合は、実質的な指摘をそれぞれ分類した後でのみ、その旨を明確に述べてください。レビューのチェックがタイムアウトした場合は、確認できた内容と、まだ不明な点を記載してください。