pr-comment-triage

PR コメントのトリアージ

現在の PR にあるすべてのコメントを確認し、それぞれについて慎重に判断してください。コードで対応する、説明を求める返信をする、またはすでに対応済みであれば解決します。対応済みであることを確認したレビュー スレッドはすべて解決し、解決する際は必ず短い説明を返信してください。

指摘とは、コードに関する主張であって、コードについての事実ではありません。これはすべての投稿者に当てはまり、ひとつの差分だけを見て、人間のレビュアーが持つ文脈を把握できない AI レビューエージェントにはなおさら当てはまります。主張によってコードを変更する前に、それぞれの内容をコードで確認してください。

対象範囲

ユーザーが、次のような依頼を含め、現在の PR へのフィードバックに関する支援を求めている場合にこのスキルを使用します。

• 「PR のコメントを確認して」
• 「レビューのフィードバックをトリアージして」
• 「これらの PR コメントにまだ対応が必要か確認して」
• 「対応済みのレビューコメントを解決して」

このスキルの対象は、現在のブランチ上にある現在の PR です。

ルール

• スレッドが対応済みかどうかは慎重に判断します。ただし、対応済みと確認できたら解決し、確認済みの対応済みスレッドを未解決のまま残してはいけません。
• 解決する理由（コードで修正済み、指摘が無効、古くなっている、または議論で決着済み）にかかわらず、解決する前に必ずスレッドへ短い説明を返信してください。
• PR に投稿するコメント（スレッドへの返信とトップレベルコメントの両方）には、末尾に帰属表示の行 🤖 Generated with Claude Code を付けてください。コメント本文の最後に、独立した行として記載してください。
• 投稿したコメントをすべて報告してください。投稿時に API のレスポンスから各コメントの URL を取得し、リンクを決して再構成したり推測したりしないでください。実行の最後に、投稿したコメントをすべて、それぞれ 1～2 文に短縮して列挙してください。
• API レスポンスのすべてのページを読み取ってください。GitHub は 1 ページあたり最大 100 件を返すため、ページネーションなしの取得では一覧が不完全です。ページネーションに対応したコマンドについては、現在の PR を特定するを参照してください。
• このスキルは繰り返し実行できます。同じ PR で何度も実行される可能性があるため、実行のたびに最新の状態を取得してください。以前の実行で取得した一覧に頼らず、前回以降に追加されたコメントを毎回確認し、コードによって対応済みまたは古くなった可能性がある未解決スレッドも再確認してください。
• レビュー スレッドとトップレベルの PR コメントを区別してください。
  • レビュー スレッドは解決できます。
  • トップレベルの PR 会話コメントは GitHub 上で解決済みにできません。返信するか、そのままにすることだけができます。
• すべてを一括で無条件に解決してはいけません。
• 判断する前に、現在のコードとその周辺の議論を読んでください。
• コメントが曖昧な場合、ほかのフィードバックと矛盾する場合、またはプロダクトやアーキテクチャ上の判断が必要な場合は、推測せずユーザーに確認してください。
• AI が作成したすべての指摘は、未検証の主張として扱ってください。 Copilot、CodeRabbit、Devin、Greptile、Graphite、任意の [bot] アカウント、およびリポジトリが実行する社内レビューエージェントなどのレビューエージェントは、リポジトリの履歴、慣例、呼び出し元、テストを知らずに差分を読みます。周辺のコードですでに防がれている不具合を報告したり、このプロジェクトには存在しないシンボルや API を挙げたり、プロジェクトが採用しないと決めた変更を求めたりします。自信に満ちた言い方は、根拠にはなりません。AI が作成した指摘をより厳しく確認するを参照してください。
• 確認できなかった指摘を満たすためにコードを変更してはいけません。 未確認の主張は、念のため対応するものではなく、却下すべき主張です。返信では、コードが実際にどのように動作するかを説明してください。
• 懐疑的であることは、指摘を退けることではありません。エージェントの指摘が正しい場合もあり、確認できた指摘にはほかの指摘と同様に対応します。変わるのは立証責任であって、対応する意思ではありません。

ワークフロー

1. 現在の PR を特定する

チェックアウト中のブランチに対応する現在の PR を取得します。

推奨コマンド：

gh pr view --json number,title,url,headRepositoryOwner

レビュー スレッドを取得するには gh api graphql を使用してください。必要なスレッド一覧全体を gh pr view では取得できないことがあります。

取得する情報：

• PR 番号、タイトル、URL
• 次の情報を含むレビュー スレッド：
  • スレッド ID
  • 解決済みかどうか
  • ファイルパス／行番号（取得できる場合）
  • スレッド内のすべてのコメント
