eval-harness-first

まず Eval ハーネス

プラグイン全体における Phase 0 のゲートです。 finetuning-method-selection とその下流のすべての スキルは、トレーニング設定が書かれる前にこのハーネスが 存在することを前提としています。ハーネスは実行終了時の 副産物ではなく、データキュレーションエンジンです。 ゴールデンを作成するのと同じラベル付きトレースが、 明示的なホールドアウトを除いて、トレーニングデータにも 供給されます。

入力: 存在する場合は本番/エージェントのトレース、 存在しない場合はタスク仕様、加えて 100 件以上の 例を採点する意思のあるラベラー。 出力形式: 以下の eval/ ディレクトリ — ゴールデン、グレーダー、ドリフトスイート、そして 後のフェーズがゲートするベースモデルのベースライン。

ゲート

Eval ハーネスがなければ、ファインチューニングもありません。 トレーニング設定に飛んでしまうと、比較対象もなく、 リグレッションを捉えるものもなく、トレーニングするための ラベル付きデータもありません。フライホイール:

1. トレースを収集する — 本番/エージェントのスパン、 まだ存在しない場合は合成タスク。
2. エラー分析 — 100 件以上のトレースに対してオープン コーディングを行い、軸索コーディングで 4〜8 個の 失敗バケットにまとめます。
3. バケットごとに 1 つのグレーダー — まず決定的なもの。 本当に主観的な基準にのみ、キャリブレーション済みの LLM ジャッジを使います。
4. 優先順位付け — 頻度 × 深刻度 × 価値で行います。
5. ラベル付きトレースは、明示的なホールドアウトを除いて データセットキュレーションに供給されます。 すべての eval/goldens.jsonl の ID は、ID によってトレーニング データから除外され続けます。
6. トレーニング。
7. 同じハーネスをチェックポイントで再実行する — 別の、より緩いハーネスではありません。
8. ドリフト検出がステップ 2 にフィードバックされる — 新たな本番の失敗モードがエラー分析を再開させます。

ステップ 2〜4 がハーネスを構築し、ステップ 5〜8 が それが最初に存在しなければならない理由です — それは トレーニングデータのソースであり、チェックポイントの 出口ゲートでもあります。

ゴールデンの構築

• トレースが存在する場合は、トレースから: エラー分析を 実行します — 100 件以上の実際のトレースに対してオープン コーディングを行い(それらを読み、自分の言葉で失敗を タグ付けし、まだ固定のタクソノミーは使いません)、次に 軸索コーディングでそれらのタグを 4〜8 個の名前付き失敗 バケットにまとめます。4 個未満はコーディングパスが 浅すぎたことを意味し、8 個を超えるとバケットを統合する 必要があります。例外: 単一の失敗面を持つタスク (例: 厳密なスキーマ抽出)では、1〜2 個のバケットに着地 し、1 つのグレーダー内にフィールドごとのサブメトリクスを 持つ場合があります — 根拠のない人為的な分割をでっち上げ ないでください。
• トレースがまだ存在しない場合は、合成: 次元ベースの 生成 — 重要な軸(タスク種別、難易度、エッジケース、 ペルソナ)を列挙し、その直積をサンプリングします。 自由生成のプロンプトは、書くのが最も簡単なものの周りに クラスタリングします。
• ゴールデンはコードのようにバージョン管理されます — eval/goldens.jsonl をコミットし、レビューで差分を確認 し、リリースごとにタグ付けします。これは CI リグレッション スイートも兼ねます。

グレーダー

エラー分析から得られた失敗バケットごとに 1 つのグレーダー — eval セット全体に 1 つではありません。単一の混ぜ合わされた スコアは、どのバケットがリグレッションしたかを隠します。

• まず決定的なもの。 正規表現、スキーマ検証、または 実行チェックは、より安価で、再現可能で、キャリブレーション が不要です。
• LLM ジャッジは本当に主観的な基準にのみ — トーン、 忠実性、「どちらの応答がより良いか」 — 決定的なチェックが それを表現できない場合です。
• Likert よりも二値の合格/不合格。 1〜5 や 1〜10 の スケールは、キャリブレーションのノイズが多く、一貫して 適用するのが難しいです。合格/不合格に集約してください。
• ドリフトスイートの MMLU 形式スコアリング: 生成して 抽出するよりも logprob を優先する — 厳しいトークン 予算は、前置きを入れるモデルにとって生成して抽出する 方式をパース的に脆くし、フォーマット遵守と測定対象の 知識を混同させます。4 つのグレーダーの形すべての テンプレートとこのスコアリングに関する注記: references/grader-templates.md。

ジャッジのキャリブレーションは前提条件

