REVIEW.mdカスタマイズでClaude Codeの自動レビュー基準を変える

REVIEW.mdは、GitHub PR自動レビュー機能(Code Review)がPRを見る基準を書き換えるリポジトリルートのファイルです。何を🔴 Importantとして報告するか、🟡 Nitを何件まで許すか、どのパスをスキップするかを、既定のレビュー基準の上から上書きできます。本稿はREVIEW.mdで調整できる7項目と、そのまま使える実例テンプレートをまとめます。

REVIEW.mdはどう効くか

REVIEW.mdはリポジトリルートに置く素のMarkdownで、レビューパイプラインの全エージェントへ最優先の指示ブロックとして逐語(そのままの文字列)で注入されます。既定のレビュー方針より優先されるため、既定基準と矛盾する指示を書けばREVIEW.md側が勝ちます。

@によるファイルインポート構文は展開されません。他ファイルを参照する記述をしても、その中身は読み込まれずレビューに反映されないので、効かせたいルールはREVIEW.md本体に直接書きます。プロジェクト全体で共有する前提知識は通常セッションでも参照されるCLAUDE.mdが担い、レビュー専用の指示だけをREVIEW.mdに置くという役割分担です。両ファイルの効き方の違いと、チーム全体への導入手順はClaude Codeチーム導入ガイドにまとめてあります。GitHub App自体のセットアップ手順や指摘の見え方はClaude CodeでGitHub PR自動レビューを設定・運用するを参照してください。

調整できる7項目

REVIEW.mdはフリーフォームのMarkdownなので、レビューへの指示として書けることは何でも対象になります。実務で効果が大きい7項目は次のとおりです。

重大度の再定義

既定の🔴 Importantは本番コードを想定した基準です。ドキュメントリポジトリや設定リポジトリ、プロトタイプ段階のコードでは、この基準がそのまま合うとは限りません。REVIEW.mdに「どの種類の指摘をImportantとし、それ以外は最大でもNitとするか」を明文化します。逆方向の調整も可能で、たとえば「CLAUDE.md違反は既定のNitではなくImportant扱いにする」といった厳格化もできます。

Nit件数の上限

散文やコード整形の指摘は際限なく出せてしまいます。「1レビューにつきNitは最大5件まで、残りは件数だけ要約に書く」のようにキャップをかけると、レビューが実際に読まれる分量に収まります。

スキップ対象の指定

生成コード・lockfile・ベンダー配布の依存パッケージ・機械生成のブランチなど、指摘しても意味のない対象を明示的に除外します。lint・スペルチェックのようにCIの他の仕組みが既にカバーしている項目も対象です。完全に除外するほどではないパスには、「scripts/配下は確度が高く重大な場合のみ報告する」のように基準を上げる指定も使えます。

リポジトリ固有チェック

「新しいAPIルートには必ず統合テストを付ける」のような、そのリポジトリ特有のルールを毎回チェックしてほしい場合に書きます。REVIEW.mdは最優先指示として注入されるため、同じ内容を長いCLAUDE.mdに埋もれさせるより確実に反映されます。

検証基準の引き上げ

命名からの推測だけで指摘されるのを防ぎたい場合、「挙動に関する指摘には、ソースコード中のfile:lineによる根拠を必須とする」のように証拠のハードルを上げます。著者が指摘を確認する往復コストを削れます。

再レビュー時の収束ルール

一度レビュー済みのPRに再度レビューが走ったときの振る舞いも指定できます。「初回レビュー後は、新規のNitを抑制しImportantのみ報告する」というルールを書けば、スタイルの指摘だけで7回目のレビューまで長引くような事態を防げます。

要約の形式指定

レビュー本文の冒頭に「2 factual, 4 style」のような1行の内訳を出すよう指定できます。問題がなければ「重大な問題なし」から書き始めるよう指定すると、著者はレビュー本文を開く前に作業の見通しを立てられます。

実例テンプレート

公式ドキュメントに掲載されているバックエンドサービス向けの例を引用します。重大度を再定義し、Nitに上限をかけ、生成ファイルをスキップし、リポジトリ固有のチェックを足す構成です。

# Review instructions
 
## What Important means here
 
Reserve Important for findings that would break behavior, leak data,
or block a rollback: incorrect logic, unscoped database queries, PII
in logs or error messages, and migrations that aren't backward
compatible. Style, naming, and refactoring suggestions are Nit at
most.
 
## Cap the nits
 
Report at most five Nits per review. If you found more, say "plus N
similar items" in the summary instead of posting them inline. If
everything you found is a Nit, lead the summary with "No blocking
issues."
 
## Do not report
 
- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules
 
## Always check
 
- New API routes have an integration test
- Log lines don't include email addresses, user IDs, or request bodies
- Database queries are scoped to the caller's tenant

このテンプレートは公式ドキュメントの英語例をそのまま引いたものです。REVIEW.md自体の記述言語について公式の指定は確認できていないため、日本語のリポジトリで使う場合は、見出しと本文を日本語に訳したうえで自分のリポジトリのディレクトリ構成(src/gen/や*.lockの部分)に合わせて書き換えてください。項目を減らして実情に合わせて調整するのも有効です。