• PR の会話にあるトップレベルの issue コメント

すべてのページを読み込む

GitHub は各レスポンスを 100 件に制限しており、gh pr view --json comments,reviews が返すのは最初のページのみです。取得が途中で切れてもエラーは表示されないため、すべてのリスト取得呼び出しで --paginate を指定し、hasNextPage が false になるまでカーソルをたどってください。

REST エンドポイント — --paginate は Link ヘッダーをたどって最終ページまで取得します。

gh api --paginate repos/OWNER/REPO/issues/PR_NUMBER/comments   # top-level conversation
gh api --paginate repos/OWNER/REPO/pulls/PR_NUMBER/comments    # review thread comments
gh api --paginate repos/OWNER/REPO/pulls/PR_NUMBER/reviews     # review summaries

GraphQL — クエリで $endCursor 変数を宣言し、pageInfo { hasNextPage endCursor } をリクエストする必要があります。そうしないと、--paginate は次のページに進めません。

gh api graphql --paginate -F owner='OWNER' -F repo='REPO' -F pr=PR_NUMBER -f query='
query($owner:String!, $repo:String!, $pr:Int!, $endCursor:String) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $pr) {
      reviewThreads(first: 100, after: $endCursor) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id
          isResolved
          isOutdated
          path
          line
          comments(first: 100) {
            pageInfo { hasNextPage endCursor }
            nodes { id author { login __typename } createdAt body url }
          }
        }
      }
    }
  }
}'

--paginate がたどるのは、クエリごとに 1 つのコネクション（ここでは reviewThreads）です。ネストされたコネクションにはそれぞれ独自の上限があるため、comments が hasNextPage: true を返すスレッドでは、そのスレッドの残りを取得するために別途クエリを実行する必要があります。

各コメントの投稿者を記録する

author.__typename は、Copilot や CodeRabbit などの GitHub App アカウントでは Bot です。REST での同等の値は user.type です。通常のユーザーアカウントで投稿するエージェントは User として返されるため、ログイン名もこのリポジトリで実行されるレビューエージェントと照合してください。社内エージェントは、タイプだけでは人間と区別できません。すべてのコメントに、human または agent の印を付けてください。この印によって、そのコメントをコードに反映する前にどの程度の根拠が必要かが決まります。

現在のブランチに PR が存在しない場合は、作業を中止してユーザーに伝えてください。

2. コメントの完全な一覧を作成する

人間とエージェントの両方から寄せられた、対応が必要な可能性のあるすべてのフィードバックを収集します。実行のたびにこの一覧を新たに作成し、繰り返し実行しても現在の PR と同期した状態を保ってください。

• 未解決のレビュー スレッド — 前回の実行後に追加されたものも含めます
• 現在のコードですでに懸念が解消されている可能性がある未解決のスレッド（解決します）、または古くなったスレッド（参照先のコードが変更、移動、削除されています）
• 誤って解決された可能性がある、解決済みのレビュー スレッド
• 会話にあるトップレベルの PR コメント
• 対応可能な要望を含むレビューの要約

評価を始める前に、一覧が完全であることを確認してください。すべてのリスト取得呼び出しで --paginate が使われていること、すべてのカーソルで hasNextPage が false になるまで取得していること、スレッド数とコメント数が PR ページの件数と一致することを確認します。一致しない場合は、不完全な一覧をトリアージせず、再度取得してください。

各項目について、次の情報を記録します。

• コメント／スレッドの識別子
• 投稿者と、その投稿者が人間か AI エージェントか
• タイムスタンプ
• 該当する場合はコード内の場所
• コメントの原文
• 返信／スレッドの文脈
• 現在の解決状態

明らかなボットのノイズ（細かな指摘のスパム、重複したレビュー要約、カバレッジに関する雑談など）は、ユーザーから含めるよう求められていない限り無視します。AI エージェントによる実質的な指摘はノイズではありません。一覧に残して確認してください。ノイズか実質的な指摘か判断できない場合は、一覧に残してください。

3. 各コメントを慎重に評価する

すべてのコメントを、次のいずれかに分類します。

1. コードで対応する

   • フィードバックは妥当で、まだ反映されていません。
   • コード、設定、ドキュメントの変更が引き続き必要です。

2. すでに対応済み、解決しても安全

   • 要求された変更は現在のブランチにすでに反映されています。
   • または、より適切な実装によってそのスレッドの指摘が置き換えられ、当初の懸念が該当しなくなっています。

3. 議論／ユーザーの判断が必要

   • コメントが曖昧です。
   • 要求が他の要件と矛盾しています。
   • 提案された修正にリスクがある、アーキテクチャに関わる、または主観的です。

