
5問のテストでは見えない「何を壊したか」~AIの変更を60ケースで確かめる評価ハーネス~
最近、Tony Cueva(@tonycueva)さんの「Build Your Eval Harness」を読みました。Evals and Tracing連載の後編です。
AIアプリの変更が「何を直し、何を壊したか」を、変更のたびに確かめる仕組みを、動くサンプルアプリと測った数字で組み立てています。
面白かったのは、5問のテストで通った修正が、実際の問い合わせに近い60ケースでは33しか通らなかったという落差から話が始まるところです。そこから33/60、41/60、54/60(回帰0件)と進み、最後はCIで何を止めるかの基準になります。
この記事では原文の手順をなぞりません。評価ハーネスとは何か、エージェントのハーネスとどう違うのか、「揺れ」をどう仕分けるのか、CIの合否をどこで切るのかを、順に整理します。
なお、著者は評価ツールを提供するConfident AIの社員で、原文は同社ツールを使うベンダーの教育コンテンツです。数字はすべて著者自身が自分のサンプルアプリで実行した結果で、第三者による再現は確認できていません。
前編(トレースと評価の基礎)は、別の記事で取り上げています。先に読むと、この記事の前提がつかみやすくなります。
【発端】 5問では通った修正が、60ケースでは33
小さなテストが守るのは「すでに知っているバグ」だけです。
前編(Evals and Tracing 101)では、靴のオンライン店のサポートボットを題材に、トレースの読み方と評価指標の基礎を扱っていました。そこでは5問のテストで、既知のバグの修正を確認しています。
後編では、同じボットを実サーバーに置き、実際の問い合わせに近い20問を3回ずつ聞きます。合計60ケースのうち、通ったのは33でした。
5問は、すでに知っていたバグしか覆っていなかったのです。
次に起きるのは、別のバグを直すためにプロンプトを書き換える場面です。このとき「ほかに何が壊れたか」を誰も言えません。
後編はこの問題への答えとして、評価ハーネスを組み立てます。
【基礎】 動かすハーネスと、測るハーネス

「ハーネス」という言葉には2つの役割があり、混ぜると何を指しているのか分からなくなります。
エージェントのハーネスは、モデルに道具を渡し、課題が終わるまでループを回す枠組みです。Claude CodeやCodexがこれにあたります。
Anthropicは、エージェントを評価するとき、測っているのは「ハーネスとモデルの組」だと整理しています(Demystifying evals for AI agents)。
評価ハーネスは、それを外から測る側です。固定したテスト問題を流し、答えを採点し、結果を集計します。
役割
エージェントのハーネス:モデルを動かして仕事をさせる
評価ハーネス:動かした結果を測る
中身
エージェントのハーネス:道具、ループ、入出力の制御
評価ハーネス:テスト問題、採点役、集計と比較
出力
エージェントのハーネス:ユーザーへの答えや行動
評価ハーネス:合否、スコア、前回との差
例
エージェントのハーネス:Claude Code、Codex
評価ハーネス:原文のpytest一式
原文のボットは、ヘルプ記事を検索して答える小さなアプリです。ツールを回し続けるエージェントではありません。
それでも評価ハーネスの考え方は同じように使えます。
用語を3つだけ押さえます。ゴールデンは、期待する答えつきのテスト問題です。
メトリクスは、答えの良し悪しを採点する物差しです。判定役は、この採点を担当するLLMを指します。
【違い】 合格率ではなく、動いた中身を見る

合格率は「どれだけ動いたか」しか言わず、比較は「何が動いたか」まで言います。
従来の確認は、直した問いが通れば出荷、という形でした。評価ハーネスは、全問を毎回聞き直し、前回の結果と問いごとに見比べます。
範囲
5問の確認:直したバグ周辺
評価ハーネス:実際の問い合わせに近い20問
回数
5問の確認:1回
評価ハーネス:各問3回
出る答え
5問の確認:通った、通らなかった
評価ハーネス:直った、壊れた、揺れ始めた、まだ落ちる
出荷の判断
5問の確認:手元の感触
評価ハーネス:比較結果とルール
原文は、一覧の読み方にも順序をつけています。「まだ落ちる」が作業リスト、「揺れ始めた」が人が読むリストで、合格率は最後です。
55%という数字には、本物のバグと判定のノイズが混ざっているためです。
【仕組み】 3回聞き、「常に」で仕分ける



