Recruit Data Blog

  • はてなブックマーク

目次

はじめに

データ推進室で SaaS プロダクトのデータ基盤の開発・運用を担当している電電です。

この記事では、開発現場で活用している AI エージェントの PR レビュー用の skill(Claude Code 向けに自作したもの)を紹介します。この skill は、レビューコメントを AI に下書きさせ、どれを投稿するかを人が選んでから GitHub に投稿します。AI レビューを試したものの、指摘が多すぎる、文面が固い、勝手に投稿されるのが怖い、と感じた人に読んでもらえると嬉しいです。

レビューで困っていたこと

LLM を使うようになって、コードを書くスピードは大きく上がりました。その一方で、PR は次々に作られるのに、レビューが追いつきにくくなりました。レビューも LLM に任せればよいと考えたくなりますが、自分が試した範囲では、全てを任せられるほど正確ではありません。それに、レビューを丸ごと任せてしまうと、自分たちのコードの設計を細部まで把握できなくなります。それでも、現実として目の前には PR が積み上がっていきます。

作ったもの:AI が下書きし、人が選ぶレビュー

そこで、レビューコメントの下書きを Claude Code に任せる skill を作りました。PR を指定して「レビューして」と頼むと、Claude Code が差分と関連する要件を読み、指摘を4段階のラベルで分類して下書きします。下書きはすぐには投稿されず、一覧として自分に提示されます。自分はその一覧から投稿する指摘を選び、必要なら文言を直してから、GitHub の PR にコメントとして投稿させます。

投稿の前にレビュワーが選ぶ工程を挟んだのには、理由が3つあります。

1つ目は、AI の指摘にはそのまま作者に届けたくないものが混ざるからです。AI は業務仕様を知らないまま判断するので、その種の指摘には間違いが含まれることがあります。そうした指摘や優先度の低い細かい指摘まで全部 PR に並べると、作者は指摘が正しいかどうかを確かめたうえで、一つずつ対応を判断しなければなりません。

2つ目は、レビュワーがその場で調整や追加をでき、その結果を skill の改善に回せるからです。一覧を見ながらラベルや文言を直せますし、一覧を読んで気になる点が新たに見つかれば、指摘を足して漏れを防げます。さらに、どの指摘を外したか、どのラベルを変えたか、どの文言を直したかが毎回手元に残ります。同じ直しが続いたら、それを skill のルールに書き足せば、次からは最初の下書きに反映されます。定期的に過去のレビューコメントを見返し、外した指摘や直した文言の傾向を確かめることで、skill を継続的にキャリブレーションできます。AI に直接投稿させる形では、こうした「レビュワーならこう判断した」という差分が残らないので、skill をキャリブレーションする手がかりが得られません。

3つ目は文面です。レビューで一番大事なのは指摘の中身が正しいことですが、AI の指摘は中身が正しくても、言い切りの多い固い文面になりがちです。固い文面は受け手を萎縮させ、正しい指摘でも素直に受け取ってもらいにくくなります。投稿前にレビュワーが目を通せば、中身を保ったまま、受け取りやすい文面に整えられます。

AI には下書きまでを任せ、どの指摘を作者に届けるかは人が決める。これが記事タイトルの「レビューは AI が書いて、人が選ぶ」の意味です。

skill の設計

レビューの流れ

skill には、次の流れでレビューするよう書いています。

  1. PR の差分と、変更ファイルの周辺のコードを読む
  2. PR にリンクされたチケット、Slack のスレッド、設計ドキュメントを開き、要件と実装を突き合わせる
  3. 指摘を must、want、nits、ask の4つに分類して下書きする
  4. 全指摘を一覧にしてレビュワーに提示し、レビュワーが確認して取捨選択する
  5. レビュワーが承認した指摘だけを、1件ずつインラインコメントとして投稿する

4 でレビュワーの確認を必ず挟むために、skill の冒頭に絶対ルールを書いています。承認前に投稿しないこと、承認されなかった指摘は投稿しないこと、ファイルを勝手に書き換えないことの3つです。

