resolve-human-reviews

PR に付いた人間のレビューコメントに対応する。コード変更が要るものを一通り直して push し、GitHub 上での返信・Resolve conversation はせず、対応表と返信案を会話で渡す。ユーザーが「人間レビューに対応して」「もらったコメントを直して」「/resolve-human-reviews」等を指示したときに使う。

SKILL.md

GitHub

人間のレビュアーから付いたコメントのうち、コード変更が要るものを一通り直して push します。GitHub 上には何も書き込まず、対応表と返信案を会話で渡すところまでが責務です。

投稿するかどうかはユーザーが決めます。渡した後、「そのまま代わりに投稿して」と言われることも、「対応したものだけハッシュを添えて返信して」と言われることもあるので、どちらの指示にもそのまま応じられる形で出す。

bot コメントを扱う /resolve-ai-reviews と対になりますが、GitHub へ書き込むかどうかが違います。

/resolve-ai-reviews このスキル
対象 AI レビュアーの bot( github-actions[bot] など。絞り方は /resolve-ai-reviews の手順2) 人間 (user.type == "User")
GitHub への返信 ハッシュか理由を返信 しない
Resolve conversation する しない
対応結果の報告先 GitHub + 会話 会話のみ(対応表 + 返信案)

返信するかどうか・何と返すかはレビュアーとの当事者間のやりとりであり、ユーザーが決めることです。こちらは修正と報告に徹し、返信の要否を尋ねもしません (responding_to_reviews.md)。

進め方

1. 対象 PR とコメントの特定

  • 引数に PR 番号があればそれを使う。無ければ gh pr view --json number で現在のブランチから特定する (該当 PR が無ければユーザーに確認)

  • 作成者を確かめる( gh pr view <PR> --json author -q '.author.login' )。ユーザー本人でなければ中断して報告する( no_operating_on_others_prs.md )。修正の push も他人の PR へ痕跡を残す

  • gh repo view --json nameWithOwner -q .nameWithOwner で OWNER/REPO を取得する

  • インラインコメントを取得し、人間かつトップレベルに絞る。

    gh api repos/OWNER/REPO/pulls/<PR>/comments --paginate \
      -q '.[] | select(.in_reply_to_id == null) | select(.user.type == "User") | "[\(.id)] \(.user.login) | \(.path):\(.line // .original_line)\n\(.body)\n---"'
    
  • レビュー提出の本文は、長さを見てから読む。空の提出はインラインを束ねる入れ物で、読む文章が無い。

    gh api repos/OWNER/REPO/pulls/<PR>/reviews --paginate \
      -q '.[] | select(.user.type == "User") | "[\(.id)] \(.user.login) body=\(.body|length)字\n\(.body)\n---"'
    

    body=0字 の提出を「サマリがあった」ことにしない。 指摘の中身が正しく見えても、出どころの無いものは指摘として数えない

    本文がインラインの指摘への対応を求めているだけなら、本文は1件の指摘として数えない。 対応表の行も返信案もインラインの分だけにする。インラインへ返信すれば、本文の求めにも答えたことになる。本文にインラインに無い指摘や質問があるときだけ、1件として扱う。数えない本文も、謝意の 👍 の対象からは外れない(手順7)

  • 接頭辞 ([must] / [imo] / [nits] / [ask] / [fyi]) を優先度の一次判断に使う

  • 複数 PR にコメントが付いている場合は PR ごとに区切って進める。ブランチを跨ぐので、混ぜると対応表が崩れる

2. 意図の咀嚼と現状コードの照合

コメント1件ごとに、何を問題視しているかと現状のコードがどうなっているかを突き合わせる。指摘が既に解消済み・前提が誤っている (誤検知) ケースがあるので、指摘を鵜呑みにせず実物を読む。

指摘が事実を主張している場合 (「BE は "" を返しうる」「この関数は他でも使われている」等) は、一次情報で裏を取る (verify_before_asserting.md)。他リポジトリのコードがローカルにあるなら読む。