4. 対応不要だが、自動では解決できない

   • GitHub ではトップレベルのコメントを解決できないため、通常はこれに該当します。
   • 必要に応じて、追加の変更が不要な理由を説明する返信案を作成します。

5. 根拠がない

   • コードがその主張に反しています。前提が誤っている、引用されたシンボルが存在しない、呼び出し元がすでに不変条件を保証している、またはそのケースが起こり得ない、などです。
   • 実際のコードの動作を説明してから、スレッドを解決します。却下された AI 作成の指摘はここに分類します。

4. 現在のコードと照合する

指摘に対応済みと判断する前に、次のことを行います。

• 該当するファイルを読みます。
• 要求された動作が実際に実装されているかを確認します。
• 後続のコミットや返信ですでに懸念が解消されていないかを確認します。
• 推測よりもコードベースの証拠を優先します。

「問題ないと思う」だけを、スレッドを解決する十分な理由として扱わないでください。

AI が作成した指摘には、より厳しい基準を適用する

AI レビューエージェントが確認するのは差分であり、プロジェクト全体ではありません。呼び出し元がどの不変条件を保証しているか、どの分岐に到達しないか、リポジトリがどのパターンを意図的に選んだか、どのテストがすでにケースをカバーしているか、依存関係のどのバージョンが固定されているかは把握できません。そのため、指摘は流暢で具体的でありながら、正否を判断するうえでまさに重要なコンテキストを欠いています。

エージェントからの指摘については、コードを書く前に必ず次のすべてを行います。

1. 指摘を、真偽を確認できる形で言い換えます。 「path が空だと parseConfig がパニックを起こす」は確認できます。「エラー処理を改善できる」は確認できません。具体的なケースを求めるか、指摘を却下します。
2. コード内で指摘の根拠を探します。 関数と、その呼び出し元、テストを読みます。該当行に至る経路を確認するまでは、行に関する指摘には意味がありません。
3. 指摘の前提を検証します。 エージェントは、nil、型、競合状態、設定キー、API など、リポジトリに存在しないものを前提にすることがよくあります。指摘で挙げられたシンボルを grep で検索します。
4. 証拠に基づいて判断します。 確認できた場合は対応します。反証された場合は、その指摘を却下し、矛盾するコードを示します。どちらとも言えない場合は、未確認として却下するかユーザーに確認し、コードは変更しません。

同じ内容の指摘が二つあっても、証拠が二つあることにはなりません。エージェント同士で推測を繰り返しているだけかもしれません。必須チェックを妨げる指摘も、それだけで正しいとは限りません。ゲートが失敗している事実は、コードについての事実ではなく、ゲートについての事実です。

エージェントの指摘を理由に差分の範囲を広げてはいけません。リファクタリング、新しい抽象化、追加の防御的チェック、新しい依存関係、またはより広範な名称変更を行うには、事前に人間からの依頼が必要です。

変更提案ブロックは提案であり、パッチではありません。周辺の行を読み、自分で修正を書いてください。内容を確認せずに提案ブロックをコミットしてはいけません。

5. 作業に入る前にトリアージの概要を提示する

判断ごとに分類した簡潔な概要を作成します。

• 対応
• 解決
• 根拠なし — 各指摘と矛盾するコードを示します
• ユーザーへの確認が必要
• 追加対応不要のトップレベルコメント

各項目には次の内容を含めます。

• 作成者
• 短い引用または要約
• 判断
• その理由を一文で説明

ユーザーから作業を依頼されている場合は、判断が曖昧またはリスクを伴う場合を除き、概要の提示後に作業を進めます。

判断に基づく対応

コメントに対応すべき場合

• 根本的な懸念を解消する、最小限かつ正確な変更を行います。
• 修正の範囲はフィードバックに限定します。
• コードを変更した後、新しいコードに照らしてスレッドを再確認し、そのうえで修正内容を簡潔に説明する返信を付けて解決します（以下を参照）。

レビュースレッドを解決すべき場合

トップレベルの PR コメントではなく、レビュースレッドのみを解決してください。

解決する理由にかかわらず、スレッドを解決する前に、必ず短い説明の返信を投稿してください。1〜2 文で十分です。返信では、何が起きたのかをレビュアーに伝えます。

• コードで修正済み — 変更内容を明記し、役立つ場合はコミットまたは file:line を記載します
• 指摘が誤り — 懸念が実際の実装に当てはまらない理由を説明します。エージェントの主張の場合は、それに反する file:line を記載します
• 古くなった — 該当するコードが削除または置き換えられたことを説明します
• 議論で解決済み — 解決につながった返信または決定を示します

