サブエージェントにコードレビューを依頼してレポートを確認する方法

"ページを確認してください"というリクエストは、レビュアーに多くの判断を残します。動作のエラーを探すのか、見た目を評価するのか、コードの別の書き方を提案するのか。その結果、きれいに整ってはいるものの、肝心のタスクにはほとんど役立たない指摘のリストが返ってくることもあります。Claude Codeのサブエージェントに明確な指示を与える方法と、その実行を確認する方法を説明しましょう。

もしまだreviewerを設定していなければ、まずロールを作成し、最初の実行を済ませてください。ここでは指示そのものと、回答の完全性に焦点を当てます。

1. レビュアーに何を渡すか

レビュアーは他人の作業を確認し、根拠を添えた指摘を返します。この記事の例では、reviewerという名前で設定済みのカスタムサブエージェントがこの役を担います。使えるのはファイルの読み取りと検索だけで、具体的にはRead, Grep, Globです。コードを調べますが、修正したり、ブラウザでページを開いたりはしません。reviewerという名前を付けただけでは、このようなロールは自動的には作られません。あなたのプロジェクトで既に設定されていることが前提です。

通常の方法で新しく起動した場合、このようなサブエージェントは会話全体の履歴を自動的に受け取りません。あなたが対話しているメインエージェントが、サブエージェント用に別のタスクを書き起こします。したがって、"同じ名前の2つの購入は異なるレコードと見なされる"などの重要な要件は、指示の中に書くか、レビュアーに読ませるドキュメントに入れておく必要があります。この仕組みはサブエージェントのコンテキストに関するドキュメントに記載されています。ここで扱うのはカスタムロールの実行で、会話のコピーを引き継ぐforkではありません。

"プロジェクトを見てください"と"レコード削除とカウンター更新を確認してください。コードは変更しないでください"を比較してください。後者なら、どこを見ればよいかも、どんな作業を望んでいないかも既に分かります。あとは、何が正しい結果と見なされるかを明確にするだけです。

短い1回限りの確認なら、メッセージで十分です。基準が多い場合や、修正のたびに確認を繰り返す場合は、ブリーフとして保存しておくと便利です。ブリーフとは、プロジェクトの中に置いておくタスクの短い説明のことです。10ページの仕様書ではありません。それがないとレビュアーが推測するしかない、いくつかの条件です。

すべての質問を先回りして予測することはできませんし、その必要もありません。入力データが足りないときは、レビュアーがその抜けをレポートに書くべきです。そうすればメインエージェントがあなたに確認できます。良い指示は解釈のずれを減らしますが、良い回答を保証するものではありません。タスクが明確でも、モデルは間違えることがあります。

2. 指示の4つの部分

目標は、どの動作を確認するのかという問いに答えます。買い物リストのページなら、アイテムの追加、削除、カウンターです。"プロジェクトをより良くする"では広すぎます。今どんな改善が大事なのかが分かりません。

入力は、ファイルと期待される動作を示します。同じ名前が許されるかどうかをコードから読み取れないなら、app.jsへのパスだけでは足りません。この仕様上の判断は、はっきり伝える必要があります。あわせて、何で確認するかも示しておきましょう。この例では、ブラウザは使わず、コードを読むだけです。

境界は、この確認を隣接するタスクから切り分けます。たとえば、スタイル、モバイル表示、セッションをまたいだリストの保存は今回は対象外です。ファイルは変更しない。必要なファイルがなければ、そのファイルに依存する部分の確認は止めて報告します。中身を想像で作ったりはしません。

結果は、何を受け取りたいかを表します。確認した範囲、根拠のある発見、そして制約です。"エラーを必ず5つ見つけること"のような要求はしないでください。Claude Codeのレビューに関する推奨事項でも、こうした依頼の仕方のリスクが指摘されています。欠点を探せという指示は、作業が正しく行われている箇所にまで指摘を出させる方向に働きます。

どの枝も、ほかの枝にはない情報を加えます。ファイルのパスからは期待される動作が分かりませんし、目標だけでは編集禁止は決まりません。これらの条件を1か所にまとめておけば、レビュアーは確認のときに照らし合わせることができます。

では、"買い物リストのページを確認して"の代わりに、次の指示を渡しましょう。メッセージで送っても、プロジェクトのルートにあるREVIEW_BRIEF.mdに保存しても構いません。

