eval-engineering

評価エンジニアリング

フロー

• すべての入力を最初に確認します。リポジトリ、Harness、任意のトレース、既存の Task と実行結果、既存の World Knowledge、および人間の目標を確認します。作業を提案する前に、該当するソースファイルとスキルの参照先を特定します。
• それらの入力に含まれる再利用可能な事実から、プロジェクト用の小規模な World Knowledge Skill を作成または更新します。それを使って、根拠に基づいた Task を 1 つ提案します。
• Task Spec と World Skill を一緒に草案として作成します。両方をユーザーに提示し、Task に関する正確な情報は Task.md のみに記載し、ユーザーの承認が得られるまで両方を修正します。
• 承認済みの Task を実装し、その Environment と Verifier を検証して、実際の Harness を実行し、証拠全体を確認します。エージェント以外の失敗のみを修正します。
• 実行結果で判明した内容を反映して World Skill を整合させた後、次の Task についてこのフローを繰り返します。

用語

• Task Spec： 1 つの Task について、入力、関連するエージェントの条件、Environment、採点、公平性、未決事項を記述した Task.md です。
• Task： 実行可能な指示、Environment、および Verifier です。
• Harness： プロンプト、モデルのループ、ツール、フック、メモリ、セッション、アダプターを含む、Harbor が実行するエージェント全体です。
• Environment： Harness を取り巻くファイル、データ、サービス、ID、権限、ネットワーク、時計、および変更可能な状態です。
• Verifier： 結果を採点するか、実行を無効と判定する独立したチェックです。
• World Knowledge Skill： Task Spec の生成と将来の Task の作成に役立つ、再利用可能なプロジェクト固有の知識、参照資料、スクリプト、アセット、テストを含む、リポジトリ内のスキルです。
• Spec2Task： レビュー済みの Task Spec を監査済みの実行可能な Task にする一連のプロセスです。具体的な構築順序と参照先については、Task の実装に従ってください。

参照先の案内

該当する判断が必要になったら、それぞれの参照資料を読んでください。

必要な内容	参照先
ソース、トレース、Harness、依存関係、アクセス権、既存の評価を確認する	ディスカバリー
再利用可能なプロジェクト知識を初期設定または更新する	World Knowledge
Task を提案し、単一の Task Spec を作成する	Task の設計
データ、サービス、アクセス権、状態、リセットを構築する	Environment の構築
構造化データまたは自然言語データを作成する	合成データ
独立した証拠と採点方法を定義する	Verifier の設計
Spec2Task を適用し、レビュー済みの Spec を監査済みの Task にする	Task の実装
モデルの実行結果を比較し、失敗を分類する	キャリブレーション
Harbor の Task をパッケージ化して実行する	Harbor
既知のベンチマーク設計を応用する	ベンチマークのパターン
複数ターンの会話を構築する	複数ターンのシミュレーション
2 つの Task を通じて得られた World Knowledge を確認する	サービスデスクの例

再利用可能な実装リソース：

• 複数ターンシミュレーション用のランナー、モデルユーザー、および Harbor アダプターの例
• 提供されたスキーマ断片を比較するツールスキーマ比較スクリプト。外部の $ref ターゲットは解決しません。
• 読み取り専用の SQLite 状態スナップショット

1. 入力と既存の World ナレッジを確認する

Task を提案する前に、ユーザーが提供するすべての入力を確認してください。利用可能な各入力に対応するガイダンスを使用します。

• リポジトリ、Harness、トレース、または依存関係については、Discovery をお読みください。
• 既存の Task と実行については、それらの指示、Environment、Verifier、報酬、トラジェクトリ、および最終状態を確認してください。実行の品質や失敗原因が新しい設計に影響する場合は、Calibration をお読みください。
• 既存のプロジェクト World Skill については、World knowledge をお読みください。その後、新しい Task に影響するソースと再利用可能なメソッドを確認してください。
• 人間の目標と制約については、Task design をお読みください。
• 関連するベンチマークの例については、Benchmark patterns のドメインインデックスとソースの注記を使用してください。

