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つ以外のスラッグが使えるのか、決まった語彙があるのかは、公式ドキュメントに記載のない点です。オプションなので、付かない指摘もあります。

ツールの周辺は、バージョンごとに少しずつ広がってきました。

どんなときにClaudeはReportFindingsを呼ぶのか

ツールリファレンスは、有効なコードレビューの指示がこのツールの利用を指示したときにClaudeが呼ぶ、としています。指示がなければ呼びません。

/code-reviewのドキュメントは、その「指示」の出どころを具体的に書いています。

表の最初の2行の実行方法では、ホストが指摘リストを要求していても指摘はテキストで返ります。ホストの要求はeffortがlowでもmaxでも同じ形で働くので、ターミナルで一覧が出ないのはeffortの設定ではなく実行方法によります。

ターミナルで/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です。あくまで例示で、公式サンプルではありません。

---
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を配る前に、自分の使う面で実際の出力を確かめます。

控えの例は次のとおりです。/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のフラグも、出力先ごとに役割が分かれます。

GitLabへの投稿にはglab CLIが要り、未導入ならターミナルに指摘が出力されます。--max-findingsの値は、defaultを渡すまで後続のレビューにも引き継がれます。

これらはいずれもリポジトリ側に指摘を残す、または件数を絞るための経路です。GitHub側のCode Reviewが出した指摘が、解消しない限り次のレビューで数え直される仕様は、Claude Code Reviewの指摘は解消しないと再カウントされるで扱っています。名前が似ていますが、こちらのツールとは関係しません。

クラウドで動く/code-review ultraの使い方は、ultrareviewの使い方にまとめています。

権限とhookでの扱い

ツールリファレンスによれば、ツール名は権限ルール、サブエージェントのツールリスト、hookのマッチャーで使う正確な文字列です。ReportFindingsは括弧付きの指定子を取るツールの一覧に載っていないため、書くなら名前だけの形になります。

名前が要るのは、一覧の表示を止めたいときや、サブエージェントに渡すツールを絞りたいときです。ツール名はskillのallowed-toolsフロントマターや、hookのif条件でも使います。ただし、拒否したときにレビューがどう縮退するのかは、公式に記述がありません。試すときは、指摘がテキストに戻るのか、失われるのかを実行して確かめます。

CLIでは、ツール名を渡すフラグが2つあります。v2.1.289のclaude --helpは、次のように説明しています。

claude --help

--disallowedTools, --disallowed-tools <tools...>
    Comma or space-separated list of tool names to deny
    (e.g. "Bash(git *) Edit")
--tools <tools...>
    Specify the list of available tools from the built-in set.
    Use "" to disable all tools, "default" to use all tools,
    or specify tool names (e.g. "Bash,Edit,Read").

--toolsは使えるツールを組み込みの中から選ぶフラグで、--disallowedToolsは拒否する名前を並べるフラグです。名前だけを渡すと、該当するツールがClaudeのコンテキストから外れます。ReportFindingsはどちらにも名前だけで書けます。

hookのマッチャーも括弧付きではなく、名前そのものを書きます。ツール実行前後のhookの使い方は、PreToolUse hookとPostToolUse hookにあります。ReportFindingsがhookに渡す入力のフィールドは、ツールリファレンスにも記載がないため、hookで加工する前に実際の入力を確かめてください。

まとめ

自作のレビューskillを配るなら、先に決めておく点が2つあります。一覧描画を期待する面で実際の出力を確かめることと、categoryに使うスラッグを本文で縛ることです。

ターミナルで/code-reviewの指摘を一覧として見たい場合、このツールは選択肢になりません。ホストアプリが指摘リストを要求する場合(v2.1.218以降が必要)がその入口で、ターミナルと-pではテキストが返ります。