# 買い物リストの確認
目標: 追加、削除、カウンターをコードで確認する。
入力: プロジェクトのルートにあるindex.htmlとapp.js。
期待する動作: 追加したアイテムがリストに表示される。
カウンターはアイテム数と等しい。1件のレコードを削除しても、
同じ名前の別のレコードは削除されない。
境界: ファイルは変更しない。スタイル、モバイル表示、
セッションをまたいだリストの保存はこの確認に含めない。
必要なファイルや要件が足りなければ、その抜けを示すこと。
推測で補わず、確認できた部分の結果を返すこと。
結果: reviewerの形式に従う。確認したことと、未確認のことを示す。
発見がゼロでも構わない。

reviewerの形式については、すぐ下で説明します。あなたのロールにまだ固定の形式がなければ、同じ1回限りのメッセージに含めても構いません。項目名は必須ではありません。大事なのは、項目名のおかげで書き忘れずに済む情報のほうです。

"レポートでは、最も重要な発見を3つ先に示して"という依頼は、回答の量を絞るもので、確認の深さを絞るものではありません。こうした制限が必要なら、ほかにも発見があるかどうかを別に書くよう頼んでください。3つ目の指摘で手を止めて、タスクを確認済みと言ってしまうのは認められません。

3. ファイルに保存するもの

個々のタスクの条件は変わります。今日はカウンターを確認し、明日はリストの保存を確認する、という具合です。こうした条件はブリーフに書きます。一方、エラーの場所と根拠を示してほしいという要望は、ほぼすべてのレビューで必要です。こちらはロールの指示に一度書いておくほうが便利です。

Output contract、つまり出力の取り決めは、ここでは合意済みの回答形式を指します。名前ほど大げさなものではありません。レビュアー向けの普通の指示であって、Claude Codeの特別な設定でも、品質の自動チェックでもありません。形式があればレポートから必要な情報を探しやすくなりますが、その情報が正しいとは限りません。

上の2つの枝は、それぞれ別のことを受け持ちます。ブリーフは確認の内容を決め、ロールの指示にはレポートの形式も含まれます。保存したブリーフをレビュアーに使わせるには、ファイルを読むよう指示してください。自分からそこを見に行くことはありません。下に出てくるのがレポートで、その根拠と網羅性はこれから評価する必要があります。

既存のロールファイル.claude/agents/reviewer.mdの本文部分、つまり設定の後ろに、次のセクションを追加できます。

## 結果の形式
確認したファイルと基準を示す。
各発見について: 場所、期待される動作、根拠、
確認の条件と影響。優先度はその理由も書く。
コードで裏付けられたことと、未確認の推測を分ける。
制約と不足しているデータは別に挙げる。
基準に沿って問題が見つからなければ、そう書く。

これは指示の一部で、サブエージェントのファイル全体ではありません。このロールには読み取りと検索しかないので、"変更したファイル"という固定の項目は要りません。もっと広いレポートなら、変更についての記述は事実を反映している必要があります。実際に何が起きたかに関係なく、"変更したファイル: なし"という行を前もって指定しておくことはできません。

ブリーフを保存したら、メインエージェントに次のように依頼します。

reviewerに、プロジェクトのルートにあるREVIEW_BRIEF.mdを読んで、
その基準に沿って指定のファイルを確認するよう指示して。
最終レポートは省略せずに全文を返して。

ここでは、ドキュメントの名前を挙げるだけでなく、読むようにはっきり指示しました。ただし、ファイルがあるだけでは何も保証されません。レビュアーが条件を見落とす可能性は残ります。保存したブリーフが便利なのは、結果と照らし合わせたり、同じ確認を繰り返したりできるからです。要件が変わったら、まずドキュメントを更新してください。そうしないと、次の回は古いタスクを評価することになります。

4. レポートを確認する方法

まず、実際に何が確認されたかを見てください。ブリーフにあったのは、追加、削除、カウンター、そして同じ名前のレコードが互いに独立していることでした。レポートがカウンターのことしか書いていなければ、それはまだタスク全体の結果ではありません。たとえ唯一の発見がまったく正しくても、です。

ブリーフの基準を1つずつ回答と突き合わせると便利です。たとえば、説明用の部分的なレポートでは次のようになりました。

同じ名前についての行がないからといって、エラーがないとは言えません。一方で、カウンターについての根拠ある発見が1つあっても、タスクの抜けた部分が埋まるわけではありません。具体的に何を補ってほしいかを添えて、レポートを差し戻します。

ブリーフには、同じ名前の2つのレコードのうち1つを削除するケースがある。
レポートにはこの基準が出てこない。使える手段で確認して、
結果の根拠か、確認できなかった理由を書いて。
ほかの結論は、変更がなければ繰り返さなくていい。コードは変更しないで。

