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

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

REVIEW.mdはCLAUDE.mdと何が違うのか

REVIEW.mdはリポジトリルートに置く素のMarkdownです。Code Reviewは複数のエージェントが役割分担して動き、PRの差分と周辺コードから指摘の候補を探す担当、候補が実際のコードの挙動と合うかを確かめる担当、重大度を決めて結果を書く担当に分かれます。REVIEW.mdの中身は、指摘を探す担当と確かめる担当にレビュー指示として渡されます。重大度を決めて書く担当は、確定の前にこのファイルを参照します。

Code Reviewが読むファイルはもう1つあり、CLAUDE.mdです。2つは影響の強さと役割が違います。

REVIEW.mdは指摘を探す担当と確かめる担当へ直接届くため、同じルールを長いCLAUDE.mdに書くより確実に反映されます。両ファイルの効き方の違いとチーム全体への導入手順はClaude Codeチーム導入ガイドに、GitHub App自体のセットアップと指摘の見え方はClaude CodeでGitHub PR自動レビューを設定・運用するにあります。

症状から選ぶ、調整できる7項目

REVIEW.mdはフリーフォームのMarkdownなので、レビューへの指示として書けることは何でも対象になります。実務で効果が大きい7項目を、レビューを読んで感じる症状の側から並べます。

重大度の再定義

既定の🔴 Importantは本番コードを想定した基準です。ドキュメントリポジトリや設定リポジトリ、プロトタイプ段階のコードでは、この基準がそのまま合うとは限りません。REVIEW.mdに「どの種類の指摘をImportantとし、それ以外は最大でもNitとするか」を明文化します。

逆方向の調整も可能で、たとえば「CLAUDE.md違反は既定のNitではなくImportant扱いにする」といった厳格化もできます。なお、Code Reviewの重大度には、このPRで入ったのではない既存のバグを示す🟣 Pre-existingもあります。実例テンプレートはこの区分に触れていないので、既存バグの報告が邪魔なら、その扱いも自分で書き足す必要があります。

Nit件数の上限

散文や設定ファイルは、いくらでも磨き続けられてしまいます。「1レビューにつきNitは最大5件まで、残りは件数だけ要約に書く」のようにキャップをかけると、レビューが実際に読まれる分量に収まります。

スキップ対象の指定

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

リポジトリ固有チェック

「新しいAPIルートには必ず統合テストを付ける」のような、そのリポジトリ特有のルールを毎回チェックしてほしい場合に書きます。テストの有無やログの書き方のように、レビューでだけ確かめたい項目が向いています。

検証基準の引き上げ

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

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

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

ただしこのルールは、今後投稿される新規指摘の量を絞るだけです。すでに出ている指摘が消えるわけではありません。コード修正なしに指摘を閉じるにはスレッドの解消が要り、返信では閉じられません。詳しくはClaude Code Reviewの指摘は解消しないと再カウントされるで扱っています。

要約の形式指定

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

実例テンプレート

公式ドキュメントに掲載されているバックエンドサービス向けの例を引用します。重大度を再定義し、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」がリポジトリ固有チェックです。残りの3項目は例に入っていませんが、必要になった時点で見出しを1つ足せば拡張できます。

書いた効果はどう確かめるか

REVIEW.mdはリポジトリ内のファイルなので、基準を変える変更自体も通常のコードと同じくPRでレビューしてから取り込めます。取り込んだ後の効き目は、感触ではなく数で見られます。Code Reviewは、CIのチェックと並ぶ「Claude Code Review」というチェックランを残すからです。

チェックランの詳細には、指摘が重大度順に並んだ表と、機械が読める重大度の内訳があります。内訳はチェックランIDを指定してghで取り出せます。OWNER・REPOは自分の値に置き換えます。IDは、コミットのチェックランを一覧して調べます。

gh api repos/OWNER/REPO/commits/<commit-sha>/check-runs \
  --jq '.check_runs[] | {id, name}'