3. トリアージ

すべてのコメントを次のいずれかに割り当てる。放置しない。

「対応」はコミットを伴うコード変更を指す。 記述の訂正や質問への回答は対応ではなく、報告のときも分けて書く。

判定 基準
対応 [must] は原則すべて。[imo] / [nits] は「直した結果が本当に良くなるか」で判断する
非対応 既に満たされている / 前提が誤っている / 直すとかえって劣化する。技術の採否は実装側が決めるので、仕様や優先度の判断が要らないものはここへ入れる。理由を必ず書き出す
コード変更を伴わない 指摘が記述の誤り(PR 説明・doc)や質問のとき。[must] でもここに入る。PR 説明を直すことが指摘への応答そのものになる
ユーザー判断待ち 指摘がユーザーの領分(方針・粒度・優先度・公開範囲)に当たる。セッション内の合意・PR 本文の明記事項と抵触して、どちらが正か即断できない場合も含む

保留の基準は「誰が決めることか」。 迷ったかどうかではない( decide_or_ask.md の判断軸と同じ)。

保留する 自分で決める
ユーザーの領分(方針・粒度・優先度・公開範囲) 手段の選択(実装の書き方・道具立て・技術の採否)

技術の採否は、迷っても自分で決めて非対応へ振り分ける。 ユーザー判断待ちへ入れると、決められることが決まらないまま止まる。 非対応にも返信案は要る(手順9が全件に用意させる)。投稿するかはユーザーが決めるので、ここで絞らない。

[must] を見てコード変更だと決めつけない。 レビュアーが「コードの修正は不要」と書いていることがある。何を直せと言われているかを読む。

セッション文脈と照合する。 ユーザーが「〇〇は残して」と言った箇所、PR 本文で「意図的に採用しなかった」と書いた項目、memory に記録した好みに抵触する指摘は、優先度に関わらず自動で従わない。文脈で方針が確定済みなら独断で非対応にしてよく、抵触したうえで迷うならユーザーに尋ねる (AskUserQuestion で「対応 / 非対応 / 別方針」を選ばせる)。抵触していない技術の採否は、迷っても上記のとおり自分で決めて非対応へ振り分ける。

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

  • 対応すると決めたものをコードに反映する。1つの指摘が複数箇所に波及する場合 (文言変更、リネーム等) は参照元・テスト・モックまで漏れなく追随する
    • 文言を変えたら、その文言を期待するテストを grep で洗う。ただしテスト内のローカル定数は追随不要なので、実装を参照しているかを確かめてから直す
  • 修正後、影響範囲のテスト・lint・format を通す。テスト一式は run_in_background: true で流し、待つ間に残りの修正を進める

5. コミット & プッシュ

このスキルの起動を、このレビュー対応分のコミット & プッシュへの明示的な承認とみなす (decide_or_ask.md の言う「一意に読める指示」に該当)。確認質問は挟まない。

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

  • コメントとコミットが対応付く粒度で分ける。1コメント1コミットが基本だが、同一ファイルの同趣旨の指摘 (定数の位置と doc の表記など) はまとめてよい。逆に、性質の違う指摘 (文言変更とテスト追加) を1コミットに混ぜない

6. PR 説明と補足コメントの追随

レビュー対応で差分が動いたら、それを説明している記述も同時に直す( keep_records_current.md )。指摘が「説明の誤り」だった場合は、コードを変えなくても本文の修正が対応そのものになる。

見るもの 直す観点
実装内容 追加した判断・変えた挙動が載っているか
テスト内容 追加したテストの対象と件数
影響範囲 既存の挙動に触れたなら必ず書く。レビュー対応は既存に手を入れやすい
補足コメント 契約・データモデルを載せているなら、変えた箇所を反映

/update-pr-description を呼ぶ。 本文が既に実態と合っているなら呼ばない。