テンプレート内の4つの見出しは、7項目のうち影響が大きい4つに対応しています。「What Important means here」が重大度の再定義、「Cap the nits」がNit件数の上限、「Do not report」がスキップ対象の指定、「Always check」がリポジトリ固有チェックです。検証基準の引き上げ・再レビュー時の収束ルール・要約の形式指定はこの例には入っていません。必要になった時点で見出しを1つ足すだけで拡張できます。

REVIEW.mdは小さく始めて足していく

7項目を最初から全部書く必要はありません。優先順位を間違えると、レビュー基準が意図と外れたまま気づかないという事故につながります。

効果が出るのが早いのはスキップ対象の指定とNit件数の上限です。生成コードやlockfileへの指摘、Nitの洪水を止めるだけで、レビューは実際に読まれる分量になります。ここは基準を間違えても実害が小さく、効果もすぐに体感できます。

重大度の再定義は逆に慎重に進めます。Importantの定義を狭めすぎると、本当に危ういバグまでNit扱いに落ちてしまいます。数回分のレビュー結果を見て、実際に見逃したくない指摘の種類を確認してから書き直すのが安全です。検証基準の引き上げと再レビュー時の収束ルールは、チームがCode Reviewの運用に慣れてから足しても遅くありません。

REVIEW.mdを書くときの注意点

長さにはコストがあります。項目を足しすぎると、本当に重要なルールが埋もれて効きが弱くなります。置く場所を分けるのが基本です。プロジェクト全体の前提知識(アーキテクチャの説明、命名規則など)はCLAUDE.mdに残し、REVIEW.mdにはレビューの挙動そのものを変える指示だけを置きます。両方のファイルに同じルールを重複して書く必要はありません。REVIEW.mdが存在しない場合、Code ReviewはCLAUDE.mdだけを参照して既定の基準で動きます。

組織全体でREVIEW.mdのひな形を配布したい場合、リポジトリごとに個別管理するより、組織のポリシーとして統制する運用が向くこともあります。管理者側の統制手段はClaude Code組織管理ガイドで扱っているmanaged-settingsの考え方と共通する部分があります。CLAUDE.md側の設計パターンはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンにまとめてあるので、REVIEW.mdと役割分担して使う際の参考にしてください。REVIEW.mdはリポジトリ内の1ファイルにすぎないため、基準を変える変更自体も通常のコードと同じくPRでレビューしてから取り込めます。

まとめ

REVIEW.mdはリポジトリルートに置くだけで、Code Reviewのレビューパイプライン全体に最優先の指示として注入されます。重大度の再定義・Nit件数の上限・スキップ対象・リポジトリ固有チェック・検証基準・再レビュー時の収束ルール・要約の形式という7項目のうち、ノイズが多い、指摘が信頼できないと感じる項目から順に足していくのが実務的な進め方です。長く書きすぎず、レビューの挙動そのものを変える指示だけに絞ります。

よくある質問

REVIEW.mdはどのブランチに置けば効きますか

リポジトリルートに置いたREVIEW.mdが対象です。PRのブランチ側に置いた変更が反映されるか、デフォルトブランチのものが常に使われるかは明記されていないため、確実に反映させたい変更はデフォルトブランチ側に先に取り込んでおくと安全です。

自作ワークフローでもREVIEW.mdは読まれますか

読まれません。REVIEW.mdが効くのは管理Code Review機能だけです。自分で書いたGitHub Actionsワークフローで同じプラグインを呼ぶ場合、レビュー基準の調整はワークフロー側のプロンプトやパラメータで行う必要があります。

文字数やサイズの上限はありますか

公式には明確な上限は示されていません。ただし記述が長くなるほど本当に重要なルールが埋もれて効きが弱まるため、目安として「レビューの挙動を変える指示」だけに絞り、プロジェクトの一般的な説明はCLAUDE.md側に残す運用が推奨されています。

サブディレクトリにも部分適用できますか

できません。CLAUDE.mdはディレクトリ階層のあらゆる場所に置け、サブディレクトリのファイルはその配下だけに適用されますが、REVIEW.mdはリポジトリルートの1ファイルだけが対象です。モノレポでパッケージごとにレビュー基準を変えたい場合、現状はREVIEW.md側にパッケージ名で条件分岐する指示を書く形になります。

CLAUDE.mdと矛盾したらどうなりますか

REVIEW.mdはレビューパイプラインの全エージェントに最優先の指示として注入されるため、CLAUDE.mdとの間に矛盾があればREVIEW.md側が優先されます。同じ論点について2つのファイルに違う基準を書くと管理が煩雑になるため、レビュー基準の変更はREVIEW.mdだけに集約しておくのが安全です。

REVIEW.mdを追加した直後から基準は変わりますか

次にトリガーされるレビューから反映されます。過去に投稿済みのコメントや、既に完了したチェック実行の内容が遡って書き換わるわけではありません。基準を変えた効果を確認したい場合は、変更後に@claude reviewで新しいレビューを起動します。