PRレビューの傾向を分析して「あの人が見たら指摘する観点」をセルフレビューできるSkill を作った

背景: AIのレビューには足りない観点がある

これを作る前にも、AIによるコードレビューの仕組みは組織でも個人でも導入済みでした。それでもいざPRを出すと、レビュアーから指摘を受けることはあります。

• ある人は Figma との 1px のズレや arbitrary valueなど、UIデザイン観点の指摘
• ある人は状態管理のエッジケースやルート変更の互換性破壊を指摘
• ある人は N+1・eager load・既存 scope の再利用を重点的に見る
• ある人は認可（RBAC）の write 経路ガード漏れを体系的に洗う

これらはプロジェクトのコードベース固有の規約や注意すべき観点・背景とレビュアーの経験則に基づく個性であり、AIの汎用レビューでは補えない観点だということに気がつきました。

もちろん、あらかじめ.claude/rules などに規約は記していますし、個人的に指摘内容は書き留めたりと対策していますが、そうしていても、例えば自分以外の人のPRと指摘内容を全て確認しているわけでは無いので、穴はあり、終わりがないように思えます。

そこで、ClaudeCodeでPRの過去コメントを分析して、セルフレビューしてくれるskillを作ろうと思い至りました。

作ったもの

2つのSkillを作り、組み合わせて使っています。

1. 特定のレビュアーを指定し、PRの過去コメントを収集・分析して傾向プロファイルを生成
2. 現在の差分を、そのリポジトリのレビュアープロファイルの観点でレビューし、その対応要否まで判定

1で特定のレビュアーの指摘傾向をあらかじめ分析しておいて、観点をまとめたファイルを作成しておきます。
2でそれを活用して、PRを出す前にスラッシュコマンド + PRのURLを渡してセルフレビューさせます。

/self-review https://github.com/<org>/<repo>/pull/1234

/self-reviewを実行すると、レビュー結果と共に、その指摘箇所を精査して本当に対応すべきなのか判定した結果付きで回答が出力される仕掛けになっています。

### [must] エラー時に送信ボタンが永久無効化される — index.tsx:53
指摘: 取得失敗時にフラグが立ちっぱなしで送信不可になる（状態管理のエッジケース）
検証: hook は error を立てるが呼び出し側が未消費（rg で参照0件を確認）
判定: ✅ 要対応 — 実コードで成立。ユーザーに通知もなく詰む
推奨対応: 呼び出し側で error を受けて通知 or 再選択導線を出す

作り方

ここからはどうやって作ったのかを解説します。
この文章をまるごとClaudeCodeにコピペして渡すなどすれば、同じものがすぐ作れると思います。

設計判断

全員の合算より特定数名に絞った

最初はチーム全体のレビューを合算して傾向を出す案を考えました。
しかし試した結果、個人に絞るほうが精度が上がること、また当たり前ですがそのプロジェクトで関わった時間が長い人の方が、プロジェクト独自の背景と将来の方針を含んだ良質なコンテキストになると分かりました。

• レビュー観点は人によって大きく違う
• 全員を平均すると当たり障りのない一般論に寄ってしまう
• 特定の人に絞ることで、その人の経験則がくっきり出てセルフレビューで再現しやすい

そこで傾向の分析対象者を数人に固定しました。
人数を絞った分、学習対象のPR数はむしろ増やせるので、同じか少ないコストで濃いプロファイルが作れます。

レビュアーはリポジトリに応じて選定

私の場合は複数リポジトリで使いたかったり、フロントエンドのレビュアーとバックエンドのレビュアーが別人という事情があったので、プロファイルフォルダを分けて、その中に各人の分析結果の入ったプロファイル(markdown)を入れると言う構成にしました。

profiles/
  <frontend>/
    reviewer-a.md
    reviewer-b.md
    reviewer-c.md
  <backend>/
    reviewer-x.md
    reviewer-y.md
    reviewer-z.md

self-reviewのskillは、渡されたPRのURLから対象リポジトリから誰のプロファイルを使用したらいいのかを自動判定してレビューするように作ってあります。
これで別リポジトリの観点は混入しませんし、自分で選ぶ手間も省けます。
もしも新しいリポジトリへの対応が発生したら、新しいスキルを増やすのではなく、リポジトリとレビュアーの情報だけを追加するだけで済むようにしました。

実装：レビューコメントの収集・分析

2系統のコメントを集める

