Claude CodeのReportFindingsツール — レビュー指摘を一覧で描画する
ReportFindingsは、コードレビューの指摘をファイル・要約・失敗シナリオの構造化リストで返す組み込みツールです。呼ばれる条件、categoryスラッグ、自作レビューskillへの組み込み方をまとめます。
Claude CodeのReportFindingsツール — レビュー指摘を一覧で描画する
ReportFindingsは、コードレビューの指摘を構造化リストとして返す組み込みツールです。1件の指摘に、ファイル、要約、失敗シナリオの3項目を持たせます。テキストで書き流す代わりに、Claude Codeがそのリストを一覧として描画します。v2.1.196以降で使えます。
普段のターミナル操作では、このツールの出番はほとんどありません。呼ばれる条件が限られているためです。この記事では、その条件と、指摘に付くcategoryスラッグ、自作のレビューskillに組み込むときの考え方を扱います。
ReportFindingsは何を返すツールか
ツールリファレンスの説明は、次の内容です。
- コードレビューの指摘を構造化リストとして報告する
- 指摘ごとに、ファイル、要約、失敗シナリオを持つ
- テキストとして出力する代わりに、Claude Codeが描画できるようにする
- 権限確認は不要(Permission requiredが
No)
つまり、レビューの出力を「読み物」ではなく「データ」に変えるためのツールです。失敗シナリオは、その指摘が具体的にどんな入力や状態で壊れるのかを書く欄にあたります。
ツールを使うかどうかはClaudeが決めます。ユーザーがReportFindingsと打って呼び出すコマンドではありません。
v2.1.199で加わったcategoryスラッグ
v2.1.199から、指摘にはオプションのcategoryスラッグを付けられます。例としてcorrectnessとtest-coverageが挙がっています。描画されるリストでは、ファイルの位置の横にこのスラッグが表示されます。
公式に列挙されているスラッグの全一覧はありません。挙がっているのは上の2つだけです。この2つ以外のスラッグが使えるのか、決まった語彙があるのかは、ドキュメントからは分かりません。オプションなので、付かない指摘もあります。
| 項目 | 必須か | 一覧での見え方 |
|---|---|---|
| ファイル | 必須か3項目の1つ | 一覧での見え方ファイルの位置として表示 |
| 要約 | 必須か3項目の1つ | 一覧での見え方1文の要約として表示 |
| 失敗シナリオ | 必須か3項目の1つ | 一覧での見え方指摘の中身(表示の詳細は公式に記述なし) |
| category | 必須か任意(v2.1.199以降) | 一覧での見え方ファイルの位置の横のタグ |
どんなときにClaudeはReportFindingsを呼ぶのか
ツールリファレンスは、有効なコードレビューの指示がこのツールの利用を指示したときにClaudeが呼ぶ、としています。指示がなければ呼びません。
/code-reviewのドキュメントは、その「指示」の出どころを具体的に書いています。
| 実行の場面 | 指摘の出力先 |
|---|---|
ターミナルセッションで/code-review(フォークしたサブエージェントとして実行) | 指摘の出力先返信のテキスト |
-pによる非対話実行(テキスト出力・JSON出力) | 指摘の出力先返信のテキスト |
| 指摘リストを要求するホストアプリ(例: デスクトップアプリ) | 指摘の出力先ReportFindingsツール |
ホストアプリが指摘リストを要求した場合は、どのeffortレベルでも適用されます。この動作はv2.1.218以降が前提です。ホストが要求していても、上の表の最初の2行の実行方法では、指摘はテキストで返ります。
effortをlowにしてもmaxにしても、ホストが指摘リストを要求していれば出力の形は同じです。ターミナルの利用者が一覧を見られない理由は、effortの設定ではなく、実行方法にあります。ターミナルでの実行と-pは、ホストが要求していても指摘をテキストで返す経路だからです。
したがって、ターミナルで/code-reviewを打って指摘がただの文章で返ってきても、不具合ではありません。仕様どおりの挙動です。一覧描画を見られるのは、デスクトップアプリのようなホスト側の要求があるときです。/code-review自体の使い方はClaude Codeコードレビューの4つの実行経路に、effortの渡し方は/code-reviewでeffortを指定する方法にあります。
修正後の再報告で状態が付く
/code-reviewのドキュメントには、続きがあります。報告された指摘をClaudeが後から直すと、Claudeは指摘を報告し直します。すると、更新された一覧の各指摘に「修正済み」「見送り」「対応不要」のいずれかの印が付きます。
原文の表現は、fixed、skipped、no change neededです。指摘を出して終わりではなく、直したかどうかまで同じリストで追える作りです。これはテキスト出力では成立しにくい点で、構造化する意味が最も出る部分です。
自分のレビューskillに組み込むときの考え方
ここからは、公式に書かれた事実をもとにした設計の考え方です。挙動の保証ではありません。
ReportFindingsはClaudeの判断で呼ばれます。skillの本文で「指摘はReportFindingsで報告する」と書けば、レビューの指示側がこのツールの利用を指示した形になります。Skillはツールリファレンスの説明どおり、新しいツールを増やさず既存のSkillツールを通して動きます。
例えば、次のようなskillです。あくまで例示で、公式サンプルではありません。
---
name: pr-review
description: 差分をレビューし、指摘を構造化リストで報告する
context: fork
disable-model-invocation: true
---
現在のブランチの差分をレビューします。
1. 正しさのバグと、テストの不足を探す
2. 各指摘には、ファイル、1文の要約、失敗シナリオを書く
3. 指摘のcategoryは correctness か test-coverage のどちらかにする
4. 結果は ReportFindings ツールで報告する
5. 指摘がなければ、その旨を1文で書くcontext: forkは、skillを専用のサブエージェントの文脈で動かす設定です。disable-model-invocation: trueは、Claudeが自動でskillを読み込むのを止め、/pr-reviewと打ったときだけ動かす設定です。2つとも、skillのフロントマターの項目として公式に定義されています。
一覧描画になるかは先に確かめる
上のskillを書いても、ターミナルのセッションで一覧描画になるとは限りません。/code-reviewのターミナル実行では、ホストの要求があっても指摘がテキストで返ると明記されています。自作skillについては、同じ条件で一覧になるかどうかの記述が見当たりません。
そのため、自作skillを配る前に、自分の使う面で実際の出力を確かめます。確認は次のように進めます。
claude --versionでバージョンを確認する(v2.1.196以降。categoryを見たいならv2.1.199以降)- 使う面(ターミナル、デスクトップアプリ、
-p)ごとにskillを1回走らせる - 指摘が一覧になったか、テキストで返ったかを控える
控えの例は次のとおりです。/code-reviewのドキュメントに書かれた挙動を基準にした書き方で、自作skillの結果は各自の実行で埋めます。
| 使う面 | /code-reviewの出力先 | 自作skillの結果(自分で記入) |
|---|---|---|
| ターミナルセッション | /code-reviewの出力先返信のテキスト | 自作skillの結果(自分で記入)一覧 / テキスト |
| デスクトップアプリ | /code-reviewの出力先ReportFindingsの一覧 | 自作skillの結果(自分で記入)一覧 / テキスト |
-pの非対話実行 | /code-reviewの出力先返信のテキスト | 自作skillの結果(自分で記入)一覧 / テキスト |
3列目が/code-reviewの列と食い違う面があれば、そこがskillの設計を見直す箇所です。
claude --versionツールがセッションで使えるかは、Claudeに直接聞けます。公式が挙げている確認方法です。
What tools do you have access to?Claudeが会話形式で要約を返します。MCPツールの正確な名前が必要なときは/mcpを使います。一覧にReportFindingsが出ない場合は、バージョンが古いか、使っている面で有効になっていない可能性があります。
カテゴリの語彙は自分で決めておく
categoryはオプションで、公式の語彙一覧もありません。自作skillでは、使うスラッグを本文に書いて縛るのが確実です。上の例はcorrectnessとtest-coverageの2つに絞っています。
語彙を決めておくと、二つの利点があります。
- 描画される一覧で、同じ種類の指摘が同じタグにそろう
- チームでレビュー結果を見比べるとき、タグの表記ゆれが出ない
反対に、語彙を決めないと、Claudeが指摘ごとに違うスラッグを付ける可能性があります。付け方の揺れは、一覧の見やすさに直接効きます。
GitHubのレビュー機能とは別物
ReportFindingsは、セッション内でレビュー結果を返すためのツールです。GitHub上のCode Reviewが出す指摘とは別の仕組みです。
/code-review --commentはGitHubのプルリクエストにインラインコメントを、GitLabのマージリクエストには単一のノートを投稿します。GitLabへの投稿はv2.1.257以降が前提で、glab CLIも必要です。この経路は、指摘をリポジトリ側に残すためのものです。一方、GitHub側のCode Reviewが出した指摘が、解消しない限り次のレビューで数え直される仕様は、Claude Code Reviewの指摘は解消しないと再カウントされるで扱っています。名前が似ていますが、こちらのツールとは関係しません。
クラウドで動く/code-review ultraの使い方は、ultrareviewの使い方にまとめています。
権限とhookでの扱い
ツールリファレンスによれば、ツール名は権限ルール、サブエージェントのツールリスト、hookのマッチャーで使う正確な文字列です。ReportFindingsは括弧付きの指定子を取るツールの一覧に載っていないため、書くなら名前だけの形になります。
一覧の表示だけを止めたい、あるいは特定のサブエージェントに渡すツールを絞りたい、といった場面で名前が必要になります。ただし、拒否したときにレビューがどう縮退するのかは、公式に記述がありません。試すときは、指摘がテキストに戻るのか、失われるのかを実行して確認します。
hookのマッチャーも括弧付きではなく、名前そのものを書きます。ツール実行前後のhookの使い方は、PreToolUse hookとPostToolUse hookにあります。ReportFindingsがhookに渡す入力のフィールドは、ツールリファレンスにも記載がないため、hookで加工する前に実際の入力を確かめてください。
まとめ
ReportFindingsは、レビュー指摘をファイル・要約・失敗シナリオの3項目に構造化し、Claude Codeに一覧として描画させるツールです。v2.1.199からは、correctnessやtest-coverageのようなcategoryスラッグが指摘の横に付きます。
呼ばれるのは、レビューの指示がこのツールの利用を指示したときです。/code-reviewでは、ホストアプリが指摘リストを要求する場合(v2.1.218以降)に限られ、ターミナルや-pではテキストで返ります。自作skillに組み込むときは、使う面ごとに出力を確かめ、categoryの語彙を本文で決めておくと、結果がそろいます。