4つの分類ラベル

指摘の本文の先頭には、必ず次のラベルを付けます。

ラベル 意味 例
(must) マージ前に必ず直すべきもの。バグ、仕様違反、壊れた処理など (must) ここ null のとき例外になりそうなので直したいです
(want) 直してほしいが必須ではないもの。可読性や一貫性の改善など (want) この処理は共通ユーティリティに寄せてもいいかもです
(nits) 些細なもの。typo、空白、命名の揺れなど (nits) ファイル末尾には改行を入れましょう
(ask) 質問や意図の確認 (ask) ここは意図的に同期処理にしてますか?

ラベル自体は Conventional Comments などと同じ考え方で、新しいものではありません。この skill では、自分のチームで使っていた4つをそのまま AI にも使わせています。

ラベルがあると、作者は must だけ先に直す、nits は余裕があれば対応する、と優先度を付けやすくなります。業務仕様や作者の意図のように AI が断定できないものは、推測で must にせず ask にするよう指示しています。具体的な修正案があるときは GitHub の suggestion ブロックを付け、作者がワンクリックで反映できるようにしています。

レビュワーに提示する形式

下書きした指摘は、次の形式の表で提示させます。以下は形式の例で、実際には「指摘(投稿する本文案)」の欄に投稿する本文がそのまま入ります。

# ラベル 対象 指摘(投稿する本文案) suggestion
1 must path/to/file:25 本文そのまま あり
2 ask PR 全体 本文そのまま なし
3 want ファイル: path/to/file 本文そのまま なし

番号を振っているのは、「2番は外して」「3番は nits に下げて」のように短く指示できるようにするためです。投稿する本文をそのまま見せるので、レビュワーは投稿後の見た目を確認してから選べます。

skill が提示した指摘の一覧。番号、ラベル、対象行、投稿する本文案、suggestion の有無が並んでいる
この記事自体を skill でレビューしたときの提示画面

文面を自分のレビューに寄せる

AI の下書きをそのまま投稿しても違和感がないように、過去に自分が書いたレビューコメントを見返し、書き方の癖を skill に書きました。

何を書くかについては、次のルールにしています。

  • 指摘には必ず理由を添える
  • 直してほしいときは、suggestion ブロックや参考リンクで具体的な代案を添える
  • 1つの指摘は1〜2文で書く

どう書くか(口調)については、次のルールにしています。

  • 基本は敬体で書く
  • want と nits は「〜かもです」「〜した方が良さそう」のように断定しない
  • 硬い敬語や理由のない命令口調にしない

AI は口調を指示しないと固い文面を書きがちなので、柔らかい表現で書くよう指示しています。たとえば次のような違いです。

  • 固い文面:「この変数名では中身が想像しにくいため、user_count への変更を推奨します。」
  • 柔らかい文面:「この変数名だと中身が想像しにくいので、user_count とかにするといいかもです」

どちらも、直してほしい理由(中身が想像しにくい)と代案(user_count)は同じです。変えているのは言い回しだけで、「〜ため」「推奨します」という言い切りを、「〜ので」「〜といいかもです」という提案の形にしています。

運用して見えた課題と対策

以下は、レビュワーとして下書きを直すなかで同じ直しが続き、skill に書き足してきた例です。

must と want の線引きがぶれる

潜在的なバグを must にするか want にするかで、判定がぶれることがありました。多かったのは、今の使われ方ではたまたま問題なく動くものの、使われ方が変わると壊れるコードです。AI はこうした箇所を「今は動いている」という理由で want にしてしまい、本来 must で止めるべき問題を軽く扱うことがありました。

そこで判定の基準を「レビュー時点の使い方で動くか」ではなく、「その PR の変更によって渡せるようになる値の中に、壊れる入力があるか」と決めました。たとえばシェルスクリプトで変数をクォートしていない箇所は、固定の値なら動きます。しかし、その値を設定ファイルや Secrets から利用者が渡せるようにする PR なら、空白入りの値が渡された時点で引数が分割され、意図しない値が設定されたり、エラーでジョブが落ちたりします。この場合は既存の行であっても must にします。推測で must にしないよう、可能なら壊れる入力で実際に再現し、「確認しました」と本文に書かせています。

