Evals

Evals — アサーション優先の AI 評価

概要

eval では、AI に入力を与え、その出力にアサーションを適用して成功度を測定します（Anthropic の定義）。ケースは {id, prompt, assert:[...]} です。各アサーションは、決定論的（コードによる判定、高速・無料）またはモデル採点式（LLM ジャッジ）のいずれかです。各ケースは複数回試行され、pass^k（すべての試行が合格。信頼性が重要なエージェントにとって、誠実な指標です）と pass@k（いずれかの試行が合格）を報告します。すべて Inference.ts を経由します。課金はサブスクリプション経由で、API キーを使う経路はなく、外部依存もありません。

Anthropic の現在の指針に基づいています。Demystifying evals for AI agents、Define success criteria / develop tests、および skill-creator の {text, passed, evidence} アサーション規約を参照してください。型付きアサーションレイヤーは promptfoo を参考にしていますが、TS は独自のものです。

鮮度に関する取り決め：「Anthropic の指針に沿っている」というのは、現時点での主張であり、ある時点のスナップショットではありません。新しいスイートクラスを設計するときや、以下の ## Doctrine セクションに手を加えるときは、Demystifying-evals のドキュメントを再取得し、ここに反映されている内容から変わった箇所を報告してください。これは助言のみです。相違点を報告し、自動的に採用してはいけません。また、URL にアクセスできなくても実行を妨げてはいけません。

正規のパス（v2）

ツール	役割
Tools/Assertions.ts	決定論的なアサーションエンジン：equals、contains、icontains、contains-all/any、regex、starts-with、ends-with、is-json、contains-json、max-length、min-length。それぞれに not- による否定があります。同期処理で、モデル呼び出しはありません。
Tools/Judge.ts	モデル採点式アサーション llm-rubric（1～5 → 0～1、しきい値）と llm-assert（自然言語アサーション → TRUE/FALSE/UNKNOWN）。構造化 JSON の判定を強制し、理由を述べてから採点します。ジャッジレベルは個別に設定され、Unknown→miss の回避策があります。
Tools/EvalRunner.ts	スイートを読み込み、ケースごとにテスト対象エージェントを実行します（対象システムプロンプトに対する単発推論）。アサーションを適用し、pass^k/pass@k を計算して、トランスクリプトと latest.json を保存します。
Tools/SuiteManager.ts	スイートの一覧表示と飽和度の追跡。
Tools/FailureToTask.ts	実際の失敗をケースに変換します（実際の失敗を 20～50 件シードとして使用）。

# Run a suite (USER-customization suites resolve before the skill's own)
bun run ${LIFEOS_SKILL_DIR}/Tools/EvalRunner.ts -s <suite> [-t trials] [--json]
# Sanity-check the assert engine / judge
bun run ${LIFEOS_SKILL_DIR}/Tools/Assertions.ts     # 16-case self-test
bun run ${LIFEOS_SKILL_DIR}/Tools/Judge.ts          # good-vs-bad discrimination

ワークフローの振り分け

ワークフロー	トリガー	ファイル
RunEval	「eval を実行」「スイートを実行」「これを評価」「出力を採点」	Workflows/RunEval.md
CreateUseCase	「新しい eval」「スイートを作成」「X 用の eval」「何をテストすべきか」	Workflows/CreateUseCase.md
CreateJudge	「ジャッジを書く」「llm-rubric」「採点基準」「ジャッジプロンプト」	Workflows/CreateJudge.md
ComparePrompts	「プロンプトを比較」「どちらのプロンプトがよいか」「このプロンプトを A/B テスト」	Workflows/ComparePrompts.md
CompareModels	「モデルを比較」「どちらのモデルがよいか」「より安価な段階で十分か」	Workflows/CompareModels.md
ViewResults	「eval の結果」「スコアはどうだったか」「直近の実行結果を表示」「飽和度」	Workflows/ViewResults.md
CreateScenario	「シナリオを作成」「マルチターン eval」「シナリオテスト」	Workflows/CreateScenario.md
RunScenario	「シナリオを実行」「マルチターンを実行」	Workflows/RunScenario.md

スイート／ケースのスキーマ（アサーション優先）