ソースとテストで答えられる質問をする前に、リポジトリを確認してください。プロンプト、モデル、ツール、サービス、状態、エフェクト、およびフォーカスされたテストを通じて、アクティブな Harness を追跡してください。既存の Task の指示、パーサー、Verifier、報酬パス、および実行の証拠を確認してください。

ユーザーがトレースを提供する場合は、完全な実行またはスレッドを確認してください。トレースを使用して、実際のリクエスト、依存関係の動作、状態の形状、エラー、および失敗条件を学んでください。トレースの回答を独立した真実として扱わないでください。

.agents/skills/<project>-world/SKILL.md が存在する場合は、それを読んでください。現在の Task に関連するナレッジについてのみ、そのルーティングに従ってください。引用されたリポジトリのパス、コマンド、およびスクリプトが設計に影響する場合は、それらの正確性を確認してください。

2. Task を提案して選択する

Task design を読み、Benchmark patterns のインデックスを使用して、関連するドメインとソースの注記を見つけてください。Task が別のドメインにまたがる場合を除き、そのドメインに焦点を当ててください。確認後の最初のユーザー向け設計レスポンスで、リポジトリの証拠、提供されたトレース、既存のカバレッジ、または人間の優先事項に基づいた 1 つの Task を提案してください。次のことを述べてください。

• 実際の作業と能力。
• そのケースを非自明にする条件。
• それが必ずしも必要とする Environment と独立した証拠。
• それが検出できる重要な失敗。
• 既存の Task との違い。
• 主な未解決の決定事項。

同じレスポンスで、関連する現在の World Skill の内容と、この Task が提案する具体的な追加または修正を示してください。World Skill が存在しない場合は、この Task と将来の Task の作成に役立つ小さな初期内容を示してください。Task の正確なリクエスト、焦点となるレコード、期待される結果、隠された真実、および正確なスコアリングルールは World Skill に含めないでください。

実装前に、ユーザーが Task の提案と World ナレッジを一緒に修正できるようにしてください。実際のユーザーの選択が設計を変える場合にのみ、代替案を提示してください。

3. Task Spec と World Skill を作成してレビューする

Task テンプレートを evals/<suite>/tasks/<task-id>/Task.md にコピーします。Task 固有の設計はすべて、この 1 つのファイルにまとめます。同時に、World knowledge に従って プロジェクトの World Skill を作成または更新します。アクティブなエージェントとリポジトリが サポートするプロジェクトのスキルの場所を確認します。 .agents/skills/<project>-world/SKILL.md と .claude/skills/<project>-world/SKILL.md が一般的な配置先です。プロジェクトに既存の 慣例があれば、それに従います。慣例がない場合は、提案する配置先を説明し、スキルを作成する前に ユーザーの確認を得ます。必要に応じて、World Skill テンプレートから 始めます。

各 Task.md は、それが説明する Harbor タスクの隣に置きます。

evals/<suite>/tasks/<task-id>/
├── Task.md              # human-reviewed control-plane spec
├── task.toml             # required Harbor configuration
├── instruction.md        # required agent input
├── environment/          # required Environment definition and visible state
│   ├── Dockerfile        # use this or docker-compose.yaml
│   └── docker-compose.yaml # optional; primary service must be main
├── tests/
│   ├── test.sh           # required Harbor Verifier entry point
│   ├── test_*.py         # optional Verifier helpers
│   └── fixtures/         # optional hidden Verifier data
└── solution/
    └── solve.sh          # optional reference path

評価対象のエージェントのワークスペースやイメージに Task.md をコピーしたり、マウントしたりしないでください。 エージェントに渡すのは instruction.md と、その実行用として意図された Environment の状態のみです。

以下を含めます。

• 目的と根拠となる情報源；
• 正確な入力と後続のターン；
• この Task に関連する Harness の条件のみ；
• 初期状態、サービス、アクセス、可視性、リセット、実運用との差異；
• 必須の結果、禁止される影響、許容される代替案、独立した Verifier の証拠；
• 公平性、情報漏えいのリスク、無効な実行条件；および
• 未決事項と前提。

