explain-review-comments
PR に付いたレビューコメントを取得し、1件ずつ何を問題視しているかを噛み砕いて、変更案・影響・推奨と、次に自分で気づくための手がかりまで渡す。対応可否を判断できる状態にすることと、同じ指摘を繰り返さない知識が残ることの両方が目的。修正・返信・Resolve はしない。ユーザーが「レビューコメントを解説して」「何を言われているのか教えて」「/explain-review-comments」等を指示
SKILL.mdhome/.claude/skills/explain-review-comments/SKILL.md
GitHubPR に付いたレビューコメントを取得し、1件ずつ意図を噛み砕いて、対応可否を判断できる状態にします。
そこで終わりません。 レビューは指摘された本人にしか届かない学習の機会なので、次に自分で気づけるようになるところまでが範囲です。同じ指摘を2度受けるなら、1度目の解説が足りていません。
説明だけを行い、コードは書き換えません。GitHub 上での返信・Resolve もしません。
土台は responding_to_reviews.md
1件あたりの型はルールが持っています。 意図の咀嚼 → 現状のコード → 変更案 → 影響 → 推奨 → 対応可否を尋ねる、までがあちらの規定で、テンプレートも載っています。本スキルはそれを再定義しません。
本スキルが足すのは、複数件を横断で扱う手順です。
| ルールが担う | 本スキルが担う |
|---|---|
| 1件をどう説明するか | どれを対象にするか(取得・絞り込み・並び順) |
| 変更案と推奨の出し方 | 件数が多いときの畳み方 |
| 尋ねて止まること | 人間 / bot の判別と、その後の渡し先 |
| — | 学びとして残すこと(下記5) |
対象
| 引数 | 挙動 |
|---|---|
| 省略 | 現在のブランチに紐づく PR の未解決コメント全件 |
| PR 番号 / URL | その PR の未解決コメント全件 |
+ --comment <コメント ID> |
その1件だけに絞る |
+ --filter <絞り込み> |
「人間のだけ」「 [must] だけ」等 |
ユーザーがコメント本文を直接貼った場合は、取得を飛ばしてその1件を扱う(ルールがそのまま適用される場面)。
進め方
1. コメントを取得する
3つの場所に散っています。 1つ見て終わりにしない。
gh api repos/OWNER/REPO/pulls/<PR>/comments # インライン
gh api repos/OWNER/REPO/pulls/<PR>/reviews # レビュー本文
gh api repos/OWNER/REPO/issues/<PR>/comments # PR コメント欄
- 並び順は
created_at昇順のまま維持する。 Conversation タブの並びと揃う(report_formatting.md) /ai-reviewのようなコマンドコメントは除外する。 本文を trim してコマンド1行だけかで判定する(github_writing.md)。投稿者名では分けられない- 解決済みかどうかを見る。 既に Resolve されたスレッドは既定で対象外。ユーザーが「全部見せて」と言えば含める
2. 人間 / bot を判別する
その後の渡し先が変わります。 user.type == "Bot" で機械的に分ける。
| 投稿者 | 対応するときの渡し先 |
|---|---|
| 人間 | /resolve-human-reviews(返信・Resolve はしない。対応表を会話で渡す) |
| bot | /resolve-ai-reviews (返信と Resolve まで含む) |
判別を文脈で行わない。 「AI っぽい書き方」で決めると、人間のコメントに返信する事故が起きます( responding_to_reviews.md )。
3. 1件ずつ、ルールの型で説明する
responding_to_reviews.md のテンプレートに従う。 指摘対象 / 問題視している点 / 提案 / 現状のコード / 変更案 / 影響 / 推奨。
まず pstack の in-your-own-words に従い、レビュアーが何を求めているかを自分の言葉で言い直す。そのうえで本スキルとして足すのは次の3点。
- 指摘が現状のコードに当てはまるか確かめる。 レビュー後に push していれば、既に直っていることがあります。
file:lineは動くので、必ず今のコードを読む(verify_before_asserting.md) - セッションの文脈と照合する。 これまでのユーザー指示・実装判断・PR 本文の明記事項と抵触する指摘は、正論に見えても採らない選択がある。抵触を見つけたら、その旨を添えて判断を仰ぐ
- 要点を
file:lineで指す(report_formatting.md)。抜粋が要るなら1件につき1個
噛み砕き方
レビュアーの文章をそのまま渡さない。 指摘は当人の語彙で書かれており、読み手が同じ前提を持っている保証はありません。
内部の呼び名を開く。 型名・関数名・SQL ファイル名をそのまま置かず、何をするものかを一言添える(「複数件をまとめて作る入口」「対象の行に鍵をかける」)。指摘の中の識別子も対象です。
「なぜ問題なのか」まで届かせる。 「〜すべき」だけでは判断できません。次のどれかを補う。
- 今のままだと何が起きるか。 落ちるのか、気づかないうちにおかしくなるのか
- 指摘どおりにすると何が変わるか。 副作用があるならそれも
- なぜレビュアーがそう見たか。 前提が違うだけのこともある
観点が3つ以上並ぶなら表に畳む(指摘 / 現状 / 判断)。散文で書くと、1件が長くなって全体が読まれません( concise_first_then_detail.md )。
指摘の前提になっているコードを深く読む必要があるなら、/explain-code へ渡す。 ここで実装の解説を始めると、対応可否の判断がその下に埋まります。
4. 件数が多いときは畳む
5件を超えたら、先に一覧を出す。 全件を同じ厚さで書くと、読み手はどれが重いか分からなくなる。
| 手順 | 中身 |
|---|---|
| まず一覧表 | コメント ID / 投稿者種別 / 位置 / 指摘の要約 / 推奨(対応 / 見送り / 要判断) |
| 次に個別の解説 | 「要判断」と重いものだけを厚く書く。自明なものは表の1行で足りる |
並び順は取得順のまま。 重要度で並べ替えない。ユーザーは PR を開いて上から突き合わせます( report_formatting.md )。
5. 学びとして残す
ここが本スキルの中心です。 対応可否だけなら、ルールのテンプレートで足りています。
指摘1件は、その場の1箇所を直すためだけのものではありません。 レビュアーは自分の中の基準でコードを見ており、その基準は言葉にされないまま指摘の形だけで届く。基準のほうを渡さないと、次も同じ所で指摘されます。
次の3つを、対応可否とは別に添える。
| 渡すもの | 何を書くか |
|---|---|
| 背後にある一般原則 | その指摘が何の具体例かを1行。「これは〜という判断の一例」 |
| 他にどこへ当てはまるか | 同じ観点で見ると引っかかる箇所が今の差分や近くにあるか。grep で数えて、あれば file:line で挙げる |
| 次に自分で気づく手がかり | 何を見れば同じ判断ができるか。「この形を書いたら〜を確かめる」 |
2つ目は実際に探す。 「他にもあるかもしれません」では手がかりになりません。探して0件ならそう言う。それ自体が「今回だけの話」という情報になります。
既に規約がある指摘は、その場所を指す。 リポジトリの規約ドキュメントやルールに書かれているなら、指摘の内容を書き写すのではなく参照を渡す。規約があるのに指摘を受けたということは、読まれていないか、書き方が悪いか、規約側が古い。どれかを見立てて1行添える。
全部の指摘に付けなくてよい。 typo の指摘に一般原則はありません。「なぜそう見たか」を言葉で説明できるものだけに絞る。付ける件数は1回につき1〜3件で足ります。
6. 尋ねて止まる
対応可否はユーザーの領分です。 推奨は出しますが、決めるのはユーザー。
- 選択肢が2つ以上あるなら
AskUserQuestionで出す(decide_or_ask.md) - 勝手に修正へ進まない。 GO が出てから
/resolve-human-reviewsか/resolve-ai-reviewsへ渡す - 返信要否を聞かない。 人間コメントへの返信はユーザーが判断する領分で、こちらから確認すること自体が侵入になる(
responding_to_reviews.md)
出力の目安
| 件数 | 目安 |
|---|---|
| 1件 | 10〜20行。ルールのテンプレート + 学びを3行。図は要らない |
| 2〜5件 | 1件ずつ、各10行程度 |
| 6件以上 | 一覧表 + 重いものだけ個別に。全件を厚く書かない |
やってはいけないこと
- コードを書き換えること。 説明だけを行う。修正は GO が出てから、対応スキルの担当
- GitHub 上で返信・Resolve すること。 本スキルの範囲外(
responding_to_reviews.md) - ルールのテンプレートを自前で再定義すること。 1件あたりの型は
responding_to_reviews.mdが持つ - 人間 / bot を文脈で判別すること。
user.typeで機械的に分ける - コマンドコメントを解説対象に含めること。 本文が trim してコマンド1行なら除外する
- 今のコードを読まずに書くこと。 レビュー後の push で既に直っていることがある
- 推奨を出さずに「どうしますか」と丸投げすること。 判断コストをユーザーへ全部渡すことになる
- 取得順を重要度で並べ替えること。 Conversation タブと突き合わせられなくなる
- 対応可否だけ渡して終えること。 それはルールのテンプレートで足りている。次に自分で気づける形まで持っていく
- 「他にもあるかもしれません」で済ませること。 実際に探して、件数か0件かを言う
- 全件に一般原則を付けること。 言葉で説明できるものだけ。typo の指摘に原則は無い
関連
responding_to_reviews.md(レビューコメントの意図を先に噛み砕く): 土台。 1件あたりの型・テンプレート・尋ねて止まることはあちらが定める。本スキルは取得と横断、そして学びとして残すことを足すresponding_to_reviews.md(人間コメントへ返信しない): 返信と Resolve をしない根拠/resolve-human-reviews//resolve-ai-reviews(対応の実行): GO が出た後の渡し先。 本スキルは判断材料を揃えるところまで/explain-code(実装の説明): 同じ explain 系。 指摘の前提になっているコードを深く読むならあちらへ渡すreport_formatting.md(報告に貼る識別子の書式): 一覧の並び順とfile:lineの書式はあちらが持つgithub_writing.md(コマンドコメントの別扱い): 取得時に除外する根拠