7. リアクションは、返信を代行したときだけ付ける

返信していない段階では 👍 を付けません( responding_to_reviews.md )。リアクションもレビュアーへ向けた発信なので、返信と同じ許可が要る。人間レビューでは返信が明示指示制なので、指示が出るまではどちらも行わない。

ユーザーが返信を代行するよう指示した場合は、その返信を投稿したコメントにだけ付ける。

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

PR コメント欄のコメントなら、経路は issues/comments/<comment_id>/reactions に変わる。返信の直後に、返信を投稿したコメントへまとめて付ける。1件ごとに付けると通知が細切れになる。

あわせて、本文のあるレビュー提出にも 👍 を付ける。 インラインの1件ずつは「その指摘に応えた」の印だが、レビュー提出は見てもらったこと自体への謝意にあたる。指摘の可否とは別なので、非対応の指摘しか無かった回でも付ける。

本文が空のレビュー提出には付けない。 インラインコメントを束ねるだけの入れ物で、読む文章が無い。

REST に該当のエンドポイントが無いので GraphQL を使う( /reactions は issue コメントとインラインコメントにしかない)。

gh api graphql -f query='query{repository(owner:"OWNER",name:"REPO"){pullRequest(number:NNN){reviews(first:50){nodes{id state author{login} body}}}}}' \
  -q '.data.repository.pullRequest.reviews.nodes[] | select(.author.login=="LOGIN") | select(.body != "") | .id'

gh api graphql -f query='mutation($id: ID!) { addReaction(input: {subjectId: $id, content: THUMBS_UP}) { reaction { content } } }' -F id="<review node id>"

8. 対応表の報告

GitHub には何も書かず、会話で報告する。 これがこのスキルの成果物。

  • 1つの表にまとめ、GitHub の Conversation と同じ順で並べる( report_formatting.md )。Step 1の取得順がそのまま Conversation の順なので、優先度や対応可否で並べ替えない。ユーザーは PR を上から見ながら返信する
  • 列は「コメント ID / 種別 / 位置 / 指摘の要約 / 結果」。結果にはコミットハッシュか非対応の理由を入れ、裏取りの根拠が長ければ表の下に回す
  • ID 列には Step 1で取得した識別子だけを書く。「レビュー本文」のような代替語を置かない。ID を書けない行は、その指摘が実在しない
  • ハッシュはレンジではなく個別に列挙する
  • PR が複数なら PR ごとに節を分ける

9. 返信案の提示

対応表と並ぶ、このスキルのもう1つの成果物。 ユーザーがそのまま投稿できる形で渡す。

返信が要るものすべてに用意する。 投稿する / しないの取捨はユーザーが決めるので、こちらで絞らない。ただし、インラインへの対応を求めているだけのレビュー本文は返信が要るものに入らない(手順1)。インラインへの返信と同じことを2回言うことになる。

コメント 案の中身
コードを直した メンション + ハッシュ。下記の書式そのまま
[ask] の質問 回答の案。裏を取った根拠(ファイル・関数名)を添える
非対応にした 理由の案。なぜ直さないかを1〜2行
コード変更を伴わない(PR 説明・doc の誤り) 何をどう直したかの案

コードブロックに入れて1件ずつ出す。 コメント ID を見出しに置き、対応表の行と突き合わせられるようにする。投稿はしない。

案にも謝罪の文言を入れない(下記「謝罪の文言は書かない」)。ここで入ると、そのまま投稿される。

理由の案と回答の案では、GitHub の表現手段を使ってよい(手段の選び方は /format-post )。散文で書くと長くなるものを表や <details> へ畳む。IMPORTANT / WARNING は本文に1〜2個まで(末尾の生成者表示 Note は数えない)。返信は本文より短いので、2つ要る場面は稀。

ハッシュ返信は対象外。 1行目にハッシュ、末尾に Note という形が決まっており、畳むほどの中身が無い。