一覧のうち名前がClaude Code ReviewのもののidをCHECK_RUN_IDに入れて、内訳を取り出します。

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

返るのは{"normal": 2, "nit": 1, "pre_existing": 0}のようなJSONで、normalがImportantの件数、nitがNitの件数です。REVIEW.mdの変更前後で同じ種類のPRを比べれば、Nitの上限が効いたか、Importantが極端に減っていないかを確認できます。チェックランは常に中立の結論で完了するので、マージを止める働きはありません。指摘の件数でマージを止めたい場合は、この出力を自分のCIで読む設計になります。

Code Reviewの各コメントには👍と👎が最初から付いていて、ワンクリックで評価できます。この反応数はPRのマージ後に集計され、レビュアーの調整に使われます。反応は再レビューを起こさず、PRの内容も変えません。REVIEW.mdで直しきれないノイズは、👎で残す使い道があります。

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

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

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

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

長くしすぎない・置き場所を間違えない

公式は「長さにはコストがある」と明記しています。長いREVIEW.mdは、本当に重要なルールを薄めてしまいます。プロジェクト全体の前提知識(アーキテクチャの説明、命名規則など)はCLAUDE.mdに残し、REVIEW.mdにはレビューの挙動そのものを変える指示だけを置きます。CLAUDE.md側の設計パターンはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンにまとめてあります。

組織全体で基準を揃えたい場合の管理者側の統制手段は、Claude Code組織管理ガイドのmanaged-settingsが扱っています。REVIEW.mdがリポジトリごとのファイルである点は変わりません。

REVIEW.mdを書いたのにレビューが来ないとき

Code ReviewはTeamとEnterpriseの契約で使えるリサーチプレビューで、ゼロデータ保持を有効にした組織では使えません。REVIEW.mdを整えたのにレビューが来ないときは、基準ではなく起動条件の側を疑うほうが早く済みます。

手動のコメントコマンド(@claude review)は、下書き(ドラフト)のPRでも動きます。対象はopenのPRで、コメントはトップレベルに書きます。インライン返信では動きません。

組織のメンバーシップが非公開だと、書き込み権限があってもレビューは始まらず、👀の反応だけが付きます。リポジトリにcollaboratorとして直接追加されていれば始まります。メンバーシップを公開にするか、管理者にcollaborator追加を頼めば解決します。

フォークからのPRは、リポジトリの設定にかかわらず自動ではレビューされません。@claude reviewのコメントが必要です。

レビューは平均20分ほどで完了します。費用は1回あたり平均15〜25ドルで、PRの大きさと複雑さに応じて増えます。利用クレジットで別に課金されます。

まとめ

REVIEW.mdは、レビューの挙動だけを変えるための、CLAUDE.mdとは別のファイルです。ノイズが多い、指摘が信頼できないと感じたら、その症状に対応する項目を1つ足し、チェックランの件数で効いたかを確かめてから次に進む、という順で育てられます。

よくある質問

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

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

手元の/code-reviewコマンドでもREVIEW.mdは読まれますか

読まれません。ローカルの/code-reviewコマンドはCLAUDE.mdをClaude Codeの通常セッションと同じように読みますが、REVIEW.mdは読まない仕様です。REVIEW.mdはGitHub上のCode Review(管理サービス)向けのファイルです。ローカルでの確認はREVIEW.mdの効果を見る手段にならないため、確かめるにはPRで実際にレビューを走らせます。

サブディレクトリにも置けますか

公式はREVIEW.mdをリポジトリルートのファイルとして説明しています。サブディレクトリのREVIEW.mdに触れた記述は見当たりません。一方のCLAUDE.mdは、サブディレクトリのものがその配下のファイルにだけ効くと明記されています。パッケージごとに基準を変えたい場合の書き方は公式に例がないので、まずルートのREVIEW.mdでパスを名指しして指示する形から試すことになります。

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

公式は具体的な上限を示していません。示しているのは、長さにはコストがあり、長いと重要なルールが薄まるという点までです。