はじめに
ソニックガーデンには、つよつよなコードレビュー文化があります。年単位で保守する前提のプロダクトばかりなので、毎日メンバーが互いのコードを読んで、容赦ない指摘が飛び交ってます。
他にも
- レビューを題材にした書籍 「コードレビューで学ぶ Ruby on Rails 第三版」 が技術書典に出ている（第三版！？）
- コードレビュー力を鍛えるための 「ソニックガーデンジム」 がある（僕も参加しました）
くらいのレベルです。すごい。
そんな環境で日々レビューを受けていると、「この観点、人間の頭の中だけにあるのもったいなくない？」という気持ちが湧いてきます。新しく入った人にも、未来の自分にも、なんなら一緒に働く Claude Code にも、同じ観点で見てほしい。
この記事は、そのレビュー観点を Claude Code のスキルにしてみたよという内容です。
AI レビューめっちゃ良くなった。でも先輩を超えられない
最近のAIコードレビュー、正直めちゃめちゃすごいです。Claude Codeでも、GitHub連携のAIレビューでも、「やるやん」というレベルのコメントが普通に飛んできます。
少し前までの「変数名を見直しましょう」みたいな虚無な文章はほぼなくなった気がします。
のですが、AI レビューをした後でも、先輩レビュアーから指摘が普通に飛んできます。多いときで 20 件、少ない PR でも 2〜3 件は必ず出る。AI レビューが「マージ可能です」と言ってくれた数分後に、先輩から「ここはこうして欲しいんだよね」と来ます。
例えば、こういうのが飛んできます。
「...っていうのは今現在の話でしかないので、あまり『良し』としない方がいいと思います。（担当が代わったり増えたりする可能性はいくらでもある）」
それは今のAIには気づけんよ...。（自分も気づけなかった）
プロダクトは年単位で保守する前提で、判断軸には 「5 年後の自分（または引き継いだ誰か）が読み解けるか」 というのがあり、ただ「動けばいい」では通らない。
こういうのは 「ソニックガーデンが大事にしている『いいコード』の基準を知っている人にしか出せない指摘」 で、その基準はリポジトリにも完全には書かれていません。
なんかルールブックがあるわけでもなく（欲しい）、毎回のコメント・たまに記事化されたもの・先輩の頭の中、チームごとに分散して棲みついてて、そして「いいコード」が毎秒更新されるので、AIが知らないのも当然。
なので AI が持ってる汎用的な観点に加えて、自分たちの『いいコード』の基準をAIに教えていくしかない。
ということで、まずは「過去レビューをかき集める」
スキルを書き始める前に、素材集めをします。
長年のレビュー文化から、「いいコード」を積み上げてきたからこそできることで、Claude Code に渡すレビュー観点も、頻出パターンを抽出する元ネタも、ぜんぶそこに溜まっているので活用しない手はないですよね。
手順はこんな感じです。
- 直近1年くらいの先輩からの指摘コメントを集めて、JSONにまとめて取り回せる形にする
- その JSON を Claude Code に渡して、頻出パターンを分析させる
- 分析結果をベースに、スキルとして書き出す
1. 直近1年分の指摘コメントを集めて JSON にする
Claude Code に丸投げします。具体的には、こんな感じで指示するだけ。
このリポジトリで、直近 1 年に PR に書いたコメントを全部集めてください。ファイルパス・行番号・本文・PR 番号・URL を含めた JSON で
review_comments.jsonに保存してください。
ノイズを減らしたければ、続けてこう言う。
本文が極端に短いコメント（絵文字だけ、
+1など）は除外してください。
これで直近 1 年くらいの指摘コメントが、構造化された JSON で手元に残ります。雑にやっても数百件は集まるので、観点の素材としては十分です。
2. JSON を Claude Code に分析させる
集めた JSON を、そのまま Claude Code に分析させます。これも指示は雑で OK。
review_comments.jsonにレビューの指摘があります。
これを以下の観点で分析してください:
- 頻出する指摘パターンをカテゴリ分けし、件数と割合を出す
- 各カテゴリで代表的なコメント本文を 2〜3 件、引用する
- 「このレビュアーが暗黙に持っていそうな判断軸」を仮説として書く
出力を眺めて「もうちょっと粒度細かくして」「このカテゴリは 2 つに割って」と返しながら、手で粒度を整えます。最終的には、自分が読んで腹落ちする粒度になっているかが大事です。
3. 出てきた頻出パターンを眺める
実際に二人のレビュアーぶんを回してみたところ、こういう分布が見えてきました（数字はざっくりです）。
| 観点 | 比率の感覚 | 例 |
|---|---|---|
| 可読性・命名 | 25%前後 | 1 行詰め込み、Date/Time の _on/_at
|
| 責務配置・Rails イディオム | 25%前後 | 既存 concern と被ってる、find_or_initialize_by で書ける |
| テストの検証力不足 | 15%前後 | データが ID 順、初期状態未検証、have_content 羅列 |
| 過剰な防御的プログラミング | 10%前後 |
&. や || [] 本当に必要？ |
| エラーハンドリング・運用想像 | 10%前後 | 失敗時にログ残ってる？本番 URL は？ |
| ドメイン/PR スコープ | 残り | フラグの意味のすれ違い、PR の混ぜすぎ |
パターンを見て思ったのは先輩ごとに観点の重みが違うこと。ある先輩は「責務がどこにあるべきか」を問うタイプで、別の先輩は「読み手の負荷とテストの証明力」を問うタイプ。それでも根っこには共通軸があって、表現の癖は違うのに、判断の方向は揃っている。共通の思想があるんですね。
と、ここまで来てようやくスキルとして書き出す材料が揃いました。
スキルに書き出すときに気をつけたこと
あとは Claude Code の skill-creator を使って、スキルを作成してもらいます。レビュースキル先輩Aバージョンとレビュースキル先輩Bバージョンで2つ作ってます。
以下のような感じで作ってもらいました。
-
「禁止」ではなく「問いかけ」で書く: 「
&.を使うな」ではなく「本当に nil が来るかを呼び出し元やバリデーションから判断して」と書く。 - 指摘の強度を 3 段階で出させる: 「要修正 / 改善提案 / 好みレベル」を付けさせる。温度差を明示させる。
- diff の外を読ませる: 例えば「新しい scope を追加したら既存の同種 scope を探す」と書いておく。
実際に使ってみた
指摘の量が減った...気がする。 A/Bテストで比較してみたいですが、1回目と2回目でPRに関する記憶をなくしてもらう必要があり、そんなことできないのでちゃんとは分からないです。多分減ってます。
観点が文書化されたこと自体に価値があった。 正直これが大きいかもしれないです。自分の中でもこういうの指摘されがちだよなーと思っていたことが言語化されて、実装中にその観点を含んだ実装をするようになりました。
まだまだ改善の余地はありそうです。このスキルも現時点のスナップショットから作成しているものなのでメンテナンスは必須です。
おわりに
たぶん大事なのは、Claude Code を賢くすることだけではなく、自分たちが何を大事にしてレビューしているのかを、ちゃんと言葉にしていくことなんだと思いました。
がんばれ、Claude Code と自分。
Discussion