ユーザーから返信を指示された場合

既定は「返信しない」で、ユーザーが明示指示したときだけ代行する( responding_to_reviews.md )。指示が出たら次の書式で返す。

マージまで指示されたら、それは返信を含む指示。 「対応してマージしておいて」と言われた場合、返信してからマージする。マージすると PR が閉じ、指摘したレビュアーには対応内容が届かないまま終わるため。

書式は下の表を読んでから書く。 メンションと 🙇🏽‍♂️ は毎回付けるもので、記憶で書くと落ちる。実際に両方欠けた返信を投稿し、レビュアーに気づいてもらえない形になった。

@<レビュアーの GitHub ID>
<ハッシュ1> <ハッシュ2> で<動詞>ました🙇🏽‍♂️

<生成者表示の Note ブロック>

生成者表示の文言は github_note_generated_by_claude.md が持つ。 ここには写さない

決めごと 内容
宛先 レビュアーの GitHub ID をメンション。1行目に置き、本文は次の行から
ハッシュ 空白区切りで列挙。レンジにしない( report_formatting.md )
動詞 差分の性質に当てる(下記)
🙇🏽‍♂️ ハッシュ返信の行末に、空白を空けずに付ける(下記)
生成者表示の Note 付ける。末尾に空行を挟んでブロックを置く( github_note_generated_by_claude.md )

🙇🏽‍♂️ は感謝であって、謝罪ではない。 「いいご指摘をありがとう」の意味で置くもので、相手が人間だから要る。bot への返信( /resolve-ai-reviews )には付けない。

付くのはハッシュ返信だけ。 指摘を受けて直したことを報告する形に添えるもので、非対応の返信(直していない)と [ask] への回答(聞かれて答えているだけ)は、その形に当たらない。

謝罪の文言は書かない

レビュアーとユーザーは対等です。 上下があるなら謝罪に意味がありますが、対等なら事実と判断だけのほうが速く伝わります。

書かない 書いてよい
「申し訳ありませんでした」 「ご指摘ありがとうございます」
「完全に私の間違いでした」 事実の確認(「ご指摘のとおり〜でした」)

🙇🏽‍♂️ とは別の話。 あちらは感謝で、こちらは謝罪。種類が違うので、片方を置いて片方を落とすことに矛盾はありません。位置も違い、🙇🏽‍♂️ は行末の1文字ですが、散文の謝罪は冒頭に来て主題を奪います。

誤りを認めること自体は要ります。 認めるのと詫びるのは別で、「ご指摘のとおりでした」で足ります。

動詞は1件ずつ当てる

全件を「対応しました」で埋めない。 レビュアーはハッシュを開く前に何をされたのかを動詞から読みます。同じ語が並ぶと、その手がかりが消えて全件を開くことになる。

差分の性質 動詞
誤り・不具合を直した 修正しました
記述が実態とズレていた(doc・コメント・PR 説明) 実態に合わせました
無かったものを足した(関数・テスト・ケース) 追加しました
別の形へ置き換えた(実装の差し替え・共通化) 置き換えました / 〜へ寄せました
不要になったものを消した 削除しました
書き方・命名を他と揃えた 揃えました
上流・他ブランチの変更を取り込んだ 取り込みました

「対応しました」は最後の手段。 1件の中で性質が混ざり、どれか1つに寄せると嘘になるときだけ使う。

指摘と違う形で直したなら、動詞だけで済ませない。 ハッシュの後に理由を1〜2行足す。黙って別の形で直すと、レビュアーは指摘どおりに直ったと読む。

指示の型で投稿範囲が変わる。 どこまで代行してよいかはユーザーの言葉で決まるので、広く解釈しない。

指示 投稿する範囲
「対応したものだけ返信して」 コミットを伴うものだけ。ハッシュを添える
「返信案をそのまま投稿して」 手順9で渡した案すべて
個別に「このコメントに〇〇と返して」 そのコメントだけ