Task Spec の全文と World Skill の変更内容をユーザーに提示します。すでに World Skill に含まれている内容、この Task が追加または修正する内容、Task.md のみに記載する内容を説明します。やり取りを重ねながら、両方を改訂します。明示的な承認を得てから、Task Spec を承認済みにします。World Skill の変更は、ユーザーがレビューした後にのみ受け入れられたものとします。ユーザーから承認待ちなしで最初から最後までの構築を依頼された場合は、エージェントによるレビューを行ったうえで Status: Draft のまま続行し、World Skill の変更には未レビューであることを明記します。

実装によって依頼内容、表示情報、Environment の重要な挙動、またはスコアリングの境界が変わる場合は、Task.md を更新して変更内容を提示します。ステータスを Draft に戻します。差分を示し、ステータスを再び Approved にする前に、明示的な再承認を求めます。

4. Spec2Task を適用する

Task implementation に従います。構築の順序が記載されており、各判断を Environment、合成データ、Verifier、Harbor、およびキャリブレーションに関するリファレンスへ案内しています。

既存のプロジェクトでは、固定済みまたはサポート対象の Harbor バージョンを使用します。それ以外の場合は、インストール済みのサポート対象バージョンを使用して記録します。ユーザーの承認と明示した互換性上の理由がある場合に限り、アップグレードします。コマンドの仕様には、インストール済み CLI のヘルプを使用します。

スコア対象のモデル実行の前に、次を行います。

1. ユーザーがすでに実行計画を承認している場合を除き、モデル、試行回数、ジャッジ、タイムアウト、想定される最大コストをユーザーに確認します。
2. Harbor のパッケージ監査を完了します。この Task に必要なすべてのファイル、エントリーポイント、パス、権限、設定値、マウント、サービス、報酬出力が揃っており、Harbor を通じて動作することを確認します。非公開の Task、Verifier、ソリューション、秘密情報が、エージェントから見えるイメージやワークスペースに含まれていないことを確認します。
3. Environment に適した方法で、セットアップと試行の分離を確認します。新しいコンテナまたはワークツリーは、置き換えによって分離できます。再利用される変更可能なサービスには、確認済みのリセットが必要です。変更不可の凍結データには、読み込みの確認だけが必要です。Task implementation を参照してください。
4. Task が依存するすべての操作を実行して確認します。
5. 参照経路がある場合は、それを実行します。
6. Verifier を、明確に有効な結果、有効な代替結果、現実的な誤った結果、抜け道、禁止された付随的変更、および証拠の欠落や破損を用いてテストします。
7. Verifier の完了したすべての経路で、非公開の正解や秘密情報を漏らすことなく、有効な報酬と有用な証拠が出力されることを確認します。

5. 実行と監査

Harbor を通じて実際の Harness を実行します。報酬だけでなく、軌跡全体を読みます。次の点を調査します。

• メッセージ、モデル呼び出し、ツール呼び出し、結果、再試行、エラー。
• Environment の初期状態と最終状態、および外部への影響。
• サービス、セットアップ、準備状態、リセット、クリーンアップの証拠。
• Verifier の各基準、それに関する証拠、判定、エラー。
• 解決済みの Harness、モデル、Environment、判定設定。

失敗した各実行を、エージェントの能力不足、情報不足、Harness の不具合、Environment の不具合、Verifier の誤った拒否、Verifier の誤った受け入れ、情報漏えい、インフラストラクチャの障害のいずれかに分類します。スコアを利用する前に、エージェント以外に起因する失敗を修正します。

モデル比較は任意のキャリブレーション戦略であり、完了条件ではありません。実際の不確実性を解消できる場合は、より弱いモデル、対象モデル、またはより強いモデルを比較し、動作にばらつきがある場合は試行を繰り返します。選択したトレースはすべて読みます。比較により、入力の不明確さ、脆弱なセットアップ、情報漏えい、近道、報酬の不正利用が明らかになることがあります。合格率やモデルの順位だけでは、Task の品質を証明できません。