name: my-suite
type: regression            # or capability
pass_threshold: 0.75
agent_level: medium         # agent-under-test inference level
judge_level: high           # judge != generator (Anthropic best practice)
trials: 3
# system_prompt: optional override; default = live system prompt + DA identity
cases:
  - id: descriptive_name
    prompt: "the user turn sent to the agent-under-test"
    assert:
      - type: not-contains       # deterministic
        value: "should work"
        weight: 1
      - type: llm-rubric         # model-graded, weighted for partial credit
        weight: 2
        value: "Does the output tie any done-claim to verification evidence?"
      - type: llm-assert
        weight: 1
        value: ["The output does not claim success without evidence"]
  - id: should_not_case          # balance: test should-do AND should-not
    negative: true
    prompt: "..."
    assert: [...]

ID に紐づくスイート（例：{{DA_NAME}} の性向）は LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Evals/Suites/ に格納されます。公開スキルに含まれるのは、汎用スイートと例のみです。

Doctrine（Anthropic より — 言い換えずに反映）

• 経路ではなく、出力／結果を評価します。 ツール呼び出しシーケンスのアサーションは壊れやすいため、オプトインに格下げされています。通常のスイートではエージェントが生成した内容を評価します。従来の core-behaviors スイート（ツールシーケンスを評価）は、このアンチパターンの例としてのみ保持されています。これは v1 の tasks: ファイルであり、EvalRunner では実行できません。実行を試みるのではなく、名前付きエラーとして報告されます。
• 能力は低いところから始まります（登るべき坂です）。回帰の目標は約 100％です。合格した能力ケースは卒業して回帰に加わります。
• 信頼性には pass^k を、1 回の成功で十分な場合は pass@k を使います。
• アサーションの重み付けで部分点を付けます。すべきことと、すべきでないことのケースをバランスよく扱います。一方に偏った評価は、一方に偏った最適化を招きます。
• ジャッジの規律： 別個のジャッジモデルを使い、理由を述べてから採点し、構造化された判定を必須とし、Unknown の逃げ道を設けます。
• トランスクリプトを読むまでは、スコアを決して信用しないでください。 各実行では、すべてのケースの完全なトランスクリプトが MEMORY/STATE/Evals-Results/<suite>/<run>/run.json に保存されます。

ハーネス統合

• 設定変更時の回帰： hooks/ConfigEvalFire.hook.ts → LIFEOS/TOOLS/ConfigEvalOnChange.ts は、動作を定義するファイルが変更されると、設定済みのディスポジションスイート（デフォルトは実行可能な v2 スイート core-dispositions）を実行します。LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Evals/config.json の config_change_suite で上書きできます。アイデンティティに紐づくスイートは USER レイヤーに置き、公開ツリーには決して置きません。回帰は Pulse に通知されます。ノンブロッキングで、サブスクリプション課金、デバウンスありです。
• ISA／アルゴリズム： 評価スイートは、ISA の主張に対する反証可能性を運用可能な形にしたものです（統合マップはメンテナーのマシンに保持され、セッションノートに記載されており、配布されません）。

レガシー（v1、置き換え済み）

v1 のグレーダースタック（Graders/、TrialRunner.ts）と @langwatch/scenario の経路（ScenarioRunner.ts、LifeosAgentAdapter.ts、API 課金）は、アサーションファーストの書き換えより前のものです。上記の v2 経路を優先してください。シナリオ経路では ANTHROPIC_API_KEY が課金対象となるため、主要な作業には使用しないでください。

注意点

• テスト対象のシングルショットエージェントは、ツール呼び出しを語ります。 ツールなしの推論でエージェントのシステムプロンプト全体を実行すると、エージェントは回答する代わりに応答を先延ばししてツール使用を模擬するため、「答えを先に述べる」スタイルのケースの評価が大きく下がります。EvalRunner はこれを修正するため、[EVALUATION CONTEXT] no tools, answer directly というサフィックスを追加します。出力を評価するディスポジションケースを作成する際は、これを維持してください。
• judge_level は agent_level と異なる必要があります（Anthropic：ジャッジ ≠ 生成モデル）。デフォルトは agent=medium、judge=high です。
• Unknown は不合格として数えられます。 ジャッジがアサーションを検証できない場合は UNKNOWN を返し、不合格として採点されます。これは回帰には保守的で、ゲートには適切です。
• 決定論的なアサーションは無料なので、まず使ってください。 コードチェックでは捉えられない細かな違いに限り、モデルアサーション（llm-rubric／llm-assert）を使います。
• is-json は出力全体をチェックし、contains-json は埋め込まれた断片をチェックします。 JSON に言及しているだけの文章に is-json を使わないでください。

実行ログ

ワークフローの完了後、JSONL エントリを 1 つ追記します。

echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Evals","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' >> ~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl