REVIEW.md の書き方ガイド——Claude Code Review をチーム仕様に合わせる設定ファイルの使い方
Claude Code ReviewのREVIEW.mdとは何か、CLAUDE.mdとの違い、実際の書き方・テンプレートを公式ドキュメントベースで解説。severity制御・スキップルール・チーム固有チェックの設計方法まで。
エンジニアのゆとです。
Claude Code Reviewを使い始めると、すぐに気になるのが REVIEW.md の存在だ。「CLAUDE.mdじゃないの？」「そもそも何が違うの？」と思った人は少なくないはず。自分もそうだった。
この記事では、REVIEW.mdが何者なのかを公式ドキュメントから正確に読み解いて、実際の書き方・設計のポイントをまとめる。
先に結論を言うと、REVIEW.mdはClaude Code Reviewの公式機能だ。2026年3月にリリースされたCode Reviewの設定ファイルとして、公式ドキュメントに仕様が明示されている。「なんとなくREVIEW.mdを置いたら動いた」ではなく、設計意図を理解してから使うと、チームのレビュー品質が大きく変わる。
なお前提として、REVIEW.mdが効く「Code Review」はGitHub連携のPR自動レビュー（マネージドサービス）で、2026年6月時点ではresearch preview・Team / Enterpriseプラン向け（ZDR有効の組織は対象外）。手元のターミナルで使う /code-review コマンドとは別物なので、その区別を頭に置いて読んでほしい（詳細は後述）。
REVIEW.mdとは何か
REVIEW.mdは、Claude Code Reviewの挙動を制御するリポジトリ固有の設定ファイルだ。
公式ドキュメント（code.claude.com/docs/en/code-review）にはこう書かれている。
REVIEW.mdis a file at your repository root that overrides how Code Review behaves on your repo. Its contents are injected into the system prompt of every agent in the review pipeline as the highest-priority instruction block, taking precedence over the default review guidance.
つまり、REVIEW.mdはレビューパイプライン内のすべてのエージェントに対して、最高優先度の指示として注入される。デフォルトの挙動を上書きする。
配置場所はリポジトリのルートで、名前は REVIEW.md 固定。Claude Code Reviewが自動的に検出する。設定は不要。
重要な仕様がもう一つある。
Because it’s pasted verbatim,
REVIEW.mdis plain instructions:@import syntax is not expanded, and referenced files are not read into the prompt.
CLAUDE.mdで使える @path/to/file によるファイルインポートは、REVIEW.mdでは機能しない。ルールを直接書く必要がある。
CLAUDE.mdとどう違うのか
ここが最も混乱しやすいポイントなので、整理する。
Claude Code Reviewはリポジトリの2種類のファイルを読む。
| CLAUDE.md | REVIEW.md | |
|---|---|---|
| 読まれる場面 | すべてのClaude Codeタスク | Code Reviewのみ |
| 反映されるseverity | 違反はNit（軽微）として検出 | 最高優先度として全エージェントに注入 |
| 影響範囲 | 普段のコーディング支援・リファクタ等にも効く | レビュー時のみ |
| @importサポート | あり | なし（直接記述のみ） |
CLAUDE.mdはプロジェクト全体の指示書で、Code ReviewはそれをNitレベルの参考情報として読む。新しく導入した変更がCLAUDE.mdのルールに違反していれば、nitとして指摘される。
REVIEW.mdはコードレビュー専用の指示書で、しかも最高優先度で注入される。「重要度の定義を変えたい」「特定パスをスキップしたい」「チーム固有のチェック項目を追加したい」といった要件はREVIEW.mdに書く。
使い分けの原則はシンプルだ。
チーム全体で守るコーディング規約 → CLAUDE.md
レビュー時だけ適用したい、またはレビューの挙動を変えたい設定 → REVIEW.md
REVIEW.mdで何を制御できるか
公式ドキュメントは「フリーフォームのmarkdown」と説明している。つまり、レビューへの指示として表現できるものであれば、基本的に何でも書ける。実用的な制御パターンを整理する。
severityの再定義
デフォルトでは、コードレビューはバグや動作上の問題を🔴 Important、スタイルや軽微な問題を🟡 Nitとして分類する。
プロトタイプのリポジトリ、設定ファイルのみのリポジトリ、ドキュメントリポジトリなど、本番コードとは性質が異なるリポジトリでは、Importantの定義が厳しすぎる場合がある。REVIEW.mdでこれを調整できる。
## Importantの基準
Importantに分類するのは以下のみ:
- 実行時にクラッシュするロジックエラー
- 認証・認可のバイパスにつながる問題
- 本番データの漏洩・破損につながる問題
- ロールバックを妨げるマイグレーションの非互換
スタイル・命名・リファクタリングの提案はNit以下に留める。
CLAUDE.mdの違反はImportantではなくNitとして扱う。逆に厳しくすることもできる。セキュリティ重視のリポジトリであれば、CLAUDE.mdの違反をImportantに格上げする指示を書けばいい。
Nitの量を制限する
コードは無限に磨ける。Nitコメントが20件ついたレビューは、読む気が失せる。
## Nitの上限
1回のレビューでNitコメントは最大5件まで投稿する。
それ以上ある場合は「他にN件の同様の指摘あり」とサマリーに記述するだけにする。
Nitのみで終わる場合、サマリーの冒頭に「ブロッキングな問題はありません」と記載する。これだけで、レビューが格段に読みやすくなる。
スキップするパスと項目
生成コードやlock fileは人間もレビューしない。Claude Code Reviewも同じでいい。
## レビュー対象外
以下はコメントしない:
- `src/gen/` 配下のすべての自動生成ファイル
- `*.lock` ファイル（`package-lock.json`、`yarn.lock`、`Gemfile.lock` 等）
- `vendor/` 配下の外部依存コード
- CIがすでに強制しているlint・型チェック・フォーマットの問題
- テストコードが意図的に本番ルールに反している場合特定のパスに対してスキップ完全にするのではなく、基準を上げるという設定もできる。
## `scripts/` ディレクトリ
`scripts/` 配下のコードはほぼ確実かつ重大な問題のみ報告する。
軽微な問題は無視する。チーム固有のチェック項目を追加する
これがREVIEW.mdの一番の強みだと思っている。チームの「暗黙のルール」を明文化してレビューに組み込める。
## 必ず確認すること
- 新しいAPIエンドポイントには対応するインテグレーションテストがある
- ログにメールアドレス・ユーザーID・リクエストボディが含まれていない
- DBクエリはテナントでスコープされている（マルチテナント環境）
- マイグレーションは後方互換性があるCLAUDE.mdに同じことを書いても効果は薄い（Nitレベルとしてしか扱われない）。REVIEW.mdに書くことで、最高優先度として全エージェントに適用される。
二回目以降のレビューの収束
PRを繰り返しプッシュすると、毎回同じNitが出てくることがある。
## 再レビュー時の挙動
PRが一度レビュー済みの場合、Nitは新規追加分のみ報告する。
既に指摘したNitを繰り返し報告しない。
二回目以降はImportantな問題のみに絞る。サマリーの形式を指定する
レビューを最初に開いたとき、何が起きているかを一瞬で把握できるサマリーにしたい。
## レビューサマリーの形式
サマリーの冒頭に「重大: N件 / Nit: N件」の形式で内訳を1行で記載する。
重大な問題がない場合は「重大な問題はありません」を先頭に記載する。
詳細はその後に続ける。実際のREVIEW.md テンプレート
バックエンドAPIサービスを想定した、実用的なREVIEW.mdの例を示す。
# レビュー方針
## Important の基準
以下のみをImportantとして報告する:
- 本番環境でクラッシュするロジックバグ
- データ漏洩・PII（個人情報）のログ出力
- 認証・認可のバイパス
- 後方互換性のないDBマイグレーション
- 決済・在庫などのクリティカルな数値ロジックのエラー
スタイル・命名・リファクタリング・テストカバレッジはNit以下に留める。
## Nitの制限
1回のレビューでNitは最大5件まで投稿する。
5件を超える場合は「他にN件の同様の指摘」とサマリーに記述する。
Nitのみの場合はサマリーの冒頭に「ブロッキングな問題はありません」と記載する。
## レビュー不要
- `src/generated/` 配下の自動生成ファイル
- `*.lock` ファイル（package-lock.json 等）
- `__snapshots__/` 配下のスナップショットファイル
- CIがすでに検出するlint・型エラー
- `scripts/` 配下: ほぼ確実かつ重大な問題のみ報告する
## 必ず確認すること
- 新しいAPIルート（`src/routes/` 配下）にはインテグレーションテストがある
- ログ出力にメールアドレス・ユーザーID・リクエストボディが含まれていない
- DBクエリには `tenantId` によるスコープがある
- 外部サービスへのリクエストはタイムアウト設定がある
## サマリー形式
サマリーの冒頭: 「重大: N件 / Nit: N件」の1行。
重大な問題がない場合: 「重大な問題はありません — Nit N件」と先頭に記載。
## 再レビュー
2回目以降のレビューはImportantな問題のみ報告する。
前回のNitを繰り返し報告しない。このREVIEW.mdを置くだけで、レビューはかなりチームの実務に合ったものになる。
REVIEW.mdを書く際の注意点
長くしすぎない
公式ドキュメントにはこう書かれている。
Length has a cost: a long
REVIEW.mddilutes the rules that matter most. Keep it to instructions that change review behavior, and leave general project context inCLAUDE.md.
長いREVIEW.mdは、重要なルールを薄める。プロジェクトの一般的なコンテキストはCLAUDE.mdに任せて、REVIEW.mdはレビューの挙動を変える指示だけに絞る。
目安としては、50〜100行以内に収める意識でいい。「この行を削ったらレビューが変わるか？」を自問して、NOなら消す。
@importは使えない
繰り返しになるが、REVIEW.mdでは @path/to/file の構文は展開されない。外部ファイルを参照したくても、その内容を直接REVIEW.mdに書く必要がある。これを知らずに @ 参照を書いても、単純にテキストとして処理されるだけで期待通りに動かない。
指示は具体的に書く
「品質を重視して」「丁寧にレビューして」のような抽象的な指示はあまり意味がない。「何を報告するか・しないか」「Importantとは何か」を具体的に定義する。行動を変える指示だけが機能する。
チームで育てていく
最初から完璧なREVIEW.mdを書こうとしなくていい。まず最低限の設定だけ入れて、レビューを繰り返す中で「これは毎回Nitで出てきて邪魔だ」「このチェックは毎PR人間が目で確認している」という項目が出てきたら追加していく。
チームで共有する設定なので、Gitにコミットしてレビュー依頼を出して、全員で合意形成するプロセスが自然にできる。
よくある質問
REVIEW.mdを置かなくても動くのか？
動く。REVIEW.mdはオプションのカスタマイズファイルだ。置かなければデフォルトのレビュー動作が適用される。CLAUDE.mdも同様で、どちらも「あれば読む」もの。
REVIEW.mdはチームメンバー全員が共有するのか？
はい。リポジトリのルートに置いてGitにコミットすれば、そのリポジトリのすべてのレビューに適用される。個人設定ではなくリポジトリ設定だ。
CLAUDE.mdに書いたルールはCode ReviewでImportantとして扱われるか？
いいえ。公式ドキュメントによると、CLAUDE.mdの違反はNit（軽微）として検出される。Importantとして扱いたいなら、REVIEW.mdに明示的に書く必要がある。
REVIEW.mdはプラグイン版の /code-review コマンドでも読まれるか？
公式ドキュメントの記述から確認できる範囲では、REVIEW.mdはCode Reviewのマネージドサービス（GitHub連携のPR自動レビュー）の文脈で説明されている。ローカルの /code-review コマンドについては別の仕組みで動作する。現時点では、ローカルコマンド実行時にREVIEW.mdが読まれるかどうかは公式ドキュメントに明確な記述がない。
severityを完全に無効化できるか？
特定のクラスの指摘を「絶対に出さない」という指示はREVIEW.mdで表現できる。「この種の問題はレポートしない」と書けば、実質的に無効化できる。ただし100%保証されるものではなく、AIへの指示として機能する。
REVIEW.mdとCLAUDE.mdのどちらに書くか迷ったら？
「レビュー以外のClaude Codeセッション（コーディング支援、リファクタリング等）でも適用したいか？」で判断する。YESならCLAUDE.md、レビュー時だけでいいならREVIEW.md。重複して書いても問題ないが、管理が煩雑になる。
まとめ
REVIEW.mdは、Claude Code Reviewの挙動をリポジトリ固有にカスタマイズするための公式の設定ファイルだ。コミュニティの慣習ではなく、公式ドキュメントに仕様が明示されている（code.claude.com/docs/en/code-review）。
CLAUDE.mdとの関係を整理すると:
- CLAUDE.md: 全タスクに効く。Code ReviewではNit参考情報として読まれる
- REVIEW.md: Code Reviewのみに効く。最高優先度で全エージェントに注入される
REVIEW.mdで何を制御するかを簡単にまとめると:
- Importantの定義をプロジェクトの性質に合わせて再定義する
- Nitの量を制限して読みやすくする
- 生成コード・lockファイル・CI管理済みの問題はスキップする
- チーム固有のチェック項目（API統合テスト必須など）を最高優先度で入れる
最初は数十行の最小限の設定から始めて、レビューを繰り返しながら育てていくのが現実的なアプローチだ。
コードレビューの文脈でClaude Codeをもう少し深掘りしたい場合は、マルチエージェント構成の詳細やプラグイン版の使い方も記事にしているので、あわせて読んでもらえると全体像がつかめる。