監査方法の全容については、キャリブレーションを参照してください。

6. プロジェクトの World 知識を調整する

Task の設計、実装、監査を通じて、World 知識を活用します。別の Task に役立つ証拠が作業から得られた場合は、プロジェクト固有の知識を追加または修正します。これには、Task のパターン、Environment の手法、データの作成、Verifier の証拠、実行手順、スクリプト、アセット、例などが含まれます。

監査後、完了した Task で実証された内容に合わせて World Skill を調整します。ユーザーには次の内容を提示します。

• 再利用可能な知識の提案。
• その根拠となる証拠。
• 別の Task での活用方法。
• その情報を配置すべき場所。
• 完了した Task 固有の要素。

Task によって否定されたアイデアは削除するか、適用範囲を狭めます。ユーザーから中断なしの自律的なエンドツーエンド更新を依頼された場合は、証拠に裏付けられた最小限の更新を行い、最終レビューで示します。また、人間がその一般化を承認したかのように示してはいけません。

まずは SKILL.md のみを作成します。実際の内容が必要性を裏付ける場合に限り、references/、scripts/、assets/、tests/ を追加します。

完了した Task の依頼内容、焦点となる状態、期待される結果、厳密な基準は、同じ場所にある Task.md に記録します。このスキルですでに明確な広範なガイダンスはコピーしないでください。そのガイダンスをプロジェクト向けにどのように適用したかを記録します。

7. 繰り返す

Task 2 と 3 を使って World Skill を検証します。再発見の削減、Task Spec の改善、重要な関係性の維持、実証済みの操作の再利用、既知の Verifier の不具合の防止につながっているかを確認します。不足している、古くなっている、または適用範囲が広すぎるルールを修正します。

複数の大きく異なる Task で共有知識が試され、構築方法と検証方法が明確になったら、次のサイクルでは複数の独立した Task Spec を提案できます。

1. 新たなリポジトリ、トレース、人間による証拠を収集します。
2. World Skill を使って、異なる Task Spec を生成します。
3. 人間に Spec をレビューしてもらいます。
4. 承認された独立した Task を並行して構築します。
5. 各 Task を個別に監査します。
6. 再利用可能な修正だけを World 知識に反映します。

本番環境の動作、ユーザーの優先事項、エージェント、モデルの変化に合わせて、このループを続けます。

依存関係、アクセス、安全性

必要なシステム、データ、役割、ネットワーク要件、安全なセットアップ方法を整理します。秘密の値を読み取ったり、表示、コピー、保存したり、人間に貼り付けを依頼したりしてはいけません。必要な依存関係、その理由、プロジェクトで想定されるアクセス方法を人間に伝えます。制御されたローカル環境、固定環境、またはシミュレートされた依存関係を優先します。評価中に本番環境へ書き込みを行ってはいけません。アクセス、起動、リセット、タイムアウト、判定、Verifier の失敗は、エージェントの失敗ではなく無効な実行として扱います。

完了条件

• Task.md が、構築された指示、環境、検証ツールと一致していること。
• タスクが、エージェントから見える情報、または通常発見できる情報に基づいて解決できること。
• 環境が、必要に応じて置き換え、リセット、または不変の状態によって試行を確実に分離し、隠された真実を漏らさないこと。
• 検証ツールが、有効なケースと無効なケースで意図どおりに動作すること。
• 実際のハーネス実行を少なくとも1回、全編確認していること。
• エージェントに起因しない障害が修正されているか、未解決の制限事項として報告されていること。
• モデル比較を行う場合、合格率だけでなくトレースも確認していること。
• プロジェクトのワールドスキルがタスク仕様とともに作成または更新され、作業中に確認され、最終的な証拠と整合していること。
• ユーザーにタスクのパス、実行コマンド、結果、証拠、残る制限事項が提示されていること。