1問を3回聞いて「常に通る、常に落ちる、揺れる」に分けると、バグとノイズは別々です。
AIアプリは同じ問いでも答えが変わり、判定役のスコアも変わります。そこでハーネスは各問を3回実行し、結果を次の3つに分けます。
3回揃わない問いは「エラー」で、別扱いです。
常に通る:3回とも合格。信頼できる問い
常に落ちる:3回とも不合格。本物のバグ
揺れる:合格と不合格が混ざる。人が読む対象
揺れた問いは、3回分の答えを並べて読みます。答えが違えばボットが揺れていて、答えが同じでスコアだけ違えば判定役が揺れています。
原文の例では、注文4821の問いは3回とも同じ正しい答えでしたが、判定は「不合格、不合格、合格」でした。この場合、直すのはボットでなく採点基準です。
採点の物差しにも工夫があります。「正しい方針か」を見るメトリクスには正しいヘルプ全文を渡し、「作り話をしていないか」を見るメトリクスには、ボットが実際に見た検索結果とツールの出力だけを渡します。
根拠を取り違えると、正しい答えまで落とします。実際に原文でも、注文状況を答える問いが誤って落ちていました。
CIでは、止める条件を絞ります。原文のゲートは3回の試行錯誤を経ています。
テストが1つでも落ちたら失敗にしました。mainでも落ちる問いがあり、常に赤で無視されました
1回の実行で回帰を見ました。丁寧な結びの一文で関連性が0.67になり、正しい答えが誤報になりました
3回の結果で「常に通る→常に落ちる」だけを失敗にしました。揺れは一覧にして、人が読む対象にしました
結果が欠けた問いも失敗です。最初は、サーバーエラーで結果が空のケースを合格と数えるバグがあったため、再試行と件数チェックを加えています。
【具体例】 33→41→54、回帰0件
変更を1つずつ入れたから、どの直しが役に立ったかが分かりました。
最初の実行は33/60でした。常に通る7問、常に落ちる5問、揺れる8問で、エラーは0です。
1つ目の変更はプロンプトです。ヘルプにある内容だけで答える、分からなければ人間の担当者につなぐ、1週間は7日として数える、という指示を足しました。
結果は41/60で、7問が直り、回帰は0件です。価格マッチや子ども靴などは「分からない」と担当者の案内に変わりました。
ところが「5週間前に買った靴を返せるか」は、3回とも落ちたままでした。トレースを開くと、検索が30日ルールの文書を返していませんでした。
「送り返す」という言い方が、文書の語と1語も重ならなかったのです。プロンプトでは直せない、検索の問題でした。
2つ目の変更は、検索を単語一致から意味での一致(埋め込み)に替えることです。結果は54/60、回帰0件で、5週間の問いは3回とも通りました。
「別のカードに返金できるか」も同じ原因で直っています。
残った「靴が破損して届いた」は、ヘルプに該当文書がないため、文書を足すのはサポート側の判断です。
なおConfident AIの比較画面は、3ケースを「回帰」と表示しました。そのうち速達送料の問いは、前の版でも揺れていた問いで、1回の失敗を回帰と呼ばないのが3回実行の意味です。
数字は、20問の1アプリ、1人の実行結果です。同じ値になる保証はなく、原文も「多少ずれる」と書いています。
【関連概念】 揺れの数え方と、判定役の信頼

この仕組みは、評価の世界ですでにある考え方を小さく実装したものです。
pass^k:k回すべて成功する確率です。Anthropicは、1回あたりの成功率が75%なら3回連続成功は約42%と説明しています。「常に通る」は、この考え方に近い基準です
誤差分析:本番の出力を読み、失敗を型に分け、数えてからテストを書く手順です。Hamel Husainが一貫して勧めており、原文のステップ1にあたります
判定役の校正:LLMの採点は人間の判断と照らして確かめます。G-Evalの論文も、LLMの評価者がLLM生成の文章に偏る可能性を指摘しています
回帰評価と能力評価:ほぼ100%を保つべき回帰用と、伸ばしたい能力用は別に持ちます。原文の「常に通る問いを守る」は前者にあたります
参考情報・参考書籍(PR)
本記事をより深く理解するために、概念マップスライドを作成しました。こちらをみることで理解の補助になるはずです。
松木 晋祐『生成AIアプリケーション評価入門』。生成AIアプリの評価を題名にした日本語の入門書です。
上野 彰大、大嶋 勇樹『LLMアプリケーション評価駆動開発 継続的に改善し運用していくための実践知』。書名のとおり、評価を続けながら改善し運用していく本で、変更のたびに確かめるこの記事の主題と重なります。
John Berryman、Albert Ziegler『LLMのプロンプトエンジニアリング』(翻訳は服部 佑樹、佐藤 直生)。プロンプトの作り方を題名にした本で、この記事が最初に変えたのもプロンプトです。
Shreya Shankar、Hamel Husain『Evals for AI Engineers』(英語の電子書籍)。評価を題名にした本で、関連概念に名前を出したHamel Husainの共著にあたります。
関連記事
【まとめ】 自分の失敗20問を3回聞き直す
最初の一歩は仕組みの導入でなく、失敗を並べることです。原文のコードを私が動かして確かめたわけではないので、次は読み手が自分で試す際の手順です。
本番かそれに近いログから、失敗した問いを20問ほど集める
各問に、期待する答えを「判断+理由」で書く
失敗の型ごとに、1つずつ採点基準を決める
各問を3回聞き、常に通る、常に落ちる、揺れるに分ける
揺れた問いは、答えが違うか、同じなのにスコアが違うかを見る
変更は1回に1つにして、前回との差を読む
判定役のモデルは、比べる全実行で固定してください。原文も、モデルを変えるとコストとスコアが変わると注意しています。
前編は以下の記事で整理しているので、まだ読んでいない場合には見てみてください。