各返信本文の末尾には、帰属表示の行 🤖 Generated with Claude Code を単独の行として記載してください。

必須の手順（この順序で両方実施します）。

1. スレッドに説明の返信を投稿します。
2. GitHub GraphQL を使用してスレッドを解決します。

記述例：

# 1. Reply with a short explanation (end the body with the attribution line).
#    Request `url` back and keep it — it is the direct link for the posted-comments list.
gh api graphql -f query='mutation($threadId:ID!,$body:String!) { addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$threadId, body:$body}) { comment { id url } } }' -F threadId='THREAD_ID' -F body='Fixed in <commit> — extracted the helper as requested.

🤖 Generated with Claude Code'

# 2. Resolve the thread
gh api graphql -f query='mutation($threadId:ID!) { resolveReviewThread(input:{threadId:$threadId}) { thread { isResolved } } }' -F threadId='THREAD_ID'

スレッドがすでに解決済みの場合、誤って解決されていると判明したときを除き、変更しないでください。誤って解決されている場合は、履歴を黙って変更するのではなく、ユーザーに伝えてください。

項目がトップレベルの PR コメントの場合

トップレベルの PR コメントは解決できません。代わりに、次の対応を行います。

• コード変更が必要かどうかを判断します
• 必要に応じて短い返信を下書きまたは投稿します
• その項目を、要約では対応済みまたは対応不要として報告します

gh pr comment は作成したコメントの URL を出力します。投稿済みコメントのリストに記載するため、その URL を保持してください。

gh pr comment PR_NUMBER --body 'Confirmed — the rate limit is enforced by the gateway, so no change here.

🤖 Generated with Claude Code'

GitHub で解決できない項目を解決したと主張しないでください。

出力形式

次のような列を含む簡潔なチェックリストまたは表を使用してください。

• kind（thread、top-level、review-summary）
• author
• author kind（human、agent）
• location
• decision
• reason
• action

投稿したコメント

実行の最後に、その実行中に投稿したコメントのリストを、投稿順に記載してください。それぞれを1つの箇条書きとし、コメント内容を1〜2文で要約した後、直接リンクを記載します。

## Comments posted

- Extracted the retry helper into `client.go:88` as requested, then resolved the thread — [reply](https://github.com/owner/repo/pull/123#discussion_r456789)
- Explained that the nil check is unreachable because the caller validates the input — [reply](https://github.com/owner/repo/pull/123#discussion_r456790)
- Confirmed the rate limit is enforced by the gateway, so no change is needed — [comment](https://github.com/owner/repo/pull/123#issuecomment-99887766)

投稿時に API から返された URL を使用してください。コメントを投稿していない場合は、リストを省略せず、その旨を記載してください。

判断基準

次のいずれかが当てはまる場合に限り、スレッドを安全に解決できます。

• 要求された変更がコードに反映済みである
• 実際の実装に照らして、懸念が誤りである
• その後の議論で、問題が明示的に解決された
• 該当するコードが削除または置き換えられたため、スレッドが古くなっている

いずれも明確に当てはまらない場合は、解決しないでください。

コード変更には、もう一段階の基準があります。AI が作成した指摘を受けてコードを変更するのは、自分でコード内の不具合を確認した場合に限ります。提案された差分、自信に満ちた口調、レビューのステータスが赤であることは、その根拠にはなりません。主張が正しいかどうか確認できない場合は、却下するかユーザーに委ねてください。念のためという理由だけで実装してはいけません。

トラブルシューティング

• gh が認証されていない場合は、ユーザーに gh auth login の実行を案内してください。
• GitHub のバージョンや API の形式によって GraphQL フィールドが異なる場合は、カスタムの gh api graphql クエリに切り替えてください。
• 存在を把握しているコメントが一覧にない場合、取得結果が途中で切れています。--paginate を指定して再取得し、スレッドの comments など、入れ子になったコネクションについても、それぞれの hasNextPage を確認してください。
• 現在のブランチに PR がない場合は、処理を中止してユーザーに伝えてください。
• コメントが対応済みかどうかをコードだけから判断できない場合は、推測せずユーザーに確認してください。
• AI が作成した指摘に、見つからない関数、フラグ、フィールド、API が記載されている場合、検索が不十分なのではなく、その指摘がこのコードベースについて誤っているものとして扱ってください。返信ではその旨を伝え、コードに実際に存在するものを明記してください。
• エージェントがすでに却下した指摘を再投稿した場合は、再度議論するのではなく、以前の返信へのリンクを記載し、エージェントが同じ指摘を繰り返していることをユーザーに伝えてください。