差分だけを見て的外れな指摘をする

差分だけを読むと、要件を知らないまま的外れな指摘をすることがあります。実際、チケットには書かれていない除外条件が、依頼元の Slack のスレッドにだけ書かれていたことがありました。

そこで、PR にリンクされたチケット、Slack、ドキュメント、スプレッドシートを開き、要件と実装の対応表を作るよう指示しました。要件にあるのに実装にない条件は must の候補にします。実装にあるのに要件にない条件は、全てのリンク先を確認してから ask にします。SQL の指摘は、BigQuery の dry run や件数を数えるクエリで裏取りしてから書かせています。

GitHub に投稿するときにつまずく

インラインコメントの投稿では、GitHub の仕様でつまずく箇所がいくつかありました。

  • インラインコメントは diff に含まれる行にしか付けられない。diff の外の指摘は、ファイル単位のコメントか PR 全体へのコメントに切り替える
  • 削除された行への指摘は side を LEFT にする
  • 日本語やバッククォートを含む本文は、JSON ファイルに書いてから gh api に渡すとエスケープの事故が起きにくい
  • 承認を待つ間に作者が push することがあるので、コメントを付けるコミットは投稿の直前に取り直す

これらは一度つまずくたびに skill に追記しています。

LGTM はレビュワーが言ったときだけ

指摘がない PR に Approve するかどうかも、レビュワーが決めます。レビュワーが「LGTM」と言ったときだけ、skill が Approve レビューを投稿します。

使ってみて

  • 半年ほど使っていますが、チューニングの甲斐もありクリティカルな部分はだいぶ指摘できるようになりました。
  • 当初よりもレビューの濃淡をつけやすくなりました。重要な PR は skill と自分の目でしっかり見て、Markdown だけの変更などは基本 skill に任せる運用にすることで、レビューの工数を体感で5割ほど減らせています。
  • 思ってもみなかった効果として、自分が PR を作ったときにも、レビューを依頼する前にこの skill で見てもらうと、レビュワーに指摘される前に課題を潰せるようになりました。

まとめ

Claude Code の skill で、AI がレビューコメントを下書きし、人が選んでから投稿する PR レビューの仕組みを作りました。AI には分類ラベル付きの下書き、要件との突き合わせ、データでの裏取りまでを任せています。どの指摘を作者に届けるかと、Approve するかどうかはレビュワーが決めます。

付録:skill のベーシック版

記事で紹介した skill を、汎用的に使える形に整えたベーシック版です。 ~/.claude/skills/pr-review/SKILL.md として置けば、Claude Code から使えます。

なお、ここに載せたものは実際に運用している skill そのものではありません。実際の skill には、社内のリポジトリ固有のルール、社内ドキュメントへのリンク、業務の具体例を書き足していますが、それらはここでは除いています。口調の例やレビュー観点も自分のチーム向けのものなので、そのまま使うのではなく、自分のチームの口調や規約、レビューで実際に直した内容に合わせて書き足していく前提で使ってください。また、動作を保証するものではないので、利用は自己責任でお願いします。

---
name: pr-review
description: GitHub の PR / ブランチをレビューし、指摘を must/want/nits/ask に分類してインラインコメント(該当すれば suggestion 形式)で投稿する。PR や feature ブランチの「レビューして」「指摘して」「レビューコメントを付けて」と依頼されたときに使う。投稿前に必ず全指摘をユーザーに提示して承認を得る(人手確認が必須)。
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
---

# PR レビュー(分類ラベル付き)

GitHub の PR / ブランチをレビューし、指摘を **must / want / nits / ask** に分類して
インラインコメントで投稿するためのスキル。

## 絶対ルール(MUST)

- **投稿前に全指摘を必ずユーザーに提示し、明示的な承認を得てから投稿する。**
  勝手に GitHub へ投稿しない。ユーザーは各指摘を取捨・修正できる。