重要な発見がどこまで信頼できるかも、別に評価します。示された場所、要件、結論の根拠を突き合わせてください。詳しい例はレビューレポートの読み方についての記事にあります。ここでは、指示をどこまでカバーしたかと、結果に根拠があるかの両方を確認する必要があります。提案された実行手順は、実際に行ったテストと同じではありません。

最初の分岐では、今回のタスクに対して十分に確認されたかを判断します。足りなければ、不足分を依頼するか、確認済みの部分だけを受け入れます。その場合も、その部分の根拠は評価しておきます。2つ目の分岐では、根拠のある結論を、疑わしい結論や誤った結論と区別します。根拠がはっきりしないものは問い合わせる価値があります。誤りだと示せる指摘や、タスクと関係のない助言は却下して構いません。

発見のないレポートでも、この確認を通ることはあります。たとえば、"index.htmlとapp.jsで、追加と削除の処理経路、同じ名前のレコードの独立性、カウンターの更新を確認した。これらの基準では問題は見つからなかった。ブラウザでは実行していない"。こうした結論は、プロジェクトにエラーが一切ないことを約束するものではありません。示された範囲での結果を伝えているだけなので、必要なら主要な処理経路はあなた自身で確かめます。

一方、"指定のパスにapp.jsが見つからず、削除の動作を確認できなかった"は、データ不足を意味します。エラーがないという意味ではありません。この場合は正しいパスを渡して、確認を続けてもらいます。抜けを隠した長いレポートより、短くても正直な回答のほうが役に立ちます。

レポートを受け入れることは、書かれている項目をすべて修正させることではありません。確認結果に根拠があると認めただけです。今どの変更を行うかは、別に決めてください。

5. もう一度確認が必要なとき

レポートに根拠が足りなくても、レビューを最初からやり直す必要はありません。足りない点を具体的に示して差し戻します。たとえば、カウンターについての発見を短くまとめた版に、エラーの名前しかなく、呼び出しの分析がないとします。その場合、メインエージェントへの依頼は次のようになります。

reviewerのレポートを差し戻して、補足を頼んで。カウンターについての発見に、
削除後にカウンターを更新する経路が書かれていない。
この経路を確認して、結論の根拠を追加させて。
コードは変更しないこと。

更新が実はすでに別の関数で行われているとわかったら、その指摘は取り下げる必要があります。発見の数を前と同じにするために、代わりの指摘を探すことはしません。エラーが確かめられたら、具体的な発見と許される変更の範囲を示して、別の依頼としてメインエージェントに修正を任せることができます。

修正の後は、同じブリーフでもう一度確認しておくと役に立ちます。

reviewerにREVIEW_BRIEF.mdをもう一度読ませて、
現在の削除とカウンターのコードを確認させて。前回の発見:
削除後にカウンターが更新されなかった。
問題が解消されたかどうかと、その結論の根拠を示させて。
あわせて、同じ名前のレコードの独立性が損なわれていないかも確認させて。
コードは変更しないこと。

今度探しているのは、具体的な問いへの答えです。問題は解消されたか、そして修正の影響を受けそうな周辺の動作が壊れていないか。ページ上での動作を確かめるには、ブラウザで同じ手順を繰り返してください。再レビューがコードだけだったなら、その制約は新しいレポートにも残ります。

レポートは短くなることも、長くなることも、新しい発見がないこともあります。成功かどうかはそこでは決まりません。大事なのは、前の不具合が解消されていること、結論が今のコードに基づいていること、未確認の部分が見えるままになっていることです。修正を後回しにすると決めましたか？それなら、確かめられた発見と先送りの理由を残しておきましょう。変更していないコードを、新しい回答をもらうためだけにレビューし直す意味はありません。

6. 指示から確認済みの結果へ

Claude Codeでの作業では、メインエージェントがタスクをレビュアーに渡すあいだも、ブリーフがあなたの期待を保ってくれます。固定の形式があれば回答も読みやすくなります。それでも、あなた自身が関わる場面は残ります。具体的には次のとおりです。

• メインエージェントが指示をまとめ、適切なロールに渡します。期待される動作と境界を決めるのはあなたです。
• レビュアーがファイルを調べ、結論の根拠を返します。確認範囲と重要な発見をチェックするのはあなたです。
• メインエージェントは、別の指示を受けてレポートを補足させたり、確かめられたエラーを修正したりできます。何を変更し、結果をどう確かめるかを決めるのはあなたです。

買い物リストの場合、結果は単なる"関数の呼び出しを追加して"という助言ではなく、確かめられた説明になります。どの操作で数が古くなったのか、どこで更新が途切れていたのか、修正の後で何が変わったのか。こういう結果があれば、次の作業に進めます。