resolve-human-reviews
PR に付いた人間のレビューコメントに対応する。コード変更が要るものを一通り直して push し、GitHub 上での返信・Resolve conversation はせず、対応表と返信案を会話で渡す。ユーザーが「人間レビューに対応して」「もらったコメントを直して」「/resolve-human-reviews」等を指示したときに使う。
SKILL.mdhome/.claude/skills/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 の番号を渡して呼んでよい。ユーザーが不要と指示した場合はスキップする