claude-apiのbuild-evalとhillclimb — 過学習を避けるeval設計の原則と事例
claude-apiスキルのbuild-evalとhillclimbが前提にする評価設計の原則と、train/test分割で過学習を防ぐ手順を解説。コスト約5分の1と66%から約88%への事例も数字で読みます。
build-evalとhillclimbは何を肩代わりするのか
claude-apiスキルのbuild-evalは評価(eval)をコードベースの中に作るコマンドで、hillclimbはその評価に向けてアプリを1回に1変更ずつ改善するコマンドです。Anthropicの開発者ブログは、2つのコマンドの土台になっている評価設計と改善ループの原則を、2件の適用例つきで公開しました。
事例の数字は目を引きます。社内のサポートチケット評価では、1チケットあたりのコストが4.6セントから1セントに下がりました。claude-apiスキル自身の評価では、通過率が66%から約88%に上がっています。
どちらのコマンドもClaude Codeに同梱されるskillのサブコマンドで、必要なバージョンはv2.1.259以降です。コマンドの細かい挙動は/claude-api hillclimbの解説にあります。この記事は一段手前の「なぜその手順なのか」と、2件の事例の数字の読み方を扱います。採点器の類型やpass@kなど、エージェント評価一般の設計はAIエージェントのEval設計にあります。
claude --version
claude updateskillはClaude Codeの中に入っているため、新しいサブコマンドを使うには本体の更新が先です。更新後は次の2行をClaude Codeのプロンプトから打ちます。
/claude-api build-eval
/claude-api hillclimb良いevalが満たす4つの条件
評価の出来は、4つの条件で点検できます。ブログの図1は、モデルが強いほど、effortが高いほどスコアが上がる関係を描いています。
評価が備えるべき性質
タスクが本番を写している
本番で気にする仕事の分布から取ります。作りやすい問題や採点しやすい問題に偏ると、測りたいものから外れます。
強いモデルと高いeffortほど点が上がる
上がらないときは、曖昧なタスクか、採点器のずれが足を引っ張っています。
満点との間に余地がある
最強モデルを最高effortで回しても、満点よりかなり下に収まる設計にします。
実行ごとのばらつきが小さい
ばらつきの原因は曖昧なタスクと、同じ出力に違う判定を出す採点器です。
4条件は設計時の理想であると同時に、できあがった評価の診断にも使えます。診断の手がかりは次のとおりです。
- 毎回の実行で、反復回数に関係なく落ち続けるタスクは、不可能か曖昧であることを疑うサインです。良いタスクは「2人のドメイン専門家が同じ判定に達し、採点器が見る内容がすべてタスクに書かれている」ものです
- effortが一貫して適用されていないと、ばらつきが設定に隠れます
- 前回の試行で残ったファイルやgit履歴が、エージェントに答えを渡してしまう環境も、スコアを歪めます
特に余地の条件は、後のhillclimbの設計に直結します。ベースラインがすでに約95%以上なら、スキルは警告を出し、品質ではなくコストやレイテンシを探る方向に切り替えるよう促します。上げる余地のない評価で品質を追っても、ループが空回りしやすいためです。
今のモデルが落とす問題だけで集めない理由
評価に入れる問題を「今のモデルが間違えたもの」だけで選ぶと、評価が歪みます。モデルの能力は凸凹しており、今日のモデルが落とす問題だけを集めると、そのモデル1つの谷間をサンプリングすることになるためです。評価が測るのは、アプリにとって本質的に難しいことではなく、特定モデルの失敗の癖になります。
代わりに、難しいと人間が判断した問題を入れます。目安は「なぜ難しいかを言葉にできるか」です。本番のトラフィック、バグ報告、チケットから拾った具体的な失敗も入れます。
ただし、ユーザーの入力をそのまま信じるのも危険です。人は「動くと期待できること」を試すので、本番ログだけから取った分布は易しい側に寄ります。難しい問題は、人間が意図して足します。
build-evalが人間に確認させる2つの関所
/claude-api build-evalを実行すると、Claudeはインタビューしながら評価をコードベースの中に作り、特定の地点で承認を求めて止まります。止まる地点は、入力と採点器の2つです。
build-evalの進み方
- 1
入力を集める
優先順は、本番のトランスクリプト(保持期間と機微データを先に質問)、バグ報告とサポートチケット、手書きの5〜10件、コードベースから合成したケースです。実例を数件渡せば、それを足場に合成データも作れます。
- 2
入力の一覧ページを見る
スキルは全入力を並べた簡素なページを作り、確認を得るまで待ちます。
- 3
採点器を選ぶ
出力が限られるなら、完全一致・固定ラベル・JSONスキーマ・テストの合否といったコード側の検証を選びます。出力が自由記述なら、LLM-as-judgeを既定にします。
- 4
採点を数件見せる
Claudeが数件を採点し、人間が違う点をつけるかを尋ねます。
- 5
ベースラインを回す
評価の規模(ケース数×反復×モデル、おおよその所要時間)を伝えてから実行し、信頼区間つきのスコアを出します。
LLM-as-judgeの設計には細かい指定があります。ルーブリックは1〜5の段階ではなく、検査できる主張の形で書きます。ベースラインと比べるときは、どちらがベースラインか伏せたまま、順序を乱数で入れ替えて読ませます。判定役のモデルは、評価対象のモデルと別のものを選びます。
採点器を信じる前に、採点済みのトランスクリプトを数件読みます。採点の失敗は、評価が誤設定される最も多い原因のひとつです。
ベースライン実行中の3つの診断
ベースラインを回す間に、Claudeは次を調べます。
| 診断 | 内容 |
|---|---|
| 採点器の安定性 | 内容同じ出力を2回採点し、判定が変わったかを報告 |
| 実行まわりの不具合 | 内容タイムアウト、APIエラー、途中で切れた回答を検出し、インフラのノイズをモデルのばらつきと誤認しない |
| 余地 | 内容約95%以上で警告 |
成果物は、ケース、採点器、実行スクリプト、ケースごとのJSON行と全文トランスクリプト、各ケースの点数から該当トランスクリプトへ辿れるページです。グラフは頼めば、同じ場所に追加のページとして作られます。追加のページは既定でローカルで開く静的ファイルで、ネットワークから何も読み込みません。
hillclimbを向ける先の選び方
評価ができたら、次は何をいじるかを決めます。hillclimbを向ける面は、次の3つの条件で選びます。
| 条件 | 内容 | 例 |
|---|---|---|
| 安く反復できる | 内容時間・費用・手間の面で、変更が軽いこと | 例プロンプトやskillなどのテキストは変更も取り消しも簡単。ハーネスの自由な改造は大規模なコード変更になることがある |
| 変化を帰属できる | 内容スコアの変動が、いじっている面のせいだと言えること | 例skillの発火率は、変更するskillの説明文と直結する |
| 目的の範囲が絞れている | 内容余地を考えずに「改善して」と頼むと止まりやすい | 例評価が飽和していても、性能を保ったままコストを下げる目的は成立する |
3つ目の指摘は実務で効きます。評価が天井に近いのに「性能を上げて」と頼むと、改善の余地がなく、ループは止まりやすくなります。そのときはコスト削減に目的を切り替えると、評価は飽和していても仕事が残ります。変更できる対象は、システムプロンプト、skillや指示ファイル、ツール説明、モデルやeffortなどのAPIパラメーター、ハーネスのコードの5つから選びます。
過学習は3つの仕組みで抑える
評価が本番の分布と完全に一致することはまずありません。評価に合わせて磨くほど、評価では良くて本番では良くならないシステムができます。評価の問題がハーネス(モデルを囲むプロンプト・ツール・ループのコード)へ染み出すのが典型です。
例を挙げると、評価にはOCRが効く問題があり、本番ではほとんど効かない場合です。評価用のハーネスにOCRツールを足すとスコアは上がりますが、本番には何も変わりません。評価のエッジケースに合わせた機能追加も、同じ型の失敗です。
対策は3つです。
過学習を抑える3つの決まり
- 評価をtrainとtestに分け、hillclimber(改善を提案する側のClaude)が読むのはtrainだけにする。trainが上がってもtestが動かなければ過学習の兆候
- 失敗したトランスクリプトを読んでも、その中身をプロンプトに貼り付けない
- 答えがモデルの手の届く場所に置かれないよう、構造で守る。モデルが評価の答えを直接探して報酬を稼ぐことがあるため
この3つがhillclimbの中でどう動くかは、ラウンドごとにはっきりしています。Claudeは最初に何を最適化するか(性能、または性能を保ったままのコスト)を尋ね、評価をtestとtrainにランダムに分けます。最初のラウンドの前に、評価のノイズ(偶然だけでスコアが動く幅)が、行動に移す最小の改善幅より小さいかを確認し、大きければ反復かケースの追加を提案します。
各ラウンドでは、前ラウンドのtrainのトランスクリプトを読んで、パッチ1つを提案します。狙うのは、評価のノイズを超えて見える変更です。1行の言い換えではなく、原因の節を書き直す、足りない規則を足すといった根本の修正になります。実行後の判定は単純です。
- trainが上がり、testが横ばいなら過学習を疑って取り消す
- 悪化したら取り消す
- 両方が上がれば残す
スコアが2〜3ラウンド止まると、残った失敗を原因別に分類します。ノイズに埋もれて1つの修正が届かないと分かった時点で、早めに分類へ移ることもあります。曖昧な評価ケース、ハーネスのエラー、ばらつきを拾うための工程で、正当な失敗だけが次のラウンドに残ります。
終了時、コードはtestで最良だった版に置かれ、ベースラインとの差が信頼区間つきで報告されます。差がノイズの範囲なら、その旨を伝えてマージを勧めません。
事例1: サポートチケットのコストを約5分の1に
社内のサポートチケット評価は44件で、30件を探索に使い、14件を取り置きました。出発点はOpus 4.8の既定(high)effortで、探索チケットの判断精度が74.4%、1チケットあたりのトークンコストが4.6セントです。
hillclimbが辿った4つの構成
- 開始Opus 4.8 / high effort
精度74.4%、4.6セント。
- 1手目プロンプト監査 + Opus 5.5 / low effort
決まりきったツール呼び出し、スクラッチパッドの手順、矛盾する規則を削除したうえで、Opus 5.5のlow effortを試しました。公開されているのは、これらを済ませた後の精度87.8%、1.9セントです。
- 2手目Sonnet 5 / low effort(同じプロンプト)
基準を超えたのでもう一段安いモデルを試した結果、精度88.9%、約1セント。
- 3手目プロンプトの改善
ルーティング規則と返金上限の相互参照を追加。精度98.9%、約1セントのまま。
取り置き14件の最終結果は、元の構成の78.6%に対して90.5%で、コストは約5分の1です。
数字から読み取れること
まず、効いた変更が精度とコストで違います。コストは1手目で4.6セントから1.9セントへ(1.9÷4.6≒0.41から算出して約59%減)、2手目で約1セントまで下がりました。2手目はモデルだけを替えた一手なので、ここはモデルの効果と言えます。1手目の下がり幅の要因として、ブログが明示しているのは価格だけです。ブログによると、Opus 4.8と比べてOpus 5.5は入力と出力のトークンが20%、キャッシュ読み出しが60%安くなっています。手順を削った分やeffortをlowに下げた分で出力トークンが減った可能性はありますが、内訳は示されていません。精度の最後の約10ポイント(88.9%から98.9%)は、コストが約1セントで変わらないまま、プロンプトの改善で動きました。
次に、1手目の数字は3つの変更を済ませた後の値です。プロンプトの監査、Opus 4.8からOpus 5.5へのモデル変更、effortのhighからlowへの変更について、ブログは監査の後にOpus 5.5のlow effortを試したと順に書いています。同じラウンドとは書いていませんが、公開されている点は、3つをすべて済ませた後の値だけです。ブログの図に載っているのは採用された経路の4点だけで、Opus 4.8のまま監査だけをしたスコアは示されていません。87.8%のうち、プロンプトの掃除が稼いだ分、モデルが稼いだ分、effortを下げた影響は、この記述からは切り分けられません。自分の評価で同じことをするなら、1ラウンド1変更の原則どおり、監査・モデル変更・effort変更を別のラウンドに分けると、効いた要素が見えます。
Opus 5.5の値下げが単価として何に効くかは、Opus 5.5の「40%安い」を検証した記事に単価表つきでまとめてあります。
最後に、取り置きの14件が示す精度の粒度を見ます。1件の変化は、1回の実行なら約7.1ポイントです。78.6%は11/14に当たり、1回の実行でも出る値です。一方の90.5%は、14件を1回ずつ回しても作れません(12/14は85.7%、13/14は92.9%)。複数回の反復を平均したか、部分点のある採点と推測できます。ブログの本文は反復数も信頼区間も示していません。
hillclimbのスキル手順書は、二値の正解率の95%信頼区間の半幅を、およそ1/sqrt(n·反復数)と示しています。この式をそのまま使い、仮に14件を3回反復したとすると、半幅は約±15ポイントです。+11.9ポイントの改善は、区間の半幅と同じ桁の差になります。方向を示す結果として読むのが適切で、ケースを増やす余地が残る規模の評価です。
事例2: claude-apiスキル自身を66%から約88%へ
2つ目の事例は、claude-apiスキルを自分で改善した話です。APIを使う正しいコードをスキルが書かせられるかを、公式ドキュメントから作った評価で測りました。スキルの出発点は66%です。
hillclimberにドキュメントとSDKを渡すと、Claudeは誤りを自分で見つけて直しました。
66%から約88%までの4つの変更
- 66%出発点
ドキュメント由来の評価でのベースライン。
- 74%8機能の節を追加
スキルに8つの機能の説明が抜けていたため、節を足しました。
- 77%C#とJavaの型表を修正
型表の誤りを直しました。
- 80%旧APIから現行APIへの対応表
冒頭近くに置いた対応表です。
- 約88%採点器とタスク文面の修正、スキルの追加編集
採点器と課題文を直し、スキルの編集も重ねて約88%に届きました。
停滞が教えた2種類の原因
スコアが2ラウンド止まったあと、Claudeは残った失敗を根本原因で分類しました。この工程では編集せず、失敗を原因別に仕分けるだけです。
1つ目の発見は、スキルの内容は足りているのに、Claudeが古いAPIの形を書いていたことでした。学習済みの事前知識に引き戻されていたためです。対処としてスキルの冒頭近くに、記憶している形から現行の形への対応表を置きました。
- 固定トークン予算の拡張思考(最近のOpusではAPIが拒否する)から、適応的な思考へ
- web searchとweb fetchの古い版のツールから、現行のツールへ
C#とJavaでは、固定予算の思考を戒める警告を、適応的な思考の例より上に移しました。ここで80%になっています。モデルを移行したときに400になる変更点は、Claude Sonnet 5.5の解説にも載っています。
2つ目は、足りない内容を補っても伸びないタスクです。これは、課題か採点器に欠陥があるサインです。実際に、1つの種類のエラーを捕まえるコードを求めるタスクで、採点器は3種類以上の連鎖を要求していました。Claudeは課題の文面を直しました。別の採点器は指示がドキュメントと食い違っており、実APIで試すとドキュメントのほうが正しいと分かりました。
この事例の肝は、伸びが止まった直接の原因がスキルの不足ではなかったことです。モデルの事前知識と採点器の誤りという、足し算の編集では届かない場所にありました。止まったときに失敗を原因別に分ける工程が、コンテンツの追加ラウンドを重ねる前に効いています。
自分のプロジェクトに当てはめる確認点
ここまでの原則を、手元の評価で確かめるときの確認表にしました。左の列が原則、中央がその点検の仕方、右が見つかったときの動きです。
| 原則 | 点検の仕方 | 見つかったときの動き |
|---|---|---|
| 強いほど上がる | 点検の仕方最強モデルの最高effortと下位構成を比べる | 見つかったときの動き逆転するなら曖昧タスクと採点器を疑う |
| 満点に余地 | 点検の仕方ベースラインが約95%以上か | 見つかったときの動きコストかレイテンシを目的にする |
| 毎回落ちるタスク | 点検の仕方反復しても全滅しているケースを探す | 見つかったときの動きタスクか採点器を直す |
| 採点器の安定 | 点検の仕方同じ出力を2回採点して判定を比べる | 見つかったときの動きルーブリックを検査可能な主張に書き直す |
| 取り置き | 点検の仕方testをhillclimberに見せていないか | 見つかったときの動きtrainだけ読ませ、testは採点のみ |
実行まわりにも決めごとがあります。スキル手順書によれば、無人で回す前に、評価の実行コマンドを示してセッション中の許可を求めます。この許可の範囲がループの安全境界なので、実行コマンド1本に絞ります。
セッション中の許可の代わりに常設で許可するなら、.claude/settings.jsonに次のような形で書けます(手順書の趣旨に沿った例で、実プロジェクトではnpm run evalの部分を自分の実行コマンドに置き換えます)。
{
"permissions": {
"allow": ["Bash(npm run eval)"]
}
}評価の入口でも、Claudeには材料を渡せます。build-evalはトレースなどの実例を渡すと、それを足場に入力を設計します。たとえば次のような一言で始められます。
/claude-api build-eval 直近のサポートチケットの匿名化済みサンプルが
./samples/tickets.jsonl にあります。個人情報は含みませんコスト目的のhillclimbの前段にあたる、キャッシュとモデルの見直しは/claude-api cost-optimizeの手順で扱っています。skillの効果をより小さい単位で測る方法はskill-creatorのevalが近い道具です。
まとめ
この手順の要は、改善を測る側(test)を、改善する側(hillclimber)から隔てることです。評価の設計原則は4条件の点検、改善の安全装置はtrain/testの分割と取り消し規則に集約されます。
サポートチケットの事例で効果の出どころが言えるのは、プロンプトを変えずにモデルだけを替えた2手目と、構成を固定してプロンプトだけを直した3手目です。3つの変更を含む1手目は、公開された数字からは精度の出どころを切り分けられません。スキル自身の事例で停滞の原因を突き止めたのは、編集をせずに失敗を原因別に分けた工程でした。