Claude Opus 4.8のコードレビューで見逃しが増えたときのプロンプト直し方

Opus 4.8でレビューの指摘が減る原因は、モデルでなくプロンプトにある

自作のコードレビューハーネスをClaude Opus 4.8に載せ替えたら、検出件数が減った。そんなときの第一候補は、レビュープロンプトに残っている「重大度の高い問題だけ報告して」の類の一文です。

Opus 4.8のプロンプトガイドは、このモデルがバグ発見で旧モデルより優れ、社内評価では再現率(recall)も適合率(precision)も高いと説明しています。そのうえで、旧モデル向けに調整したハーネスでは当初recallが低く見えることがあり、モデルの能力低下ではなくハーネス側の効果である可能性が高いと述べています。

仕組みはこうです。プロンプトに「only report high-severity issues」「be conservative」「don't nitpick」と書くと、Opus 4.8は旧モデルより忠実に従います。コードは同じ深さで調べ、バグも見つけます。ただし自分が基準未満と判断した発見は報告しません。調査の量は変わらず、報告に変換される件数だけが減ります。低severityのバグで特に目立ちます。

結果として、適合率は上がり、測定上のrecallは下がります。「出てくる指摘は当たるのに、総数が足りない」状態です。

この記事の対象はOpus 4.8です。Opus 5とSonnet 5で同じ現象が出る場合の整理はOpus 5/Sonnet 5のコードレビューでrecallが下がる原因にあります。Opus 4.8のモデル一覧上の扱いは旧世代(legacy)ですが、引き続き利用できます。

見逃しの原因は3つに切り分ける

指摘が減ったとき、プロンプトだけを疑うと外れることがあります。Opus 4.8のガイドから、原因の候補は3つに分けられます。

2行目と3行目も、ガイドの記述に基づく切り分けです。effortについては、Opus 4.8は特にlowとmediumで努力水準を厳密に守り、頼まれた範囲に作業を絞ります。そのため中程度に複雑なタスクをlowで回すと、考えが浅くなるリスクがあるとされています。ガイドは、浅い推論を見たらプロンプトで補う前にeffortをhighかxhighに上げるよう勧めています。コーディングとエージェント用途の出発点はxhighです。

3行目は、Opus 4.8が指示を文字通りかつ明示的に解釈する性質に由来します。ある項目への指示を別の項目へ暗黙に広げることはせず、頼まれていないことも推測しません。「この観点を全ファイルで確認する」と書いたつもりでも、書いていなければ効く範囲は限られます。広く適用させたいなら、スコープを言葉にします。

原因が複数重なっていることもあります。1つずつ変えて、そのつど同じテストケースで件数を比べる進め方が確実です。

発見と絞り込みを2段に分けるプロンプト

ガイドの推奨は、発見の段階で絞り込ませず、網羅を目的にすることです。ガイドが示す文面の要旨は次のとおりです。

これを前提にした書き換え例を並べます。左が旧モデル向けに書かれがちな形、右が発見段階を網羅に振った形です。文面は筆者が組んだ例で、ガイドの原文そのものではありません。

変わったのは基準そのものではなく、誰がいつ基準を適用するかです。Beforeはモデルに発見と同時に取捨選択させ、Afterは取捨選択を後段へ回しています。

ガイドによれば、このプロンプトは実際に第2段のステップがなくても使えます。それでも確信度によるフィルタリングを発見ステップから外すことで、効果が出ることが多いとされています。検証・重複排除・ランキングの段がすでにあるハーネスなら、発見段のモデルに「ここでの仕事はフィルタではなく網羅」と明示します。

第2段は決定論的なフィルタで受ける

網羅させると出力は増えます。増えた分を人が読む運用だと、今度は読み手の負担が問題になります。そこで、発見段の出力を構造化し、第2段で機械的に絞る構成が扱いやすくなります。

発見段に出させる形式の例です(筆者の設計例で、公式の指定ではありません)。

{
  "findings": [
    {
      "file": "src/billing/invoice.ts",
      "line": 88,
      "summary": "割引適用前の金額で税額を計算している",
      "severity": "high",
      "confidence": "medium"
    },
    {
      "file": "src/billing/invoice.ts",
      "line": 131,
      "summary": "変数名がループ内で再利用されていて読みにくい",
      "severity": "low",
      "confidence": "high"
    }
  ]
}