- 承認された指摘のみを投稿する。ユーザーが「これは要らない」と言ったものは投稿しない。
- 自動修正でファイルを書き換えない。修正実施は作者・人間レビュワーに委ねる。

## 分類ラベル

各指摘の本文の先頭に必ずラベルを付ける。深刻度の高い順:

| ラベル | 意味 | 例(この口調で書く) |
|--------|------|-----|
| `(must)` | マージ前に必ず直すべき。バグ・仕様/規約違反・壊れた処理など。 | `(must) ここ null のとき例外になりそうなので直したいです` |
| `(want)` | 直してほしい推奨。品質・可読性・一貫性の向上。必須ではない。 | `(want) この処理は共通ユーティリティに寄せてもいいかもです` |
| `(nits)` | 些細な指摘。typo・文末・空白・命名の揺れなど。無視可。 | `(nits) ファイル末尾には改行を入れましょう` |
| `(ask)` | 質問・意図確認。修正を断定せず作者に確認したいこと。 | `(ask) ここは意図的に同期処理にしてますか?` |

- 具体的な修正案があるものは GitHub の **suggestion ブロック**を併記する(作者がワンクリック反映できる)。
- 断定できない業務仕様・意図は `(ask)` にする。推測で `(must)` にしない。
- **潜在バグの must / want 判定は「レビュー時点の使い方で動くか」ではなく「その PR が作る契約の中に壊れる入力があるか」で決める。**
  現在の値・現在の呼び出し方では動いていても、PR によって値が可変になる(設定ファイル・Secrets・ユーザー入力などで利用者が自由に値を渡せるようになる)なら、壊れる入力は「いつか必ず踏まれる」ものとして `(must)` にする。
  - 例: シェルスクリプトの変数クォート漏れ。固定の bot 名では動くが、空白入りの値を設定されると `git config user.name ${USER_NAME}` の引数が分割され、`Foo Bar` なら `Foo` だけが設定され、`Foo Bar Baz` ならエラーでジョブごと落ちる。値が設定外だしされた PR ではこれは `(must)`(既存行のままでも)。
  - この判定を使うときは推測にせず、可能なら実際に壊れる入力で再現して「確認しました」と本文に書く。
- **本文でラベル名を繰り返さない**(先頭のラベルと重複になる)。
  - ✗ `(want) 〜。wantなのでLGTMです`
  - ○ `(want) 〜。今のままでもマージは大丈夫です!`

## 文面のトーン(重要)

固い・威圧的・命令的な文面にしない。以下は実際のレビュー文面から抽出した口調。これに寄せて書く。

**DO**
- 基本は敬体(です・ます)。
- 指摘には**必ず理由を添える**(「〜ので」「〜ため」)。命令だけで終わらせない。
- want / nits はやわらげる:「〜かもです」「〜した方が良さそう」「〜してもいいかも」「〜な気がします」。
- 依頼は「〜して欲しいです」「〜お願いします」。質問は素直に「〜ますか?」。
- 具体案は `suggestion` ブロックや外部リンクで補強する。
- 1 指摘 = 1〜2 文で簡潔に。

**DON'T**
- 硬く仰々しい敬語(「〜していただきますようお願い申し上げます」等)は使わない。
- 絵文字は基本使わない。
- 理由なしの一方的な命令口調にしない(must でも一言理由を添える)。
- want / nits を断定しない。

例(固い → 寄せた形):
- ✗「記号の不整合です。〜と混在しています。〜が正だと思われます。」
- ○「ここだけ ◆ と『推奨』が混ざってる気がします。直上と揃えるなら `◇推奨` かもです。」

## レビュー観点チェックリスト

