REVIEW.mdはClaude Codeのどのレビューで読まれるのか？

REVIEW.mdを書いたのに、手元のClaude Codeのレビューが変わらない。公式ドキュメントでは、REVIEW.mdを読むのはGitHubのプルリクエストを見るマネージドのCode Review（Team・Enterpriseプラン）で、手元の /code-review が従うのはCLAUDE.mdのほうだとされています。手元で3つの条件を回した記録と合わせて、レビューの観点をどこに書けば届くのかを整理します。

REVIEW.mdを読むのは、GitHubのPRを見るCode Review

Code Review をカスタマイズするのページに、はっきり書いてあります。

自分のマシン上の Claude Code セッション内で実行する /code-review コマンドは、CLAUDE.md ファイルを読み込みますが、REVIEW.md は読み込みません。

claude -p で非対話に回しても同じだと、ローカルレビューのページに明記されています。

Code Review - Claude Code Docs

Code Review で GitHub のプルリクエストのバグを検出します。Claude が各変更をレビューし、結果を検証して、インラインでコメントします。Team および Enterprise プラン向けです

code.claude.com

マネージド版にも落とし穴があります。REVIEW.mdはベースブランチかデフォルトブランチから読まれ、プルリクエスト自体の変更からは読まれません。REVIEW.mdを足したそのPRには効かないので、先にマージします。さらに、nitの上限やパスの除外が効くのは、保護したデフォルトブランチ（またはルールセットで保護したベースブランチ）から読まれたときです。保護設定を確認できない構成では、読み込まれるファイルは「なし」になります。

あなたのREVIEW.md、どのレビューに読ませるつもりで書きましたか？

CLAUDE.mdとREVIEW.md、手元のレビューで差は出たか？

使い捨てのgitリポジトリで比べました。Rails風のファイルを置いただけで、アプリは動かしていません。feature ブランチに、欠陥を5つ入れたコミットを1つ足しています。

1. 一覧から includes(:customer) を消したN+1
2. params[:order].to_unsafe_h でStrong Parametersを外した create
3. Order.find で他人の注文も見える show
4. down が IrreversibleMigration を投げるマイグレーション
5. specのない新しいスコープ recently_ordering

条件はA（リポジトリに指示ファイルなし）、B（main にCLAUDE.md）、C（main にREVIEW.md）です。BとCには5つの観点を1行ずつ書いた同じ本文を置き、差分は3つともそろえました。手元のグローバルCLAUDE.md（レビューと無関係の内容）は外せず、3条件とも読み込まれています。実行は claude -p "/code-review" --model sonnet --permission-mode plan、Claude Code v2.1.284、モデルはSonnet 5.5です。

記録した5回とも、5つ全部が指摘されました。1回あたり21〜29秒、0.08〜0.11ドル（約11〜17円）で、5回の合計は0.49ドル（約74円）です。いずれも1ドル150円での換算です。

Aは実は3回回していて、1回は保存に失敗したので表に入れていません。その1回は0.14ドルで、数字は手元の実験メモにしか残っていません。

差らしきものは欠陥5だけでした。BとCは「specがない」を1件の指摘として立て、Aは別の指摘のついでや補足として触れています。とはいえ、同じAの2回でも指摘の数は9件と8件で、書き方も揺れていました。手元のレビューの指摘が実行のたびに少しずつ違う、と感じたことはありませんか？ 記録できたのは各条件1〜2回で、この回数では、この差はぶれと見分けがつきません。

ここで終わるなら「差は出なかった」で済む話でした。Cの出力を読み返すまでは。

出力にREVIEW.mdの名前が出た1回

Cの出力は9件の指摘をJSONで返していて、そのうち5件の説明に、こんな一文が入っていました。

REVIEW.md の Strong Parameters の項目に該当する。

権限チェック、マイグレーションの可逆性、N+1、テストの有無も同じ形で、REVIEW.mdに書いた5項目の名前がそのまま出ています。CLAUDE.mdに同じ5行を置いたBの2回には、CLAUDE.mdに触れた文が1つもありません。

docsの「読み取りません」と食い違って見えますよね。理由はわかりません。考えられるのは、たとえば次の3つです。

1. レビューの途中で、モデルがリポジトリ直下のREVIEW.mdを普通のファイルとして開いた
2. docsの「読み取りません」が「レビューの指示として組み込まない」という意味で、docsと出力は両立している
3. docsの記述と、今回のバージョンの実装が食い違っている

出力のJSONにはツール呼び出しの履歴が残っていませんでした。どれなのかは、この実験からは決められません。

それに、名前が出てもCが見つけた欠陥はAと同じ5つでした。1回だけの出来事から「手元でもREVIEW.mdが効く」と読むのは早すぎます。手元の運用は、docsどおりCLAUDE.mdを前提に組むほうが安全です。

