resolve-ai-reviews

PR に付いた GitHub Actions (AI) のレビューコメントに対応する。まずセッション文脈 (これまでのユーザー指示・実装判断・PR body 明記事項) と照合し、文脈と抵触する指摘は独断で対応せずユーザーに判断を尋ねる。文脈整合が取れた対応内容だけをコミット&プッシュし、各コメントにコミットハッシュ (または非対応理由) +末尾 Note アノテーションで返信したうえで、返信済み

SKILL.md

GitHub

現在のブランチに紐づく PR の GitHub Actions(AI)レビューコメントを取得し、セッション文脈 (これまでのユーザー指示・実装判断・PR body の明記事項) と照合したうえで、対応が必要なものを修正・コミット・プッシュし、各コメントにコミットハッシュのみで返信してください。セッション文脈と乖離する指摘は独断で対応せず、セッション文脈と bot 指摘を対比した形でユーザーに判断を尋ねます。

引数で PR 番号が渡された場合はそれを対象にし、無ければ現在のブランチから特定します。

進め方

1. 対象 PR とリポジトリの特定

  • 引数に PR 番号があればそれを使う。無ければ gh pr view --json number,headRefName で現在のブランチの PR を特定する(該当 PR が無ければユーザーに確認)。
  • 作成者を確かめる( gh pr view <PR> --json author -q '.author.login' )。ユーザー本人でなければ、そのまま中断して報告する( no_operating_on_others_prs.md )。返信・Resolve・push はいずれも他人の PR へ痕跡を残す。
  • gh repo view --json nameWithOwner -q .nameWithOwner で OWNER/REPO を取得し、以降の gh api に使う。

2. レビューコメントの取得と分類

  • gh api repos/OWNER/REPO/pulls/<PR>/comments でインラインレビューコメントを取得する。各要素の id / path / line (無ければ original_line )/ body / user.login / in_reply_to_id / commit_id を見る。
  • トップレベルの bot コメントのみを対象にする( in_reply_to_id が null かつ user.login が github-actions[bot] 等の AI レビュアー)。既に自分が返信済み(誰かの reply が既に付いている)ものは二重対応しない。
  • レビュー提出の本文は、長さを見てから読む( gh api repos/OWNER/REPO/pulls/<PR>/reviews --paginate -q '.[] | "[\(.id)] body=\(.body|length)字"' )。body=0字 の提出はインラインを束ねる入れ物で、読む文章が無い。出どころの無いものを指摘として数えない。
  • 各コメントの 接頭辞( [must] / [imo] / [nits] / [ask] / [fyi] )で優先度を判断する。
  • 対象 bot コメントの件数をここで確定し、後続 Step 3の並列化判定 (閾値3件) に使う。

2.5. セッション文脈スナップショットの組み立て (必須)

Step 3の照合対象となる「セッション文脈」をオーケストレーター側で 明示的に1つのスナップショットに束ねる。サブエージェントは会話コンテキストを引き継がず、PR body / memory / .claude/rules / 対象コードは自分で Read できても、会話内でユーザーが直近ターンに発言した内容は Read できない。スナップショットにしないと並列のサブエージェントには文脈が届かず、「文脈読み飛ばし」が構造的に発生する。

Step 3が並列モード / 直列モードのどちらであっても、このスナップショットを先に組み立てる (直列モードでも、照合対象を書き出しておくと Step 4以降の判断がぶれにくい)。

