はじめに
Claude Code にはコードレビューを支援する公式機能として「Claude Code Review」が提供されています。
これ自体も便利ですが、自分でレビューガイドラインを Markdown で書いて Skills として読み込ませたところ、公式機能よりも的確なレビューが返ってくるようになりました。
本記事では、実際に構築したレビュー Skill の設計と、精度を上げるために工夫したポイントを共有します。
レビュー Skill の全体構成
最終的に整備したディレクトリ構成は以下のとおりです。
~/.claude/skills/
└── code-review/
├── SKILL.md # レビュー手順・共通観点
└── guidelines/
├── cross-cutting.md # 全PR共通の横断観点
├── rails.md # Rails 固有の観点
├── nextjs.md # Next.js 固有の観点
├── terraform.md # Terraform 固有の観点
└── ...
SKILL.md にはレビューの手順とサイクルの定義を書き、具体的な技術観点は guidelines/ に分割しています。技術スタックが増えてもファイルを追加するだけで対応でき、メンテナンスしやすい構成です。
ガイドラインには一般的なコーディング規約に加えて、チームの暗黙知（過去の PR レビューで繰り返し指摘されてきたパターンや、Confluence / Notion に散在する設計方針など）も取り込んでおくと精度がさらに上がります。
サンプルリポジトリを公開しているので、実際のファイル内容はこちらを参照してください。
工夫ポイント
レビュー Skill を作る上で、特に効果が大きかった工夫を紹介します。
網羅と推敲のレビューサイクル
これが最も効果を実感した工夫です。レビューを1回で終わらせず、2回に分けて実施するよう SKILL.md に定義しています。
## レビューサイクル
### 第1回レビュー: 網羅的なリストアップ
- 気になる点をすべて列挙する
- 重要度は問わず、見つけたものを全て出す
### 第2回レビュー: 批判的な検証と厳選
- 第1回の指摘を見直し、本当に必要な指摘のみに絞る
- 重要度を Critical / High / Medium / Low で設定する
- 影響範囲を調査してから指摘する（省略禁止）
AI にレビューを頼むと、1回のパスではどうしても「言いたいことを全部言う」状態になりがちです。的外れな指摘や好みレベルの指摘が混ざり、本当に重要な指摘が埋もれてしまいます。
2回に分けることで、第1回で見落としを防ぎ、第2回で精度を上げるというバランスが取れます。人間のレビューでも「一度全体を見てから、もう一度重要な箇所を精査する」というのは自然な流れですが、それを明示的に指示するだけでアウトプットの質が大きく変わります。
diffのみでなく、影響範囲の調査を必須にする
もう一つ大きかったのが、diff を見る前に影響範囲を調査するステップを必須にしたことです。
## 影響範囲の調査（レビュー前に必ず実施）
> この手順を省略しない。変更ファイルだけを見てレビューを始めてはならない。
調査すべき観点:
- 変更されたクラス・関数を呼び出している既存コード
- 変更されたテーブル・スキーマを参照している他のクエリやモデル
- 変更された API エンドポイントを利用しているフロントエンドや他サービス
- 既存のテストが意図せず壊れる可能性がある箇所
多くの AI レビューツールは PR の diff だけを見てコメントを生成します。しかし、「diff だけ見ると問題なさそうだが、呼び出し元を考慮すると破壊的変更になっている」というケースは少なくありません。
影響範囲を先に調べてからレビューに入ることで、diff の表面だけでは気づけない問題も検出できるようになりました。
ガイドラインの動的選択
SKILL.md に「変更内容に応じてどのガイドラインを読み込むか」のルーティングロジックを定義しています。
| 変更内容 | 読み込まれるガイドライン |
|---|---|
| Rails の Controller / Model |
cross-cutting.md + rails.md
|
| Next.js のコンポーネント |
cross-cutting.md + nextjs.md
|
Terraform の .tf ファイル |
cross-cutting.md + terraform.md + 対象サービスのガイドライン |
| DB マイグレーション |
cross-cutting.md + 言語別ガイドライン + sql.md
|
全 PR 共通の横断観点（cross-cutting.md）は常に読み込み、それ以外は変更内容に応じて取捨選択します。全てのルールを一律に適用するのではなく、関連するものだけを使うことでノイズを減らし、精度を保っています。
リポジトリ固有の設計方針を明文化する
リポジトリごとに採用しているアーキテクチャや設計方針は異なるため、guidelines/ 配下にリポジトリ別のファイルを用意しました。
以下は、Rails アプリケーションで Service 層を導入しているリポジトリの例です。
# Rails 実装レビュー観点
## アーキテクチャ概要
本リポジトリでは Rails Way をベースにしつつ、
ビジネスロジックの肥大化を防ぐために Service 層を導入している。
## レイヤー責務チェック
以下のいずれかに該当する場合、
ロジックが誤ったレイヤーに配置されている可能性がある。
- [ ] Controller にビジネスロジックが書かれていないか
- [ ] Controller にテストしづらいコードが混入していないか
- [ ] Service を経由せずに Model のスコープやクエリを直接組み立てていないか
- [ ] Model に本来 Service が持つべき複雑な業務ロジックが肥大化していないか
NG パターンの例
# NG: Controller にロジックが漏れている
class OrdersController < ApplicationController
def create
order = Order.find(params[:id])
if order.status == "pending" && current_user.premium? # ← ここは Service に書くべき
order.update!(status: "confirmed", discount: 0.1)
end
end
end
OK パターンの例
# OK: Service に委譲する
class OrdersController < ApplicationController
def create
result = OrderService.new.process(order: Order.find(params[:id]), user: current_user)
# ...
end
end
同じ Rails プロジェクトでも「Fat Model を許容するか」「Service 層をどこまで使うか」はチームによって判断が分かれるところです。こうした設計方針を Markdown で明文化しておくことで、Claude が PR をレビューする際に自動でその観点を持って動いてくれます。
レビュー用ワークツリーの活用
SKILL.md ではレビュー時に git worktree を使ってPRのブランチを別ディレクトリに展開するよう指示しています。
## レビュー用ワークツリーの作成
git fetch origin <PRのブランチ名>
git worktree add ./review-<PR番号> origin/<PRのブランチ名>
cd review-<PR番号>
これにより、以下のメリットが得られます。
-
作業中のブランチを切り替えずにレビューできる --
git stashやgit checkoutが不要になり、レビュー中も自分の作業を継続できる - 影響範囲の調査がリポジトリ全体に対して行える -- diff だけでなく、呼び出し元やテストファイルを Grep / Read で横断的に調査できる
-
クリーンアップが確実 --
git worktree removeで完全に消えるため、レビュー後の後片付けが簡単
ガイドラインの自己改善ループ
SKILL.md に「ガイドライン改善提案」のセクションを設けています。
## ガイドライン改善提案
レビュー完了後、以下の条件に該当する指摘があった場合、
SKILL.md または guidelines/ への追記案を提示すること。
- 同種の指摘が直近のレビューで繰り返し発生している
- 既存のガイドラインではカバーされていない新しい観点である
- チーム全体に共有すべき設計判断・NG パターンが含まれている
レビューを重ねるなかで、「この観点はガイドラインに追記すべきか」を Claude 自身が判断し、追記案を提案してくれます。 レビューで得た知見がガイドラインに還元され、次回以降のレビュー精度がさらに上がるというフィードバックループが自然に回るようになりました。
使ってみた感想
レビュー体験の変化
SKILL.md を整備してから、PR レビューの体験が大きく変わりました。
Claude Code に「この PR をレビューして」と頼むだけで、影響範囲の調査から始まり、2回のレビューサイクルを経て、GitHub の Pending Review まで作成してくれます。レビューコメントは重要度付きで整理されており、最終確認して Submit するだけです（もちろん diff は確認します）。
Claude Code による実際のレビュー指摘例
一度 SKILL.md に定義した観点は必ず確認されるので「また同じことを指摘するのは気まずい」「あのルール、もう伝えたはずなのにまた同じミスをされた」という状況がなくなり、レビュアー・レビュイーどちらにとっても心理的安全性が上がったと感じています。
公式 Claude Code Review との比較
公式の Claude Code Review とも性能比較をしてみましたが、Skills アプローチの方がより的確な印象を受けています。
公式機能は汎用的なベストプラクティスに基づくレビューには強いですが、チーム固有の設計方針やリポジトリ固有のアーキテクチャルールまでは拾えません。Skills アプローチでは、これらの観点が Markdown で定義されているため、チームの文脈を踏まえたレビューが実現します。
また、影響範囲の調査や2回レビューサイクルといったレビューの手順そのものを制御できる点も、公式機能にはない強みです。
副次的な効果
レビュー Skill を整備する過程で、副次的にいくつかの効果がありました。
設計相談の精度向上: 新機能の設計を Claude Code に相談すると、Skills に定義された観点を踏まえて「このリポジトリでは Service 層にビジネスロジックを寄せる方針なので、バッチの実行ロジックも Service として切り出す構成を提案します」といった形で、チームの設計方針に沿った提案が最初から返ってくるようになりました。
オンボーディング: レビュー観点が SKILL.md として言語化されているため、チームの暗黙知が可視化されます。私自身、3月から新しい組織で業務に参画していますが、「このプロジェクトでは何を大事にしているか」を効率よく把握でき、立ち上がりのスピードに直結しています。
補足: CLAUDE.md に書くべきでは？
CLAUDE.md については、「50行以下が理想で、何を"書かないか"が重要」と言われています。以下のツイートでも触れられている通り、150行を超えると先頭偏り（primacy bias）が起きて後半の指示が無視されやすくなるため、CLAUDE.md にはルーティング指示や禁止事項など最小限の内容に留めるべきとされています。
そのため、継続的に育てていく必要がある「レビュー観点や設計方針」は Skills に分離することにしています。
まとめ
Claude Code の Skills でレビューガイドラインを自作したところ、公式機能や汎用ツールよりも的確なレビューが得られるようになりました。
特に効果が大きかったポイントは以下の3つです。
- 2回レビューサイクル -- 網羅性と精度を両立させる
- 影響範囲の事前調査 -- diff の表面だけでは見えない問題を検出する
- ガイドラインの自己改善ループ -- レビューを回すほどガイドラインが育つ
一度仕組みを作れば、レビューの工数は大幅に削減され、品質も一貫します。ガイドラインは使い続けるほど育っていくので、早く始めるほど効果が積み上がります。
ぜひみなさんも試してみてください。
Discussion