REVIEW.mdの@行でファイルを取り込み、レビュー基準を分割する手順

REVIEW.mdが長くなったら、ルートのREVIEW.mdに@review-security.mdのような行を1本書くだけで、別ファイルの中身をレビュー指示として取り込めます。Code Reviewは、その行を指定ファイルの内容に置き換えて読みます。ただし取り込みが効くのは、保護されたブランチからREVIEW.mdを読むときだけです。ファイル数・サイズ・リンク数にも上限があります。本稿は書き方、上限、効かないときの切り分けの順に説明します。

@行の書き方は「@とファイル名だけの行」

取り込みたいファイルは、ルートのREVIEW.mdに@とファイル名だけを書いた行で指定します。Code Reviewはその行を、ファイルの内容に置き換えます。取り込まれた内容はREVIEW.mdの一部として働きます。

次の例では、ルートの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

分割が向くのは、REVIEW.mdが長くなったときと、レビュー用のルールをすでに別ファイルで持っているときです。セキュリティ、API設計、データベースのように担当が分かれる領域ごとにファイルを切ると、変更の持ち主がはっきりします。

取り込みには条件と上限がある

取り込みは無条件には効きません。どのブランチからREVIEW.mdを読むかで挙動が分かれます。

どのブランチが「保護」と数えられるかは、次のとおりです。

• デフォルトブランチ: 従来のブランチ保護ルールか、ルールセット
• それ以外のブランチ: ルールセットのみ

ルールセットが保護と数えられるのは、更新を制限しているか、承認が1件以上のPRを必須にしているときです。PRを必須にする場合は、新しいpushで承認を取り消すか、最後のpushより後の承認を求める設定も要ります。

読まれるブランチと対象ファイルは、設定ごとに次の表のとおりです。

三行目の状況が見落とされがちです。取り込み用のファイルを丁寧に用意しても、ブランチが未保護なら、レビューはルートのREVIEW.mdしか読みません。

数の上限は3つ

@行を増やしていくと、次の3つの上限にぶつかります。

上限を超えたときの挙動は、ファイル数・バイト数とリンク数で違います。

• ファイル数・バイト数: 上限に達するファイルは、途中で切られず丸ごと読み飛ばされます。チェックランが、読み飛ばした取り込み行の数を報告します。
• リンク数: 64個を超えると、取り込み先だけでなくルートのREVIEW.md全体が読み飛ばされます。チェックランが、指示が適用されなかったと伝えます。

リンクの上限は、取り込みの数ではなくREVIEW.md全体の問題です。取り込み先に参考資料へのリンクを大量に貼ると、本体まで巻き添えになります。

取り込みが効かないときの切り分け

取り込み先が適用されないときの原因は、次のいずれかです。上から順に当てると絞り込めます。

最後の点は、運用でつまずきやすい箇所です。REVIEW.mdの変更と取り込み先の新規ファイルを同じPRで出すと、そのPRのレビューには効きません。基準を変えるPRは、先にマージしてから効き目を見ます。

取り込み先に別ファイルへのリンクを書くとき

Markdownリンクは、取り込みの代わりにはなりません。別ファイルへのリンクを書いても、その中身は取り込まれません。また、PRが変更するファイルやフォルダへのリンクを含むと、レビューが「リンク行だけを除く」ことができず、ルートのREVIEW.mdを丸ごと読み飛ばす場合があります。この場合は、ルールをリンクで済ませず、REVIEW.mdか取り込み先の本文に直接書きます。

チェックランに出るメッセージと対処は、次のとおりです。

スキルのSKILL.mdも取り込める

レビューに使いたい指針をすでにスキルで持っているなら、そのスキルのSKILL.mdをルートのREVIEW.mdに取り込めます。Code Reviewはスキルを実行しません。取り込むのはSKILL.mdの本文です。

書き方は、@の後に.claude/skills/<folder>/SKILL.mdの形のパスを1行で書きます。

# Review instructions
 
Report at most five Nits per review.
 
@.claude/skills/api-review/SKILL.md
 
Treat any change under `migrations/` as Important.

ここでは、通常のファイルと違い、サブディレクトリのパスが使えます。ただし取り込まれるのは、保護ブランチからREVIEW.mdを読むときだけです。スキルファイルも、8ファイル・150,000バイトの上限に数えられます。そのうえで、スキルファイルには30,000バイトの独自の上限があります。

スキル行が取り込まれない条件

次のどれかに当たると、その行からスキルは取り込まれません。

パスの形に合うのにファイルが無い行と、ファイル・サイズ・行数・ブロックの条件に反した行は、チェックランの「読み飛ばした取り込み行」に数えられます。このメッセージが出るのは、保護ブランチからREVIEW.mdを読んだときだけです。空白を含む行は数えられません。

レビューが受け取るのは本文だけ

スキルを取り込むと、レビューはSKILL.mdの本文だけを受け取ります。Claude Codeでスキルとして使うときとは、働き方が違います。スキルを転用するときは、次の点を本文に書き直します。

---
description: APIの変更をレビューするとき使う
---
Check $ARGUMENTS against the schema.

APIのスキーマ変更をレビューするときに適用する。
 
Check the changed endpoints against the schema.

書き換えで見る点は次の6つです。

スキルの!コマンド、$ARGUMENTS、リンクを書き換えると、Claude Codeでのスキルの働き方も変わります。チームがそれらに頼っているなら、スキルを取り込まず、指針をREVIEW.mdの隣のファイルへ写して、そのファイルを取り込みます。

コード片の文字が置き換わる

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.

バッククォート、角括弧、山括弧、パイプ、メンション記号が置き換わります。ルールの意味がこうした文字に依存するときは、文字だけに頼らず、言葉でも書いておきます。

分割の設計は「呼び出される場所」から決める

ここまでの条件を踏まえると、ファイルの切り方は「誰がそのルールを直すか」に合わせるのが素直です。セキュリティはセキュリティ担当、APIはAPI担当というように、CODEOWNERSで持ち主が分かれている領域の単位でファイルを切ると、ルールの変更依頼が持ち主に届きます。領域が8を超えそうなら、持ち主が同じ領域を1ファイルにまとめます。

もう1つは運用の順番です。取り込み先のファイルを足すPRは、それ自身のレビューには効きません。新しい領域のファイルを足すPRと、それを使う@行を加えるPRを分け、先にファイル側をマージしておくと、次のPRから取り込みが働いているかをチェックランで確かめられます。

保護ブランチの設定は、リポジトリごとに1回の作業です。GitHub側の設定とレビュー全体の運用はClaude CodeでGitHub PR自動レビューを設定・運用するに、チームでの基準づくりはClaude Codeチーム導入ガイドにあります。取り込むスキルの書き方はClaude Code SkillsのSKILL.mdの書き方が参考になります。

よくある質問

手元の/code-reviewコマンドでも@行は取り込まれますか

REVIEW.mdそのものが読まれません。/code-reviewコマンドが読むのはCLAUDE.mdで、REVIEW.mdは読みません。ローカルでも効かせたいルールはCLAUDE.mdに書きます。