既定は狭いほう。 範囲が読み取れないときは、[ask] と非対応の分を投稿せずに残し、その旨を報告する。語調を選んで答える必要がある返信を代行すると、ニュアンスがずれる。

出力の目安

  • 対応表 → 返信案の順に置く。表の外に長い解説を積まない
  • 返信案はコードブロックで1件ずつ。そのままコピーできる状態にする
  • 非対応の理由は1〜2行。裏取りの根拠 (ファイル名・関数名) があれば添える
  • 全件対応で非対応ゼロなら、対応表だけで完結してよい

やってはいけないこと

  • GitHub 上でレビューコメントに返信すること。gh api .../replies、gh pr comment、gh pr review のいずれも使わない(ユーザーの明示指示がある場合は上記の書式に従う)
  • 報告の末尾で返信の話題を持ち出すこと。「明示指示をお待ちします」「返信の判断だけ残っています」はいずれもこれに当たる。修正の報告はハッシュと対応表だけで閉じる( responding_to_reviews.md )
  • 返信していないコメントへ 👍 を付けること。リアクションも発信なので、返信の許可が要る( responding_to_reviews.md )
  • Resolve conversation すること。スレッドを閉じるのは、コメントを付けたレビュアー自身の役目( responding_to_reviews.md )。返信を代行してよいと言われても含まれない
  • 返信の要否をユーザーに尋ねること。尋ねること自体が判断領域への侵入になる。必要ならユーザーが明示指示を出す
  • 取得していない指摘を対応表や返信案に載せること。中身が正しくても、出どころが無ければ指摘ではない。空の本文を読んだつもりになる事故は body=0字 を見れば防げる
  • bot コメントを混ぜて処理すること。bot は /resolve-ai-reviews の責務で、返信の扱いが正反対
  • レビュアーの文言・判断のナラティブをコード中のコメントに転記すること (code_comments.md)。必要な「なぜ」はコミットメッセージ本文に置く
  • 対応表を出さずにコミットハッシュだけ報告すること。どのコメントに応えたかが対応表の本体
  • 返信案を省くこと。投稿しない運用でも、案が無いとユーザーが1件ずつ書き起こすことになる
  • 投稿範囲を広く解釈すること。「対応したものだけ」と言われたら [ask] と非対応には投稿しない
  • 返信の動詞を全件「対応しました」で埋めること。差分の性質に当てる
  • 書式を記憶で書くこと。メンションと 🙇🏽‍♂️ は毎回付けるもので、書式表を開かずに書くと落ちる
  • 返信せずにマージすること。マージすると PR が閉じ、指摘したレビュアーには対応内容が届かない
  • 🙇🏽‍♂️ を非対応の返信や [ask] への回答にも付けること。直したことを報告する形に添えるものなので、直していない返信には当たらない
  • 返信に謝罪の散文を書くこと(「申し訳ありませんでした」「完全に私の間違いでした」)。レビュアーとは対等なので、事実と判断だけでよい(上記「謝罪の文言は書かない」)
  • 差分を動かしたのに PR 説明を古いまま残すこと。レビュアーは本文を読んでから差分を見る
  • [must] を根拠なく見送ること。非対応にするなら理由を書き出す
  • 修正なのにテスト・lint を通さずにコミットすること

例外

  • ユーザーが「このコメントには〇〇と返信して」と明示指示した場合は、そのコメントに限り返信を代行してよい。文面まで指定された場合だけ生成者表示の Note を外す。Claude が組み立てていないので、表示が事実に合わない (github_note_generated_by_claude.md)
  • ユーザーが特定のコメントについて「対応しないで」と指示した場合は、トリアージせずその指示に従う
  • 点検まで通したいときは、続けて /finalize-prs に PR の番号を渡して呼んでよい。ユーザーが不要と指示した場合はスキップする