スナップショットに含めるもの

  • ユーザーの明示指示の要点: 会話内でユーザーが発した「〇〇 は残して」「これは触らないで」「〇〇 は使わないでほしい」等の方針指示 (発言そのものを引用可)
  • 前のターンの合意事項の要点: 実装者 (Claude) とユーザーの対話で確定した設計判断 (arbitrary values の粒度、semantic name 統一の対象範囲、例外扱いの合意 等)
  • PR body の「意図的に採用しなかった項目」該当節抜粋: gh pr view <PR> --json body -q .body で取得し、該当節を丸ごと抜粋する (サブエージェント側で再取得させず、抜粋済みのテキストを渡す)
  • 参照すべき memory ファイルのパスリスト: ~/.claude/projects/*/memory/feedback_*.md / project_*.md のうち、今回の PR / bot 指摘のドメインに関連しそうなもの (サブエージェント側で Read させる想定でパスだけ渡す。全件は渡さない)

格納形式: 後続サブエージェントにそのまま渡せるよう、プレーンテキストの Markdown ブロック (## ユーザーの明示指示 / ## 前のターンの合意 / ## PR body 抜粋 / ## 参照 memory パス の4セクション) で作る。

3. セッション文脈との照合 (必須・独断対応の抑止)

bot 指摘を機械的に取り込むと、これまでのやりとりでユーザーと合意済みの方針が上書きされる事故が起きる。Step 2で取得した bot 指摘を、Step 2.5のスナップショットと突き合わせて 「セッション文脈と抵触するか」 で仕分けする。

モード分岐 (閾値: 対象 bot コメント数3件)

  • コメント < 3件 (直列モード): オーケストレーターが直接、下記の観点で1件ずつ照合する。サブエージェントの起動のオーバーヘッドが照合コストを上回るため並列化しない。
  • コメント ≥ 3件 (並列モード): 対象 bot コメント1件ごとにサブエージェント (general-purpose) を 単一メッセージ内の複数 Agent ツール呼び出しで一斉にバックグラウンド起動 する。全サブエージェントの完了を待ってから、返ってきた構造化データをオーケストレーターが集約して Step 4へ進む。

いずれのモードでも、仕分けに使う観点は同じ。

  • ユーザーが明示的に採用/不採用を指示した方針
    例: 「〇〇 は残して」「これは触らないで」「〇〇 は使わないでほしい」
  • PR body の「意図的に採用しなかった項目」に明記済みの判断
    例: デザイナー合意で維持、副作用回避、スコープ外、pixel 明示意図
  • 前のターンまでに実装者 (Claude) とユーザーの対話で確定済みの設計判断
    例: arbitrary values の残し方の粒度、semantic name 統一の対象範囲、特定コンポーネントの例外扱い
  • memory (feedback_* / project_*) に記録済みのユーザーの好み・方針
    例: 「〇〇 は避ける」「〇〇 は基本〜」等の rule 化された好み

これらに抵触する指摘の扱い

  • 文脈で対応方針が明確に確定済み (ユーザーの明示指示・PR body 明記・memory 記録 のいずれかで「維持」か「別方針」が確定) → 独断で「非対応 + 理由返信」として処理してよい。わざわざユーザーに再確認しない (ユーザーは既に判断済みのため)。
  • 判断に迷う (どちらが正か即断できない・文脈解釈が割れる・新しい規約解釈が絡む・複数の合意事項が両立しない 等) → Step 5でユーザーの判断を仰ぐ (優先度 [must] / [imo] / [nits] を問わず)。

判断に迷うか否かの目安: 「対応 / 非対応いずれを選んでも後でユーザーから異議が出ないと確信できるか」。自己判断できるなら独断で進める (ユーザーへの確認をわざわざ挟まず、意思決定のノイズを増やさない)、確信できず迷うなら Step 5。

文脈読み飛ばしが起きる代表パターン (回避対象)

  • 「[must] だから対応必須」と思い込む (実はユーザーの明示指示で維持中)
  • 「[nits] だから一貫性向上のため対応する」(実はユーザーが意識的に別 utility を選んだ)
  • 「N/4で表現できるから standard utility 化」(実は pixel 明示が意図で PR body に明記済み)
  • 「規約に違反しているから直す」(実は例外扱いを合意済み)
  • 「他の場所と揃えるべき」(実は当該箇所だけ意図的に別方針)

並列モード時のサブエージェント起動プロンプト (対象コメント1件につきサブエージェント1体)

あなたは PR レビュー bot 指摘1件を **セッション文脈と照合** する担当です。修正・返信・resolve はいっさい行わず、照合結果の構造化データのみを返してください。

## 対象 bot コメント
- id: <comment_id>
- prefix: <[must]/[imo]/[nits]/[ask]/[fyi]>
- 位置: <path:line>
- 本文: <body>

## セッション文脈スナップショット (オーケストレーター作成、これが唯一の文脈)
<Step 2.5で組み立てた4セクションのプレーンテキストをそのまま貼る>

## 独立で参照してよいリソース
- PR body 全体: `gh pr view <PR> --json body -q .body`
- memory ファイル: 上記スナップショットの「参照 memory パス」セクションに列挙されたファイルを Read
- `.claude/rules/` 配下: 必要に応じ Read
- 対象コード: <path> を Read

## 出力 (この形式厳守)
- **判定**: 「対応」 / 「非対応」 / 「ユーザーの判断待ち」のいずれか1つ
- **理由**: 判定の根拠を1〜3行
- **該当した文脈項目**: スナップショット / PR body / memory / rule のどれと突き合わせて判定したかを1行で明記 (突き合わせが無ければ「なし」)

集約したオーケストレーターは、各サブエージェントの返り値をリスト化して Step 4のトリアージ入力にする。「ユーザーの判断待ち」の件は Step 5でユーザーの判断を仰ぐ。

4. トリアージ (対応要否の判断)

  • [must]: 原則すべて対応する。プロジェクト規約 (.claude/rules / docs/agents) に基づく指摘は特に確実に直す。ただし、指摘が既存コードで既に満たされている・前提が誤っている (誤検知) 等で 修正が発生しない と判断できる場合は、その旨を理由付きで返信して非対応とする ([must] を根拠なく見送るのは NG だが、正当な根拠で「修正不要」と判定するのは可)。
  • [imo] / [nits]: 「直した結果が本当に良くなるか」で判断する。改善になるなら対応、対応するとかえって劣化する (重複を生む・実害のない no-op を消すために可読性/DRY を犠牲にする 等) なら 対応せず、理由を返信 する。
  • bot は、直す所が無くても何かを指摘する。 指摘を探すよう頼まれているためだ。全部を追うと、起きない場合のための防御・余分な抽象化・それを確かめるテストが積み上がる。正しさと課題の要件に関わらない指摘は「対応しない(理由付き)」を選んでよい(Claude Code のベストプラクティス の「Add an adversarial review step」)。対応しない指摘のうち改善として残したいものは、ユーザーへの報告に書く( solve_with_minimal_change.md )
  • Step 3で「ユーザーの判断待ち」としたものは、優先度に関わらず Step 5へ回す。
  • 既にコミット済みの内容で解消済み のコメント (レビュー基準コミットが古い場合) は、修正不要。その解消済みコミットのハッシュ で返信する。
  • 判断が割れる/破壊的になりうるものは、勝手に大きく変えずユーザーに相談する。
  • すべての対象コメントについて「対応する / 対応しない (理由付き) / ユーザーの判断待ち」のどれかを選ぶ。放置は禁止。

5. ユーザーへの判断依頼 (Step 3で「文脈抵触かつ判断に迷う」が抽出された場合)

Step 3で「文脈抵触かつ判断に迷う」と判定した bot 指摘があれば、該当コメントの修正・返信・resolve をすべて保留したうえで、セッション文脈と bot 指摘を対比した形でユーザーに判断を尋ねる。質問は AskUserQuestion を優先 (箇条書きの選択肢で「対応 / 対応しない / 別方針で対応」を選ばせる)。判断依頼の粒度は「1コメント = 1質問」を基本に、同じ方針で扱えることが明らかな複数コメントはまとめて1質問にしてよい。

文脈で方針が確定済みのもの (Step 3の判定) はここに回さない。 独断で「非対応 + 理由返信」として処理する。返信本文で PR body の該当項目を引用すれば、レビュアーにも意図が伝わる。

対比記述の形式 (各コメント。3件以上あれば表に畳む)

  • bot 指摘 (id: NNNN, prefix): <path:line> — <指摘の主張の要約>
  • セッション文脈: <ユーザーの明示指示 / PR body 明記 / 前のターンの合意 / memory 記録 のうち該当するもの> — <引用か出典>
  • 判断依頼: 対応 / 対応しない (bot 指摘を却下) / 別方針 (別 utility や別範囲での対応)

ユーザーの判断が確定するまで、該当コメントには何もしない (修正・返信・resolve すべて保留)。確定後、決定に従って Step 6以降を実行する。

6. 修正の適用と品質チェック

  • 対応すると決めたコメント (Step 4で自律判定したもの + Step 5でユーザーが「対応」と決定したもの) の修正をコードに反映する。1つの指摘が複数箇所に波及する場合 (型のリネーム、mock 再生成など) は漏れなく追随する。
    • インターフェースや引数を変えたら task go:gen (モック再生成)、ファイル/型をリネームしたら参照元・テスト・registry・mock まで揃える。
  • 修正後、プロジェクトの品質チェックを通す (例: task go:format → task go:lint → task test:all)。失敗したら直してから進む。テスト一式は run_in_background: true で流し、待つ間に他コメントの対応を進める。

7. コミット & プッシュ

手順は /commit-push に従う(ステージングの粒度・メッセージの書式・フラグの扱い・push)。ここで書き直さない。 このスキル固有の事情は次の2点だけ。

  • 承認の範囲を狭める。/resolve-ai-reviews の起動が承認にあたるのは「文脈整合の対応内容 (自律判定 + ユーザーの確定)」だけで、Step 3の文脈照合と Step 5のユーザーの判断を経ていない対応は含めない。
  • push の後、git rev-parse HEAD で 返信に使うコミットハッシュ を取得する。Step 8の入力になるので、報告用の列挙とは別に控える。

8. 各コメントへの返信と Resolve conversation

  • 返信は GitHub の reply エンドポイントで行う。 gh api -X POST "repos/OWNER/REPO/pulls/<PR>/comments/<comment_id>/replies" -f body="<本文>"
  • すべての返信の末尾に GitHub Note アノテーションで生成者表示を添える (人間の言葉と誤認されないため。ハッシュ返信・理由返信を問わず統一)
    • 形式: 本文 (ハッシュか理由) の後に 空行を1行 挟み、生成者表示のブロックを置く
      <ハッシュか理由の本文>
      
      <生成者表示の Note ブロック>
      
    • 文言は github_note_generated_by_claude.md が持つので、ここには写さない
    • Note ブロックは末尾のブロッククォートとして本文から改行で切り離されるため、ハッシュ返信でも1行目からハッシュを機械抽出できる
  • 対応したコメント: 本文1行目に コミットハッシュ (例: 21cd46a34)、空行1行、末尾に Note ブロック。ハッシュ以外の説明文は付けない。
    • 今回のコミットで直したもの → 今回の push ハッシュ。
    • 過去コミットで解消済みだったもの → その解消コミットのハッシュ。
  • 対応しないと判断したコメント: ハッシュではなく、なぜ対応しないかの簡潔な理由、空行1行、末尾に Note ブロック。以下いずれの場合も同様に理由返信を行う (コミットハッシュは付けない)
    • [imo]/[nits] で「直すとかえって劣化するため見送る」
    • [must] を含めて「既存コードで既に満たされている/前提が誤っている (誤検知) ため修正不要」
    • Step 5でユーザーが「対応しない」と決定した文脈抵触指摘 (返信本文にはユーザーの判断の根拠となる文脈を簡潔に添える。例: 「PageMenu の当該 arbitrary は Figma pixel 値明示の意図で維持している」)
    • 指摘の対象が誤っている・スコープ外のため対応しない
  • すべての対象コメントに漏れなく返信する (対応したものはハッシュ + Note、対応しなかったものは理由 + Note)。
  • 返信にアノテーションは付けない。 [must] 等はレビュアーが指摘へ付けるもので、返信側が使うと役割が入れ替わって読める。
  • 自分から新規に補足コメントを投稿したら、必ず PR 本文からリンクを貼る。 書式は冒頭に [fyi] を単独行、末尾に Note ブロック (/create-pr と /update-pr-description の規約)。投稿して返る URL を gh pr edit <PR> --body-file <file> で本文へ差し込む。リンクが無いと本文だけ読んだ人がコメントの存在に気づけない。 本文の更新は全文置換なので、差し込む前に現在の本文から添付の参照( ![ user-attachments <video )を拾い、新しい本文にも残す( /update-pr-description の Step 1 と同じ)

理由返信では GitHub の表現手段を使ってよい (ハッシュ返信は1行目にハッシュのみなので対象外)。手段の選び方は /format-post が土台で、ここでは返信固有の事情だけを足す。

使う場面 形式
観点が3つ以上並ぶ (指摘 / 現状 / 判断、採用案と却下案の比較、影響範囲) 表。散文で並べるより対比が取れる。1列目に長い値 (ファイルパス等) を置かない。残りの列が潰れて縦書きになる
「どこを通るから対応不要か」のように経路や構造が根拠になる Mermaid (flowchart / sequenceDiagram)
根拠が1〜2行で足りる そのまま散文。1行の理由に表を付けるのは過剰
読み飛ばすと事故になる点 IMPORTANT / WARNING。本文に1〜2個まで(末尾の生成者表示 Note は数えない)。返信は本文より短いので、2つ要る場面は稀
長い実体を置きたい (ログ・SQL の全文) <details>。<summary> には中身が分かる名前を付ける

理由返信は簡潔さが最優先。表や図を足して長くするのではなく、散文で書くと長くなるものを畳むために使う。

書く順序は 結論 → 根拠。見出しは付けない (返信は数行なので、見出しを足すと本文より目次が目立つ)。「対応しません」を先に置き、その後に理由を続ける。レビュアーは可否を知りたくてスレッドを開くので、経緯から書き始めると最後まで読ませることになる。文が2つ以上あるなら接続詞で繋ぎ (「そのため」「ただし」)、断片を並べない。

他リポジトリの PR / issue に触れるときは owner/repo#123 (同一リポジトリなら #123)。owner を省略すると同一リポジトリの番号として解釈され、リンクが別物を指すか機能しなくなる。同じ返信の2回目以降も省略しない (github_writing.md)。

対応したコメントへリアクションを付ける

ハッシュを返信したコメントに +1 (👍)を付ける( responding_to_reviews.md )。返信とセットで、一覧から対応済みが分かる状態にする。返信を投稿していないコメントには付けない。

gh api -X POST repos/OWNER/REPO/pulls/comments/<comment_id>/reactions -f content='+1'

非対応と判断したコメント(誤検知・見送り)には付けない。理由返信だけを残す。

Resolve conversation

  • 返信を投稿したスレッドは、そのつど Resolve conversation で解決済みにする。返信だけだと未解決のまま残り、レビュアーが点検し直す手間が増える。

  • 対応方針: 今回のセッションでこちらが返信したスレッドはすべて Resolve する (対応済み・非対応理由のどちらでも)。

    • 例外: 返信で「ユーザーの判断を仰ぎたい」旨を残した場合は Resolve しない (人間のレビュアーの再確認を待つ)。
  • スレッド ID の取得は GraphQL (REST の comment id とは別の PRRT_... 形式)

    gh api graphql -f query='
    query {
      repository(owner: "OWNER", name: "REPO") {
        pullRequest(number: <PR>) {
          reviewThreads(first: 50) {
            nodes {
              id
              isResolved
              comments(first: 1) { nodes { databaseId } }
            }
          }
        }
      }
    }' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | {threadId: .id, resolved: .isResolved, commentId: .comments.nodes[0].databaseId}'
    

    commentId (databaseId) が REST の comments.id と対応するので、返信済みコメントに対応する threadId を紐付ける。

  • Resolve mutation

    gh api graphql -f query='mutation($id: ID!) { resolveReviewThread(input: {threadId: $id}) { thread { isResolved } } }' -F id="<threadId>"
    

    返り値の isResolved: true を確認する。

9. 完了報告

  • 1つの表にまとめ、GitHub の Conversation と同じ順で一覧化する (report_formatting.md)。Step 2の取得順がそのまま Conversation の順なので、優先度や対応可否で並べ替えない。列は id / 種別 / 位置 / 指摘の要約 / 結果 (返信したハッシュか非対応理由) / Resolve 状態。
  • Step 5でユーザーの判断を仰いだコメントは、別欄に切り出さず表の中で示す (元の bot 指摘とユーザーの決定が分かるように結果列へ書く)。切り出すと並びが崩れる。
  • push したコミットを個別に列挙する (レンジ表記は使わない)。
  • CI が動く場合は gh pr checks <PR> で結果を確認し、最新コミットに対する結果かも合わせて見る。
  • Resolve conversation を実施したスレッド数 (あるいは Resolve を意図的に見送ったスレッドとその理由) も併記する。

10. 仕上げの引き継ぎ

/finalize-prs はこのスキルから自動起動しない。 レビュー対応で入れた差分の点検は必要だが、呼び出し元が周回の途中か最後かを知っているため、判断はそちらに委ねる。

  • 単体で呼ばれた場合: 完了報告に「 /finalize-prs で点検すると差分の規約違反と PR 説明の鮮度を確認できる」と1行添える
  • /loop-ai-reviews から呼ばれた場合: 何もしない(あちらが最後に1回だけ実行する)

出力の目安

  • 対応 / 非対応のコメントを 表で1件1行(id / 種別 / 対応内容か非対応理由 / 返信したハッシュ / Resolve 状態)
  • ユーザーの判断を仰いだものは別欄で示す(元の bot 指摘 / ユーザーの決定 / 最終返信)
  • push したコミットはハッシュを直接列挙する。レンジ表記は使わない
  • 対象コメントが0件だったとき: 1〜2行で終わる

やってはいけないこと

  • セッション文脈 (ユーザーの明示指示、PR body 「意図的に採用しなかった項目」、前のターンの合意事項、memory の feedback_* / project_*) を無視して bot 指摘に機械的に従うこと。これらに抵触する指摘は Step 3で抽出して Step 5でユーザーの判断を仰ぐ。
  • Step 2.5のスナップショット組み立てを省いて Step 3を並列サブエージェントで走らせること。サブエージェントは会話コンテキストを引き継がないため、スナップショット無しの並列化は「文脈読み飛ばしの構造的量産」に直結する。直列モード (コメント < 3件) でも Step 2.5は実施する。
  • 対象コメントが3件未満なのに並列モードでサブエージェントを大量起動すること。起動のオーバーヘッドが照合のコストを上回り、終わるまでの時間が伸びる。直列モードのままオーケストレーターが直接照合する。
  • 「[must] だから対応必須」と決めつけて Step 3の照合をスキップすること。優先度は対応要否の一次判定材料であって、文脈抵触判定より上位ではない。
  • Step 5のユーザーの判断依頼を「大規模・破壊的な変更を伴うもの」だけに限定すること。小さな1行修正でも文脈抵触かつ判断に迷えば判断を仰ぐ。
  • 一方で、文脈で方針が明確に確定済みのもの (ユーザーの明示指示・PR body 明記・memory 記録) まで Step 5に回すこと。ユーザーは既に判断済みなので、独断で「非対応 + 理由返信」として処理してよい (毎回ユーザーに再確認するのは意思決定のノイズになる)。
  • Step 5でユーザーの判断待ち中のコメントに対して「暫定的に修正だけ入れておく」「暫定的に返信だけしておく」等の先行アクションを取ること (判断確定まで全保留)。
  • /resolve-ai-reviews 起動を「無条件の commit & push 承認」と誤解して確認質問を一切挟まないこと。承認スコープは「文脈整合が確定した対応」に限る。
  • [must] を根拠なく見送ること (Step 3の文脈抵触判定は「根拠」に該当するが、対応しない場合は Step 5でユーザーの判断を経ていること)。
  • 対応したコメント (ハッシュで返信するもの) に、ハッシュと末尾 Note ブロック以外の文言 (挨拶・追加説明等) を混ぜること。1行目にハッシュ / 空行 / 末尾 Note の3パーツ以外は付けない。
  • 末尾 Note ブロックを付け忘れて返信すること (ハッシュ返信・理由返信を問わず必須)。
  • 返信を投稿したスレッドを Resolve conversation せずに放置すること (ユーザーの再判断待ちを明示した返信は除く)。
  • 補足コメントを投稿したのに PR 本文からリンクを貼らないこと。読み手が存在に気づけない
  • コミットの手順をここで書き直すこと(ステージングの粒度・フラグ・push)。/commit-push が持つので、あちらを直したときに取り残される。
  • 修正なのに品質チェック (format/lint/test) を通さずにコミットすること。
  • レビュー基準コミットと現在の HEAD の差を無視して、既に直っている指摘を二重に直すこと。

例外

  • プロジェクト固有の規約 (コミット規約・テスト必須・品質チェックコマンド名など) が明示されている場合はそちらを優先する。
  • ユーザーが「この指摘は対応しないで」等の個別指示を出した場合はそれに従う (セッション内でユーザーが bot 指摘への対応方針を明示した場合、Step 3 / 5の議論なしにその指示を採用してよい)。
  • ユーザーが「bot 指摘全部そのまま対応して」等、セッション文脈より bot 指摘を優先する旨を明示した場合は、Step 3 / 5をスキップして自律対応してよい。