保存した結果から、確信度が低いものを除く最小の例はこうです。

jq '[.findings[] | select(.confidence != "low")]' review.json

この絞り込みは、第2段をモデルにするか、スクリプトにするかを選べる位置にあります。モデルに任せるなら、第2段の役割は「報告の取捨選択」だと明示します。発見段のモデルに戻って再調査させるのではなく、すでに出た発見に実在性の裏づけがあるかを見る段にします。

1回のパスで自己フィルタさせたい場合もあります。その場合のガイドの指針は、「important」のような定性的な言葉を避け、線引きを具体的に書くことです。たとえば次のように書きます。

不正な挙動、テストの失敗、誤解を招く結果につながるバグはすべて報告する。
スタイルや命名の好みだけの指摘(nit)は省く。

これは「重要なものだけ」より、モデルが基準を再現しやすい書き方です。何を省くのかが名指しされているため、基準が曖昧なまま文字通りに効いてしまう事態を避けられます。

変更が効いたかを確かめる手順

プロンプトを書き換えたら、効果を数字で確認します。ガイドも、評価用のケースの一部で反復し、recallやF1スコアの改善を確かめるよう勧めています。

1. 過去にレビューで見逃した既知のバグを含む、小さなテストセットを用意する。severityが高いものと低いものを混ぜる
2. 現行のプロンプトで回し、既知バグのうち報告されたものの割合(recall)を記録する
3. 発見段を網羅型に変え、同じセットで回す。あわせて、報告された総件数と、実在しない指摘の割合も記録する
4. recallが上がっても、実在しない指摘の割合が許容範囲を超えるなら、第2段のフィルタを強める。発見段の指示に戻って絞るのではなく、第2段で調整する

3の「総件数」を見るのは、網羅型が指摘を増やす方向の変更だからです。recallだけを追うと、読み手が捌けない量になっていても気づけません。4で調整の場所を第2段に固定しておくと、発見段の網羅性を保ったまま適合率を整えられます。

Opus 4.8特有の落とし穴をあわせて確認する

レビューの見逃しとは別に、同じ移行で見直したい点がガイドにあります。

• 対話型での消費量: Opus 4.8は、ユーザーのターンの後で多く推論するため、対話型のコーディング用途では単発の非同期実行よりトークンを使いやすい。xhighかhighのeffortを使い、初回のターンでタスク・意図・制約を明確に書くと、後続のターンのコストを抑えられる
• max_tokens: maxやxhighのeffortで回すなら、思考とツール呼び出しの余地を確保するため、最大出力トークンを大きく取る。ガイドは64kトークンからの調整を勧める
• thinkingの既定: Opus 4.8はthinking: {type: "adaptive"}を明示しない限り、thinkingがオフ。レビューの深さを上げたいなら、effortとあわせて設定を確認する

Opus 5.5へ進む場合、thinkingを指定しないリクエストの扱いが変わります。移行ガイドによると、Opus 5.5ではthinking欄を省いたリクエストでもadaptive thinkingで動きます。レビュー用の呼び出しをそのまま載せ替える前に、max_tokensと出力トークンの増え方を見直す必要があります。

どの症状から手を付けるか

入口は症状で変わります。推論が浅いと見えるとき(確認の形跡が薄い、複数ファイルを追っていない)は、プロンプトを書き換える前にeffortをhighかxhighに上げます。ガイドもこの順序です。

逆に、effortがすでにhigh以上で、調べたはずの項目が報告に出ないなら、絞り込み指示を先に外します。絞り込み指示が効いている限り、effortを上げて調べる量が増えても、基準未満と判断された発見は報告に出てきません。

Claude Codeの/code-reviewで使うeffortの扱いはClaude Code /code-reviewでeffortを指定するに、レビューの実行経路の使い分けはClaude Codeコードレビュー — 4つの実行経路の使い分けにまとめています。後段に検証パスを足すとき、Opus 5のガイドには検証指示を外す方向の記述もあり、Claude Opus 5のプロンプトから検証の指示を外すで扱っています。