Claude Codeの開発チームが、REVIEW.mdに書かせていること

Claude Codeの開発チームがAnthropicの開発者向けブログ（claude.dev）に載せたレビュー運用の記事（記事の日付は10月15日で、claude.com/blogの一覧カードは16日）によると、6月から9月にかけて、Claude Codeのコードベースにマージされたプルリクエストは2倍を超え、リバートが必要になった割合は40%以上下がりました。レビューは7つの層で積まれていて、一人の開発でも置けそうなのは次の4層です。右の列は私の案です。

残りの3層（リスクに応じた人の承認、マージキューとフラグと段階リリース、速い検知と速い戻し）は、承認者が複数いるチームやリリースの仕組みが前提です。

REVIEW.mdは「コードオーナーが書き、そのコードで何が大事かをレビュアーに伝える」ファイルで、良いものは短い、とブログは書いています。そのリポジトリで何が失敗にあたるか（ドキュメントなら「嘘をつく」）を書き、nitに上限を設け、飛ばすパスを並べ、名前からの推測でなくファイルと行を根拠に求める。要約は件数から始めさせます。

紛らわしいのは導入のすすめです。ブログはPRを出す前の手元の作業として、/code-review を回すことと、REVIEW.mdを足すことを続けて並べています。PRごとのAIレビュアー（Code ReviewかGitHub Action）を入れる段では、「REVIEW.mdを数週間かけて調整する」と書いています。

これだけ読むと、手元のレビューもREVIEW.mdを読むように受け取れてしまいます。私が確認できた範囲のブログには、手元の /code-review がREVIEW.mdを読むかを明示した文はありませんでした。docsと合わせるなら、PRごとのレビュアー向けの話と読むのが無理がなさそうですが、そこまでは書かれていません。

REVIEW.mdの差が見える実験に要るもの

検出数に差が出なかった理由として、私が一番疑っているのは仕込みの易しさです。N+1も権限チェックの欠落も、標準のレビューが最初から拾う種類でした。指示がなくても全部見つかるなら、指示ファイルの効き目は測れません。

ヒントは欠陥5です。マネージド版のdocsは、標準では本番を壊すバグに焦点を当て、テストカバレッジの欠落は狙いに入れていないと書いています。指示の有無で書き方が変わって見えたのも、このテストの欠如だけでした。標準の観点から外れたものほど指示の差が出やすいのではないか、と見ています（これも推測です）。

次に組むなら、指示がないと出てこない指摘を混ぜます。

• チーム固有のルール違反（たとえば、ログにメールアドレスを出す変更）
• nitの上限。手元の出力には重大度の区分が付いていなかったので、件数の変化で見る
• 生成ファイルの除外パス
• 根拠に file:line を求める指示や、件数から始まる要約

最後の2つは、効けば出力の形に表れます。回数も各条件5回は欲しいところで、1回10円台なら3条件を5回ずつ回しても300円かかりません。

マネージド版が使えないなら、レビューの観点はCLAUDE.mdに

docsは「両方で適用したいガイダンスは CLAUDE.md に記述し、REVIEW.md はプルリクエストのレビューに固有のルールのために使用してください。」と書いています。/code-review は組み込みのスキルで、編集できる SKILL.md はありません。すべてのレビューに従わせたいルールは、CLAUDE.mdに足すのが正規の道です。

Bで置いたのはこの5行です。今回の差分では効き目が見えなかったので、書く場所と書き方の見本として使ってください。

# レビューで見てほしいこと

- N+1クエリ: 一覧で関連レコードを参照しているのに includes / preload がない箇所を指摘する。
- Strong Parameters: コントローラーで params を permit せずにモデルへ渡している箇所を指摘する。
- 権限チェック: ログインユーザー自身のレコードに絞らず、IDだけでレコードを引いている箇所を指摘する。
- マイグレーションの可逆性: down で戻せない変更、データが消える変更を指摘する。
- テストの有無: クエリやスコープを追加・変更しているのに、対応するspecがない箇所を指摘する。

CLAUDE.mdは、レビュー以外の作業でも毎回読み込まれます。ブログも、大きなリポジトリではCLAUDE.mdを短く保つと書いています。ここに置くのは「どのレビューでも必ず見てほしいこと」に絞るのがよさそうです。手順ごと自分で持ちたいなら、code-review という名前のプロジェクトスキルを作ると、/code-review と打ったときは組み込みのものの代わりに動きます（/review は組み込みのままです）。

手元のレビューの観点、いまどこに書いていますか？ REVIEW.mdはPRのレビュー用、手元のレビューにはCLAUDE.mdです。私が次に回すなら、ログにメールアドレスを出す変更とnit向きの小さな指摘を混ぜた差分で、CLAUDE.mdの有無を5回ずつ比べます。