Code Review をカスタマイズする

REVIEW.md と CLAUDE.md を使って、Code Review がプルリクエストで指摘する内容を調整します。重大度の再調整、パスのスキップ、チェックの追加、そしてどのコピーが適用されるかを確認する方法を説明します。

リポジトリに指示をコミットすることで、Code Review がそのリポジトリで指摘する内容を変更できます。これにより、nit の量を減らしたり、生成されたファイルへのコメントを止めたり、チームが重視するルールを追加したりできます。指示は次の 2 つのファイルのいずれかに記述します。

• CLAUDE.md：Claude Code がレビューを含むすべてのタスクで読み込むプロジェクト指示です。Code Review はこれをプロジェクトのコンテキストとして読み込み、これに違反する変更を指摘します。
• REVIEW.md：レビュー専用の指示です。チームが何を指摘してほしいか、どの重大度で指摘するか、何をスキップするかを記述するために使用します。

リポジトリのルートに REVIEW.md を追加してマージします。その後、デフォルトブランチを保護します。

[!NOTE]

レビューの徹底度や実行タイミングを変更するには、Owner にレビューレベルまたは Review runs 設定の変更を依頼してください。

プロジェクト全体のルールには CLAUDE.md を使用する

Code Review は、リポジトリの CLAUDE.md ファイルをプロジェクトのコンテキストとして読み込みます。そのルールのいずれかに違反する変更は、問題に応じた重大度レベルの検出結果になります。

レビューでは、リポジトリのルートにある CLAUDE.md と、変更された各ファイルの親ディレクトリにある CLAUDE.md ファイルが読み込まれます。サブディレクトリの CLAUDE.md は、プルリクエストがそのパス配下のファイルを変更した場合に読み込まれます。

レビュー専用のルールには REVIEW.md を使用する

REVIEW.md は、Code Review をリポジトリに合わせて調整するための、リポジトリのルートに置くファイルです。サブディレクトリに REVIEW.md を追加して、ルートのファイルに加えて、そのパス配下の変更に対するチェックを追加することもできます。

問題を検出するエージェントと、それを検証するエージェントは、Code Review のデフォルトのレビューガイダンスとともに、このファイルの内容をリポジトリのレビュー指示として受け取ります。最終的なレビューを書き出すステップでは、重大度を確定してサマリーを書く前にこのファイルを参照します。

次のレイアウト例には、ルートのファイルとサブディレクトリのファイルが 1 つずつあります。

your-repo/
├── REVIEW.md            # Root file
├── services/
│   └── billing/
│       └── REVIEW.md    # Adds checks for changes under services/billing/
└── src/

サブディレクトリのファイルに頼る前に、デフォルトブランチを保護し、ブランチ構成に応じてレビューが何を読み込むかを確認してください。

[!NOTE]

Code Review サービスとローカルの /code-review コマンドは別々のツールであり、読み込むファイルが異なります。サービスは CLAUDE.md と REVIEW.md の両方を読み込みます。自分のマシン上の Claude Code セッション内で実行する /code-review コマンドは、CLAUDE.md ファイルを読み込みますが、REVIEW.md は読み込みません。両方で適用したいガイダンスは CLAUDE.md に記述し、REVIEW.md はプルリクエストのレビューに固有のルールのために使用してください。

REVIEW.md の例

この REVIEW.md は、バックエンドサービス向けに重大度を再調整し、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.

## 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 に何を書くかを決める

REVIEW.md は自由形式の Markdown で、レビューが何を検出して報告するかを変更します。レビューの形式は変更しません。発生している問題を見つけ、示されているような指示を追加してください。例では最初の 4 つを使用しています。

• 間違ったものが Important としてマークされる：リポジトリにおける 🔴 Important の意味を再定義します。デフォルトの調整は本番コードを対象としており、ドキュメントリポジトリ、設定リポジトリ、プロトタイプではもっと狭い定義が望ましい場合があります。どの種類の検出結果が Important で、どれがせいぜい Nit なのかを明記してください。重大度を引き上げることもでき、たとえば CLAUDE.md への違反をすべて Important として扱うこともできます。
• nit が多すぎる：1 回のレビューで投稿される 🟡 Nit コメントの数に上限を設けます。「nit は最大 5 件まで報告する」のような上限により、レビューを対応可能な内容に保てます。
• 生成されたファイルや CI がすでにチェックしている内容へのコメント：Claude が検出結果をスキップすべきパスと検出結果のカテゴリを列挙します。よくある候補は、生成コード、ロックファイル、vendor された依存関係、そして lint やスペルチェックなど CI がすでに強制しているものです。ある程度のレビューを必要とするものの、徹底的な精査までは不要なパスについては、代わりに基準を引き上げます。たとえば「scripts/ では、ほぼ確実かつ重大な場合にのみ報告する」とします。
• チームのルールがチェックされていない：「新しい API ルートには統合テストが必要」のように、すべてのプルリクエストで指摘してほしいルールを追加します。
• 誤っていることが判明する検出結果：ある種類の検出結果を投稿する前に根拠を求めます。たとえば「動作に関する主張には、命名からの推測ではなく、ソース内の file:line の引用が必要」とすることで、作成者に余計なやり取りを強いる誤検出を減らせます。