- **バグ・ロジック誤り**:null/空/境界値、エラーハンドリングの漏れ、壊れた処理。
- **セキュリティ**:credential の混入、個人名の混入、`.gitignore` の設定。
- **テスト**:ロジック変更に対応するテストがあるか。ないなら理由を `(ask)` で確認。
- **後方互換性**:既存の呼び出し元・利用者を壊す変更がないか。
- **既存パターンとの整合**:リポジトリ内の規約・類似実装と揃っているか。
- **要件との突合**:PR にリンクされた一次情報(チケット・チャット・ドキュメント)を遡って要件とコードを突き合わせる。
- **PR テンプレートの充足**:未記入のセクションが残っていないか。
- **動作確認の記載**:ドキュメント以外の変更なら、動作確認の項目と結果が書かれているか。なければ `(ask)` で確認する。

## 手順

### 1. 対象の特定
```bash
gh pr list --head <branch> --state all --json number,title,url,headRefOid
gh pr view <number> --json baseRefName,headRefOid
```
- ベースブランチを `main` 固定と思い込まない。
- コメント投稿に使う `commit_id` はここでは確定しない(手順5で投稿直前に再取得する)。

### 2. 差分と文脈の把握
```bash
git fetch origin <baseRefName> <branch>
git diff origin/<baseRefName>...origin/<branch>
gh api repos/<owner>/<repo>/pulls/<number>/comments --paginate --jq '.[] | {path, line, body}'
gh pr checks <number>
```
- 差分だけでなく、変更ファイルの周辺・既存の規約/類似実装も読む。
- 既存レビューコメントと同趣旨の指摘は新規投稿しない。
- PR 本文にリンクされた要件の一次情報は、リンク先まで開いて確認する。
  **要件 ⇔ 実装の対応表**を作り、要件にあるが実装にない条件は `(must)` 候補、
  実装にあるが要件にない条件は全ソースを確認してから `(ask)` にする。
- データで裏取りできる指摘(SQL の実行可否、件数系の懸念など)は裏取りしてから書く。

### 3. 指摘の作成
- 各指摘に、対象(`file:line`)、ラベル + 何が問題か + **なぜ**そう直すべきか、該当すれば suggestion 案を付ける。
- インラインコメントは diff のハンクに含まれる行にしか付けられない。
  diff 外の指摘は、ファイル単位コメント(`subject_type: file`)か PR コメントに切り替える。

### 4. ユーザーへ提示(← ここで必ず止まる)

| # | ラベル | 対象 | 指摘(投稿する本文案) | suggestion |
|---|--------|------|----------------------|------------|
| 1 | must | `path/to/file:25` | 本文そのまま | あり/なし |
| 2 | ask | PR全体 | 本文そのまま | なし |
| 3 | want | ファイル: `path/to/file` | 本文そのまま | なし |

- 番号を付けるのは「2番だけ外して」「3番のラベルをwantに」のような指示をしやすくするため。

### 5. 投稿(承認後のみ・指摘ごとに個別コメント)
- 投稿直前に `commit_id` を再取得する(承認待ちの間の push で古くなっている可能性があるため)。
- 本文は JSON ファイルに書いてから投稿する(日本語・バッククォート・改行のエスケープ事故を防ぐ)。
```json
{
  "body": "(must) 〜理由〜\n\n```suggestion\n<修正後の行>\n```",
  "commit_id": "<headRefOid>",
  "path": "<repo相対パス>",
  "line": 25,
  "side": "RIGHT"
}
```
```bash
gh api --method POST repos/<owner>/<repo>/pulls/<number>/comments \
  --input <comment.json> --jq '{id: .id, url: .html_url}'
```
- 削除行(赤側)への指摘は `side` を `LEFT` にする。
- suggestion ブロック内の行は置き換え後の全文にする。

### LGTM(ユーザーが「LGTM」と言ったとき)
- ユーザーが「LGTM」と言ったときだけ、`gh pr review <number> --approve --body "LGTMです"` で Approve レビューを投稿する。自分の判断で勝手に Approve しない。

### 6. 報告
- 投稿した各コメントの URL と、ラベル別の件数をまとめて報告する。投稿しなかった指摘も明記する。
電電

SaaS プロダクトのデータ基盤の開発・運用を担当

電電

新卒でリクルート入社。旅が好きで世界一周したりしていました。夢は南極に行くこと。→行きました!!