LLM ジャッジにルーティングされるバケットが少しでもあるなら、その判定が探索以上の意味を持つ前にキャリブレーションが必要です。これは必須の前提条件であり、あると嬉しいものではありません。ジャッジにルーティングされるバケットがない場合は N/A — すべてが決定的なハーネスにはキャリブレーションすべきものが何もありません。このセクションを未対応のままにするのではなく、その旨を明記してください。

• 100 件以上の項目にラベルを付け、train/dev/sealed test に分割します（一度だけ報告し、その後は再び触れないでください）。
• 単一の合成精度数値ではなく、TPR と TNR を報告してください — ジャッジは偏ったセットで常に「pass」と言うだけで 90% を達成できてしまいます。
• ジャッジを固定のモデルスナップショットにピン留めし、ジャッジモデルの変更時および四半期ごとに無条件で再キャリブレーションしてください。
• ジャッジは、テスト対象のモデルとは異なるモデルファミリーのものでなければなりません。
• 合意された TPR/TNR の基準を満たさないジャッジは advisory-only（助言的のみ）として出荷されます — 人間によるレビュー用のフラグであり、昇格をゲートすることは決してありません。完全なプロトコル、バイアス補正、再キャリブレーションチェックリストは references/judge-calibration.md にあります。

ベースライン

フェーズ 1（手法の選定）が始まる前に、完全なハーネス — goldens に加えて capability-drift スイート — を未修正のベースモデルに対して実行してください。これが、以降のすべてのチェックポイントが比較される基準となる数値です。

eval/baseline-<model>.json がゲートトークンです。ベースラインファイルがなければ、checkpoint-promotion の比較基準もありません — 何も測定していない状態で「より良く見える」チェックポイントは発見ではありません。

ディレクトリ契約

eval/
├── goldens.jsonl          # labeled traces + synthetic goldens, versioned
├── graders/                # one module per failure bucket
│   ├── schema_compliance.py
│   ├── exact_match.py
│   └── rubric_judge.py
├── drift-suite.yaml        # frozen benchmarks + 200-500 domain-adjacent items
└── baseline-<model>.json   # gate token: harness + drift suite vs the base model
runs/
└── <run-id>/
    └── results.json         # per-run harness output, one per checkpoint

eval/ は実行をまたいで永続化され、runs/ の外に置かれます — 固定された物差しであり、実行の成果物ではありません。runs/ は使い捨てですが、eval/ はそうではありません。実行スクリプトに eval/ へ書き込ませないでください。正規の場所: トレースごとのすべての results.json（フェーズ 0 のベースラインを含む）は runs/<run-id>/results.json に置かれ、eval/runs/... の下に置かれることは決してありません。後者を要求する指示は誤りであり、この契約は誤りではありません。

フェーズ 0 終了チェックリスト

finetuning-method-selection の前に、次を確認してください。

1. 100 件以上のトレースをオープンコーディング済み。4〜8 個の失敗バケット（単一の失敗面を持つタスクにおける合成 goldens の N/A 下限 — Building Goldens の例外を参照。その場合のバケット数は代わりにベースライン後のエラー分析から得られます）。
2. eval/goldens.jsonl がコミットされ、バージョン管理されている。
3. バケットごとに 1 つのグレーダー、まず決定的なもの。
4. ジャッジがキャリブレーション済み — TPR/TNR、スナップショットをピン留め、異なるファミリー（LLM ジャッジにルーティングされるバケットがない場合は N/A。その旨を明示してください）。
5. eval/drift-suite.yaml が凍結されている。
6. eval/baseline-<model>.json が書き込まれている。

この 6 つのいずれか（または明記された N/A）が欠けていますか？ それならフェーズ 0 は完了していません — /finetune は実行前にベースラインファイルを確認します。

関連スキル

汎用の評価ガイダンス（ダッシュボード、A/B テスト、ファインチューニング以外のハーネス）は、llm-application-dev プラグインの llm-evaluation スキルにあります — このスキルはファインチューニングとの結合部分のみを扱います。すなわち、トレーニングデータを兼ねる goldens と、チェックポイントをゲートするベースラインです。

• finetuning-method-selection — 最初にここへルーティングされます。
• dataset-curation — これらのトレースをトレーニング行に整形します。
• trace-to-training-data — 採点済みトレースをトレーニング例に変換します。
• checkpoint-promotion — baseline-<model>.json を消費し、各候補チェックポイントでこのハーネスを再実行します。

参考資料

• references/grader-templates.md — 形状ごとの実行可能なグレーダー例、および drift-suite.yaml の例と MMLU の logprob スコアリングに関する注記。
• references/judge-calibration.md — キャリブレーションプロトコル。すべてが決定的な場合の N/A パスを含みます。