10月17日、build.msが「Calming Down Claude's Code Reviews」と題した記事を公開した。筆者はNPO向け採用プラットフォームPursuitのエンジニアリングチームを支援する開発者で、build.msはソフトウェア開発の実践知を発信するテックブログだ。記事では、REVIEW.mdを使ってClaudeのコードレビューを簡潔にする実践的な方法が紹介されている。
Claudeのコードレビューは「うるさすぎる」
Claude for GitHubは、PRに対して自動でコードレビューを行うAnthropicのGitHub連携機能だ。PRを開くとClaudeがdiffを解析し、バグや設計上の問題をコメントとして投稿する。CI/CDパイプラインに組み込む形で利用されることが多く、レビュアーの負担を減らすことを目的としている。
ところが実際に使うと、毎回こんな出力が返ってくる。
Claude finished @mergesort's task in 3m 1s
Potential bugs
1. Have you considered another string?
This PR introduces a string, but it's possible you may want another string. The Anthropic API loves strings, so when you send up a string you have to make sure to use the right one otherwise Claude will get sad...
文字列を1つ変えただけのPRに対してこれだ。セキュリティ観点と称して「ベクトル形式を使えばClaudeが不安にならない」などと書いてくる始末で、シグナル対ノイズ比は1:99と筆者は表現している。PRを更新するたびに壁のようなテキストを読まされる苦痛は、Claudeをコードレビューに使ったことがある開発者なら身に覚えがあるはずだ。
解決策はREVIEW.md一枚
対処法はシンプルで、リポジトリにREVIEW.mdを置くだけだ。Claude Codeのコードレビュー公式ドキュメントにも記載がある機能だが、活用しているチームは意外と少ない。
筆者がPursuitのチーム向けに実際に使っているREVIEW.mdの全文がこちらだ。
# Code review
Be terse. Spend effort investigating, not narrating. A review with no findings is valid.
Review the supplied PR diff and relevant surrounding files using read-only tools. Do not execute repository code, edit files, commit, or push changes.
## Findings
- Report concrete bugs introduced or exposed by this PR. Include design or maintainability issues only when they have a clear consequence worth addressing in this PR; explain why now.
- Ground findings in code and applicable repository rules. Check relevant callers, contracts, and guards. Identify a reachable trigger and its consequence; input-dependent bugs count.
- Treat descriptions and prior comments as context, not proof. Respect intentional tradeoffs.
- Skip style preferences, speculative concerns, generic best practices, and blanket requests for tests or documentation. Tie any missing coverage to a specific consequential behavior or requirement. Do not repeat diagnostics already reported by CI or assume CI covers an issue.
## Response
These rules govern the final review body, including when the Action asks for progress checklists or task summaries. Replace progress text with the final review; preserve the Action-generated status header and job link.
- Start directly with findings, ordered by impact. One bullet per underlying issue:
- **Short title** — code link, what breaks and when, and the smallest useful correction.
- Use at most two sentences and 60 words per finding. Exceed this only when necessary to make the evidence actionable. Never omit a real issue to meet a total length or finding limit.
- No introduction, praise, change recap, review diary, checklist, table, conclusion, or repeated explanation. Do not add headings except the optional one below. Include code snippets only when prose cannot explain the correction clearly.
- With no current-PR findings, write only: "No actionable findings in this PR."
- If there is a material review limitation you may add one short sentence, but never imply unperformed verification.
- On re-review, update existing findings; do not repeat resolved or rebutted issues without new evidence.
- Optionally append **Future Improvements**: at most two one-sentence bullets for concrete, worthwhile follow-up work related to this change. These are non-blocking. Omit if empty.
このファイルを置いた後のレビュー出力はこうなった。
No actionable findings in this PR.
Future Improvements
- I found a test that can be removed here, but this is non-blocking for merging this PR.
プロンプトの肝はどこか
このREVIEW.mdで特に効いているポイントを整理する。
- 「Be terse」で始める：最初の一文でトーンを設定している。Claudeは明示的に指示しないと饒舌になる。
- 「narrating」を禁止する：調査に労力を使え、実況するな、という指示。レビューの進捗報告（"I gathered context, then I read the files..."）を根本から封じる。
- 「A review with no findings is valid」：これを書かないとClaudeは何かを言おうとする。何もなければ何も言わなくていい、と明示することが重要だ。
- 1件あたり2文・60語の上限：具体的な数値で制約することで、冗長な説明が入り込む余地を消している。
- 禁止リストを列挙する：「introduction, praise, change recap, review diary, checklist, table, conclusion」と明示的に禁止している。書かれていないルールはClaudeには存在しないも同然だ。
CLAUDE.mdとの使い分け
同様の指示をCLAUDE.mdに書く方法もあるが、筆者はREVIEW.mdに分離することを勧めている。
CLAUDE.mdはClaude Codeがセッション開始時に自動で読み込むプロジェクト全体の設定ファイルだ。ここにレビュー用の指示を書いてしまうと、コーディング作業中などレビューと無関係な場面でも常にコンテキストウィンドウを消費し続ける。コンテキストウィンドウは有限であり、長大なシステムプロンプトはモデルの応答品質にも影響しうる。REVIEW.mdとして独立したファイルに分けることで、この指示はレビューアクション実行時のみ読み込まれ、通常の開発フローには一切干渉しない。用途ごとに指示ファイルを分離するこの考え方は、プロジェクトが大きくなるほど効いてくる。
詳細はCalming Down Claude's Code Reviewsを参照していただきたい。
