こんにちは！株式会社雲海設計の技術部です。
「プロンプトを直したら前より良くなった“気がする”」「評価はGPT-4に点数をつけさせている」——AIエージェント開発の現場でこうした声を聞くたびに、私たちは評価ハーネス（Evaluation Harness）の不在を疑います。2024年以降、Anthropic・OpenAI・DeepMindなど主要ラボの論文でも、モデル評価の再現性が業界共通の課題として明示されるようになりました。本記事では、AIエージェントを業務に耐える品質まで押し上げるためのハーネスエンジニアリング ベストプラクティスを、雲海設計の実運用に基づいて体系化します。
TL;DR
ハーネスエンジニアリング ベストプラクティスの核は「評価指標・再現性・CI連携・業務適用」の4層設計
LLM-as-Judge 単体は信頼できない。決定的チェック＋人手＋LLM判定のハイブリッドが正解
再現性はseed・バージョン・データスナップショット・環境の4点を固定して初めて確保される
評価はCIに組み込んで“回帰テスト化”しないと、プロンプト改修のたびに品質が揺れる
業務適用ではオフライン評価とオンライン評価（シャドー運用）を分離するのが鉄則
なぜ「評価ハーネス」が必要なのか？
結論から言うと、AIエージェントは“動いているように見える”が最もタチが悪いからです。決定的なバグと違い、確率的な劣化は検知されないまま本番に流れ込みます。
よくある失敗パターン
プロンプトを直したら別のタスクで静かに精度が落ちる（副作用）
モデルを gpt-4o から gpt-4o-mini に切り替えたら、特定のエッジケースだけ壊れる
評価スクリプトを毎回手動で回しているので、誰も再現できない“最高スコア”が残る
LLM-as-Judge の判定プロンプトが変わっていて、スコア自体の基準がドリフトしている
これは以前、AIエージェントの95%が失敗する本当の理由でも触れた構造的問題です。エージェントが複雑化するほど、評価が開発速度のボトルネックになります。
“You cannot improve what you cannot measure reliably.”（信頼できる形で測れないものは改善できない）——DeepMindの評価チームが度々引用する原則です。
ハーネスの4層モデル：何を設計すべきか？
雲海設計では、評価ハーネスを次の4層に分けて設計します。どれか1層でも抜けると、ハーネスは“気休め”になります。
層 | 責務 | 代表的な実装 |
|---|---|---|
① データセット層 | 評価入力・期待出力・メタデータの管理 | JSONL + DVC / LangSmith Datasets |
② ランナー層 | エージェント実行・ログ収集・再試行制御 | 自社ラッパー / Inspect AI / promptfoo |
③ スコアラー層 | 指標計算・LLM判定・集計 | ルールベース + LLM-as-Judge |
④ CI/レポート層 | 回帰検知・ダッシュボード・通知 | GitHub Actions + BigQuery + Looker |
この4層を疎結合に保つことがベストプラクティスの出発点です。ランナーとスコアラーが密結合だと、新しい指標を足すたびに評価実行まで作り直すハメになります。
評価指標はどう設計すべきか？
結論：「タスク成功率」という単一指標に逃げないことです。AIエージェントの評価は多次元でしか意味を持ちません。
最低限押さえる5つの軸
正確性（Correctness）：期待出力との一致率、または意味的等価性
安全性（Safety）：禁止操作の実行率、PII漏えい、ハルシネーション率
コスト（Cost）：1タスクあたりトークン消費と $ 換算
レイテンシ（Latency）：p50 / p95 応答時間
安定性（Stability）：同一入力での出力分散（温度固定でも発生する）
コストの読み方は別記事 生成AIの請求を“原価”に落とす方法 で詳しく扱っていますが、評価ハーネスにコストと精度を同じダッシュボードに並べるだけで、意思決定の質が劇的に変わります。
LLM-as-Judge の正しい使い方
LLM-as-Judge は便利ですが、単体で信じるのは危険です。Anthropicの2024年のレポートでも、判定モデルと生成モデルが同一だと自己バイアスで3〜8ポイント高評価になると報告されています。雲海設計では次のルールを徹底します。
判定モデルは生成モデルと別系列（例：生成=Claude、判定=GPT-4o）
判定プロンプトはバージョン管理し、変えたら過去データを再判定
10〜20%は人手でサンプリング検証して判定モデルの精度自体を監視
二者択一（A/B比較）はOK、100点満点スコアは不安定なので避ける
再現性はどう確保するのか？
結論：seedを固定しても再現はできません。LLMは本質的に非決定的であり、再現性は「同一条件で同一分布を出す」という確率的再現に切り替える必要があります。
固定すべき4点セット
項目 | 固定方法 | 注意点 |
|---|---|---|
モデル | バージョンID明示（例：gpt-4o-2024-08-06） | エイリアス指定は禁止 |
プロンプト | Git管理＋ハッシュ付与 | システム/ユーザー両方 |
データセット | DVC等でスナップショット | 追加時は別バージョン |
ランタイム | temperature / seed / tool定義 | seedは“おまじない”程度 |
そして評価は同じ入力を N=5〜10 回流して平均と分散を見るのが鉄則です。1回の実行で「スコア上がった！」と喜ぶのは、テストなしで本番リリースするのと同じ危うさがあります。
CIにどう組み込むか？
結論：評価は“たまに回す儀式”ではなく、PRごとに走る回帰テストにすべきです。
実装パターン：3段階ゲート
# .github/workflows/eval.yml（抜粋）
name: agent-eval
on: [pull_request]
jobs:
smoke:
# 数十件・数分で終わる軽量セット。全PRで必ず走らせる
runs-on: ubuntu-latest
steps:
- run: python harness/run.py --suite smoke --n 3
- run: python harness/gate.py --min-correctness 0.9
regression:
# 数百件。main マージ時のみ
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- run: python harness/run.py --suite regression --n 5
- run: python harness/report.py --upload bigquery
nightly:
# 数千件。コスト制御のため夜間のみ
# スケジュール実行、ダッシュボード更新
ポイントは「Smoke / Regression / Nightly」の3段ゲートです。全件を全PRで回すとコストが爆発し、逆に誰も評価を回さなくなります。雲海設計の案件では、Smokeで1PRあたり$0.5〜$2、2〜5分に収まるよう調整しています。
回帰判定のロジック
絶対閾値：correctness < 0.9 なら fail
相対閾値：mainブランチ比で -3pt 以上の劣化で fail
分散閾値：同一入力の出力分散が過去より拡大したら warn
この仕組みは AIコーディングエージェント選定ガイド で紹介した「PR作成はAI、レビューは人間」の運用と組み合わせると、エージェントが自分のPRを自分で評価する自律ループに近づきます。
業務適用のベストプラクティスは？
結論：オフライン評価だけで本番にはいけません。現場データは評価データセットと必ず分布がズレます。
オフライン→シャドー→本番の3段階ロールアウト
オフライン評価：キュレーションされた評価セットでスコアと回帰を確認
シャドー運用：本番トラフィックをエージェントに流すが、結果は出力せずログだけ取る
限定本番：一部ユーザー・一部タスクで実運用、メトリクス監視
全面展開：フィードバックループを常時稼働
特にシャドー運用で得られるログは最高の評価データセットになります。雲海設計では顧客案件ごとに、本番ログから匿名化してオフライン評価セットに還流させる仕組みを標準化しています。
オンライン指標の設計
指標 | 計測方法 | アラート閾値例 |
|---|---|---|
タスク完了率 | ツール実行成功＋ユーザー承認 | 前週比 -5% |
手動介入率 | 人間が修正/差し戻した割合 | 20%超 |
コスト/タスク | トークン×単価の集計 | 予算の120% |
暴走検知 | ループ・過剰ツール呼び出し | 即時アラート |
暴走対策は ガードレール設計の記事 と合わせて読むと、ハーネスとランタイム制御の役割分担が整理できます。
雲海設計の実践スタック
参考までに、私たちがB2B案件で標準化しているハーネス構成を公開します。
graph LR
A[Dataset
JSONL+DVC] --> B[Runner
Inspect AI]
B --> C[Scorer
Rule+LLM Judge]
C --> D[Store
BigQuery]
D --> E[CI Gate
GitHub Actions]
D --> F[Dashboard
Looker Studio]
G[Prod Logs] --> A
E --> H[PR Comment Bot]
ポイントは本番ログ（G）が評価データセット（A）に還流していることです。これがないと、評価は永遠にラボの中で完結してしまいます。
よくある質問
Q. 小さなプロジェクトでもハーネスは必要ですか？
A. 必要です。ただし4層フル構成ではなく、50件のJSONL＋pytest＋GitHub Actionsから始めれば十分です。ゼロから作るのではなく、promptfoo や Inspect AI のようなOSSを使えば1日で立ち上がります。
Q. LLM-as-Judge の精度はどう担保しますか？
A. 人手ラベルとの一致率（Cohen's kappa など）を定期的に計測します。0.6を下回る判定軸は廃止し、プロンプトを作り直します。判定モデルの“二次評価”こそハーネスの肝です。
Q. 評価コストが高騰しそうで怖いです。
A. 3段ゲートとキャッシュ戦略で制御できます。同一入力・同一プロンプト・同一モデルの組み合わせはキャッシュから返す、夜間バッチに寄せる、軽量モデルでSmokeを回すなど、設計段階で予算を組むのがベストプラクティスです。
Q. 誰がハーネスを保守するのですか？
A. 専任を置くのが理想ですが、現実にはエージェント開発者が兼任します。重要なのは「評価が壊れたらPRが通らない」という仕組みを作ること。人ではなく仕組みで保守するのがコツです。
Q. PoC段階でも導入すべきですか？
A. はい、PoCこそハーネスから作るべきです。評価なしのPoCは「動いた/動かない」の水掛け論になりがちで、意思決定ができません。最初の10件の評価セットが、後の数百件に育ちます。
おわりに
AIエージェントを業務に載せるとき、差がつくのはモデル選定でもプロンプトでもなく、ハーネスエンジニアリング ベストプラクティスをどこまで内製化できるかです。雲海設計では、AIエージェントのPoCから本番運用まで、評価ハーネスの設計・CI統合・業務適用を一気通貫で支援しています。
DXソリューション：AIエージェントの業務適用と評価基盤構築
ITコンサルティング：評価指標設計・ガバナンス策定
お問い合わせ：現行エージェントのハーネス診断（初回無料）
「評価が言語化できていない」「プロンプト改修のたびに品質が揺れる」——そんなお悩みがあれば、気軽にご相談ください。