これらの指示の一部は、保護されたデフォルトブランチ上のルートファイルを必要とします。

REVIEW.md にはレビューの動作を変える指示だけを記述し、一般的なプロジェクトのコンテキストは CLAUDE.md に残してください。

REVIEW.md に他のファイルを取り込む

レビュー指示を複数のファイルに分割し、それらをルートの REVIEW.md に取り込むことができます。REVIEW.md が長くなった場合や、すでに別のファイルでレビュールールを管理している場合に使用してください。

ファイルを取り込むには、ルートの REVIEW.md に @ とファイル名だけを記述した行を追加します。Code Review はその行をファイルの内容で置き換えるため、内容は REVIEW.md の一部として適用されます。この例では、ルートのファイルが独自の指示を 1 つ記述し、その後に 2 つのルールファイルを取り込んでいます。

# Review instructions

Report at most five Nits per review.

@review-security.md
@review-api.md

取り込むファイルは、リポジトリのルートに REVIEW.md と並べて保存します。

your-repo/
├── REVIEW.md
├── review-security.md
└── review-api.md

Code Review は保護されたブランチから REVIEW.md を読み込む場合にファイルを取り込むため、リポジトリでレビューがどのブランチを読み込むかを確認してください。

• 保護されたブランチ：Code Review は @ 行を取り込むファイルで置き換えます
• 保護されていないデフォルトブランチ：@ 行はプレーンテキストとして REVIEW.md に残ります。プルリクエストがその行で指定されたファイルを変更している場合、その行は除外されます。

レビューで取り込んだファイルが適用されない場合は、次の各項目を確認してください。

• 場所：ファイルをリポジトリのルートに移動します。スキルファイルを除き、@docs/review-rules.md のようなサブディレクトリ内へのパスは取り込まれません。
• 名前：大文字と小文字を含めてファイル名を正確に一致させ、スペースを含まない名前を使用します。REVIEW.md と同じ場所にあるどのファイルとも名前が一致しない行は、プレーンテキストとして REVIEW.md に残り、チェック実行ではスキップされた取り込みとして報告されません。
• 1 階層のみ：すべてのファイルをルートの REVIEW.md に列挙します。取り込まれたファイル内やサブディレクトリの REVIEW.md 内の @ 行はプレーンテキストのまま残り（スキルファイルは異なります）、別のファイルへの Markdown リンクは取り込みになりません。
• 上限：取り込むファイルは異なるファイルで最大 8 つまでとし、REVIEW.md とそれが取り込むファイルの合計を 150,000 バイト未満に保ちます。バイト数の上限に達するファイルは、途中で切り詰められるのではなく、ファイル全体がスキップされます。チェック実行では、いずれかの上限によってスキップされた取り込み行の数が報告されます。
• リンク：REVIEW.md とそれが取り込むファイル全体で、Markdown リンクを 64 個以下に保ちます。http、https、mailto アドレスへのリンクと # アンカーへのリンクは数に含まれず、スキルファイル内のリンクも含まれません。この上限を超えると、レビューは取り込まれたファイルだけでなく、ルートの REVIEW.md 全体をスキップします。その場合、チェック実行では指示が適用されなかったことが示されます。
• マージ済みのコピー：取り込むファイルを REVIEW.md が読み込まれるブランチにマージします。レビューは両方を同じコミットから読み込み、プルリクエスト自体の変更から読み込むことはありません。

スキルファイルを取り込む

スキルで管理しているガイダンスにレビューを従わせるには、スキルの SKILL.md をルートの REVIEW.md に取り込みます。Code Review はスキルを実行しません。

@ と SKILL.md へのパスを .claude/skills/<folder>/SKILL.md の形式で、単独の行に追加します。

# Review instructions

Report at most five Nits per review.

@.claude/skills/api-review/SKILL.md

Treat any change under `migrations/` as Important.

Code Review は保護されたブランチから REVIEW.md を読み込む場合にのみスキルファイルを取り込むため、REVIEW.md が読み込まれるブランチを保護してください。スキルファイルは 8 ファイルおよび 150,000 バイトの上限の対象となり、さらに独自の上限として 30,000 バイトがあります。

Code Review が取り込むスキル行を書く

スペースを含まないフォルダー名を使用します。パスにスペースを含む行はプレーンテキストとして REVIEW.md に残り、チェック実行ではスキップされた取り込みとして報告されません。

スキルの @ 行が次のいずれかのルールに違反している場合、Code Review はその行からスキルを取り込みません。