GitHub のレビューコメントは gh CLI で機械的に取れます。集めるのは2系統です。

• inline コメント（コードの特定行に付くもの）: repos/{owner}/{repo}/pulls/comments
• 総評（レビュー全体のサマリ本文）: pulls/{n}/reviews の body

gh api "repos/$REPO/pulls/comments?sort=created&direction=desc&per_page=100" --paginate

自分の PR への返信がノイズなので除外

pulls/comments はその人が書いた全コメントを返します。ここには自分が作者のPRへの返信（「対応しました」「ありがとうございます」など）が大量に混ざっています。これは指摘傾向ではないので、プロファイルを汚します。

そこで「コメントが付いている PR の作者 ≠ コメント投稿者」でフィルタしました。
各レビュアーが author の PR 番号集合を先に取得し、その PR へのコメントを除外します。

# 各レビュアーが author の PR 番号を集める
gh search prs --repo "$REPO" --author "$u" --limit 1000 --json number \
  | jq -r '.[].number' | sort -u > authored.txt

# その人のコメントのうち、自分が author の PR への返信を除外
jq --slurpfile own <(jq -R 'tonumber' authored.txt | jq -s '.') '
  map(select((.pr as $p | $own[0] | index($p)) | not))
'

このフィルタで、ある人のコメントが「対応しました」系を含む状態から、純粋なレビュー指摘だけに絞り込めました。

実装：コメントからプロファイルを作る

集めたコメントをClaudeCodeに分析させ、レビュアーごとに以下の軸でプロファイル化しました。

1. よく指摘するカテゴリの頻度ランキング：実データから出てきたカテゴリを使う（デザイン忠実性、状態管理エッジケース、N+1、認可など）。
2. 指摘の深さの特徴：表層（命名・体裁）寄りか、再現条件まで踏み込む edge-case 型か。
3. 代表的な指摘の引用：カテゴリごとに実際の文面を引用。
4. セルフレビュー時のチェック観点：上記を自己点検できる命令形チェックリストに変換。

ラベルの集計は jq で機械的に出してから、代表例だけ本文を読むことでトークンを節約しました。

jq -r '.[].body | [scan("\\[[a-zA-Z!]{1,12}\\]")] | .[]' comments.json \
  | sort | uniq -c | sort -rn

最終的なプロファイルは、各レビュアーにつきラベルの使い方,よく指摘するカテゴリ（頻度順・引用つき）,セルフレビュー用チェックリストを持つ Markdown にまとめました。

実装：レビュー結果に対し、対応要否の判定を足す

作成当初の self-review はレビュー指摘候補を出力するだけでした。
しかし、使ってみると指摘には必ず誤検知が混ざります。
1つ1つ確認していましたが、段々と手間に感じられたので、処理を以下の3段に変更しました。

1. レビュー指摘作成
2. レビュー結果を検証・判定
3. 出力

指摘は鵜呑みにせず実コードを調べさせるようにしています。

• 指摘箇所の前後・呼び出し元を読んで、本当にその問題が成立するか確認する
• rg で既存パターンを裏取りする（定義済みトークンの有無、既存コードも同じ書き方か、その定数がすでにあるか）
• 既存仕様・スコープ外・別 PR 分割の妥当性を、差分最小化原則に照らして判断する

その上で5段階の verdict に分類させます。

verdict	意味
✅ 要対応	実コードで成立を確認したバグ・規約違反
🔧 対応推奨	直した方がよいが必須でない
⏭️ 別PR/別チケット	既存コード起因・スコープ外
❌ 対応不要	誤検知・既存仕様・対処済み・既存も同パターンで許容（理由明記）
❓ 要判断	コードだけでは決められず仕様確認が要る

確証が持てないものは ✅ にせず ❓ に倒す（断定しない）というルールも追加してあります。
ここを抑えないと「要対応」が乱発されるような印象を受けたからです。

トレードオフとして、検証で実コードを読みに行く分、処理時間とトークンは増えます。

今回の学び

実際にPRで回すと、汎用レビューでは出てこない観点を、レビュー依頼を出す前に潰せるようになりました。

• 平均より個別：レビュー傾向は個性が本質。合算すると個性が消える
• 指摘より判定：指摘を出すだけでなく対応すべきか実コードで裏取りして判定するところまでやると一気に実用的な精度の結果が手に入る
• 断定させない：ClaudeCodeが確証がなければ要判断に倒すルールを追加して後から確認しやすく工夫