• パス：パスはリポジトリのルートからの .claude/skills/<folder>/SKILL.md として記述し、スキルのフォルダーを skills/ の直下に置きます。ルートにあるファイル名とは異なり、この形式のパスでどのファイルとも一致しないものはスキップされ、カウントされます。
• ソース：.claude/ 配下のその他のファイルや、バンドル、個人、またはプラグインのスキルからのガイダンスは、REVIEW.md と並ぶファイルにコピーします。これらを直接取り込むことはできません。
• ファイル：SKILL.md は通常のテキストファイルとしてコミットします。Code Review はシンボリックリンクをたどりません。リンクがファイル自体であっても、パス内のフォルダーであっても同様です。
• サイズ：SKILL.md はフロントマターを含めて 30,000 バイト以下に保ちます
• 数：スキル行は最大 8 つまでとします。繰り返された行も、8 つのうちに改めてカウントされます。
• REVIEW.md 内のブロック：@ 行をコードフェンスの外に置きます。その行より上にあるすべての HTML コメントと、すべての <pre>、<script>、<style>、<textarea> ブロックを閉じてください。

Code Review がファイル、サイズ、数、またはブロックのルールへの違反によってスキル行をスキップした場合、その行はチェック実行のスキップされた取り込み行に関するメッセージでカウントされます。このメッセージは、レビューが保護されたブランチの REVIEW.md を適用する場合にのみ表示されます。

レビューがスキルから受け取る内容を確認する

スキルが取り込まれると、レビューはスキルから SKILL.md の本文だけを受け取ります。そのため、次のリストに照らしてスキルを確認してください。

• フロントマター：レビューがフロントマターから必要とする内容、たとえばスキルを使用する条件として description に記述されている内容を、本文にも繰り返し記述します
• 挿入されるコマンド：! コマンドが提供する内容を書き出します。Code Review はコマンドを実行せず、コマンドを含む行またはブロック全体をプレースホルダーに置き換えます。
• 置換：$ARGUMENTS やその他の置換を固定テキストに置き換えます。レビューは引数を渡さず、それらを記述されたまま残すためです
• サポートファイル：レビューに必要な内容を SKILL.md にコピーします。Code Review はスクリプト、リンクされたファイル、@file 参照を読み込まないためです
• 除外と Nit の上限：検出結果を除外する指示や Nit に上限を設ける指示は、スキルではなく、REVIEW.md またはそれと並ぶファイルに記述します。Code Review は、スキルのテキストをそのどちらの根拠としても受け入れません。
• リポジトリのファイルへのリンク：リンクや @file 参照が何を指しているかを言葉で説明します。レビューではパスがプレーンテキストまたはプレースホルダーとして表示されます。

スキルの ! コマンド、$ARGUMENTS、またはリンクを編集すると、Claude Code でのスキルの動作も変わります。チームがそれらに依存している場合は、ガイダンスを REVIEW.md と並ぶファイルにコピーし、スキルの代わりにそのファイルを取り込んでください。

Code Review がスキルのテキスト内で変更する文字

Code Review はスキルのテキスト内の一部の文字を変更するため、コードサンプルは次のような形でレビューに渡されます。

In SKILL.md:       Use `items[0]`, never `List<String>`.
The review reads:  Use ˋitems(0)ˋ, never ˋList< String>ˋ.

In SKILL.md:       Run `ps | grep api` and ask @alice.
The review reads:  Run ˋps ¦ grep apiˋ and ask @ alice.

ルールがこれらの文字のいずれかに依存する場合は、その内容を言葉でも説明してください。

REVIEW.md がどのブランチから読み込まれるか

Code Review は、REVIEW.md をプルリクエストのベースブランチまたはデフォルトブランチから読み込み、プルリクエスト自体の変更から読み込むことはありません。レビューの動作を変更するには、まず REVIEW.md の変更をマージしてください。

REVIEW.md はデフォルトブランチに置き、そのブランチを保護してください。レビューが保護されたデフォルトブランチ上のコピー（下の表の 1 行目）を読み込む場合、ルートファイルにある次の指示が適用されます。

• 検出結果の重大度を下げる
• パス、ファイル、または問題の種類を除外する
• nit コメントの数に上限を設ける

除外と Nit の上限は、取り込まれたスキルではなく、REVIEW.md またはそれと並ぶファイルに記述してください。

ブランチ保護とみなされるもの

Code Review は、次の設定を保護とみなします。

• デフォルトブランチ：クラシックなブランチ保護ルールまたはルールセット
• その他のブランチ：ルールセットのみ

ルールセットは、更新を制限している場合、または少なくとも 1 件の承認を伴うプルリクエストを必須にしている場合に保護とみなされます。プルリクエストを必須にしている場合は、新しいプッシュ時にその承認を取り消すか、最後のプッシュ以降の承認を必須にする必要もあります。

ブランチ構成ごとにレビューが読み込むもの

下の表の 1 列目から、リポジトリの状況に該当するものを見つけてください。

チェック実行で REVIEW.md について言及されている場合は、The check run mentions REVIEW.md を参照してください。

関連リソース

• Code Review：サービスの概要とレビューの実行方法
• プルリクエストでレビューを確認・依頼する：各重大度レベルの意味と検出結果の表示方法
• Code Review をセットアップする：Owner が設定するレビューレベルとレビューの実行タイミング
• /code-review でローカルにレビューする：/code-review コマンド、その引数、effort レベル
• メモリ：Claude Code 全体で CLAUDE.md ファイルがどのように機能するか