Eval Harness スキル
Claude Codeセッション向けの形式的評価フレームワーク。評価駆動開発（EDD）の原則を実装します。
使用するタイミング
- AI支援ワークフローに評価駆動開発（EDD）を設定する場合
- Claude Codeのタスク完了に対する合格/不合格基準を定義する場合
- pass@kメトリクスでエージェントの信頼性を測定する場合
- プロンプトやエージェントの変更に対する回帰テストスイートを作成する場合
- モデルバージョン間でのエージェントパフォーマンスをベンチマークする場合
哲学
評価駆動開発（EDD）は、評価を「AI開発における単体テスト」として扱います：
- 実装の前に期待される動作を定義する
- 開発中に継続的に評価を実行する
- 各変更で回帰を追跡する
- pass@kメトリクスで信頼性を測定する
評価の種類
Capability Eval（能力評価）
Claudeが以前できなかったことを実行できるかテストする：
[CAPABILITY EVAL: 機能名]
タスク: Claudeが達成すべきことの説明
成功条件:
- [ ] 条件1
- [ ] 条件2
- [ ] 条件3
期待される出力: 期待される結果の説明
Regression Eval（回帰評価）
変更が既存機能を壊していないことを確認する：
[REGRESSION EVAL: 機能名]
ベースライン: SHAまたはチェックポイント名
テスト:
- 既存テスト1: PASS/FAIL
- 既存テスト2: PASS/FAIL
- 既存テスト3: PASS/FAIL
結果: X/Y 合格（以前は Y/Y）
評価方法の種類
1. コードベース評価
コードを使用した決定論的チェック：
# ファイルに期待されるパターンが含まれているかチェック
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"
# テストが通るかチェック
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"
# ビルドが成功するかチェック
npm run build && echo "PASS" || echo "FAIL"
2. モデルベース評価
Claudeを使用して自由形式の出力を評価する：
[MODEL GRADER PROMPT]
以下のコード変更を評価してください：
1. 問題を解決していますか？
2. 構造は適切ですか？
3. エッジケースは処理されていますか？
4. エラーハンドリングは適切ですか？
スコア: 1-5（1=悪い、5=優秀）
理由: [説明]
3. 人手評価
手動レビューのためにフラグを立てる：
[HUMAN REVIEW REQUIRED]
変更: 変更内容の説明
理由: 人手レビューが必要な理由
リスクレベル: LOW/MEDIUM/HIGH
メトリクス
pass@k
「k回の試行で少なくとも1回成功」
- pass@1: 1回目の試行成功率
- pass@3: 3回以内の成功
- 典型的な目標: pass@3 > 90%
pass^k
「k回すべての試行が成功」
- 信頼性に対するより高い基準
- pass^3: 3回連続成功
- クリティカルパスに使用
評価ワークフロー
1. 定義（コーディング前）
## EVAL DEFINITION: 機能-xyz
### Capability Evals
1. 新しいユーザーアカウントを作成できる
2. メール形式を検証できる
3. パスワードを安全にハッシュ化できる
### Regression Evals
1. 既存のログインが引き続き機能する
2. セッション管理が変更されていない
3. ログアウトフローがそのまま機能する
### 成功メトリクス
- Capability Evals: pass@3 > 90%
- Regression Evals: pass^3 = 100%
2. 実装
定義された評価に合格するコードを書く。
3. 評価
# Capability Evalsを実行
[各Capability Evalを実行し、PASS/FAILを記録]
# Regression Evalsを実行
npm test -- --testPathPattern="既存"
# レポートを生成
4. レポート
EVAL REPORT: 機能-xyz
========================
Capability Evals:
ユーザー作成: PASS (pass@1)
メール検証: PASS (pass@2)
パスワードハッシュ化: PASS (pass@1)
合計: 3/3 合格
Regression Evals:
ログインフロー: PASS
セッション管理: PASS
ログアウトフロー: PASS
合計: 3/3 合格
メトリクス:
pass@1: 67% (2/3)
pass@3: 100% (3/3)
ステータス: レビュー準備完了
統合パターン
実装前
/eval define 機能名
.claude/evals/機能名.md に評価定義ファイルを作成します。
実装中
/eval check 機能名
現在の評価を実行し、ステータスを報告します。
実装後
/eval report 機能名
完全な評価レポートを生成します。
評価の保存
プロジェクト内に評価を保存する：
.claude/
evals/
機能-xyz.md # 評価定義
機能-xyz.log # 評価実行履歴
baseline.json # 回帰ベースライン
ベストプラクティス
- コーディング前に評価を定義する - 成功基準について明確に考えることを強制する
- 頻繁に評価を実行する - 回帰を早期に発見する
- 経時的にpass@kを追跡する - 信頼性の傾向を監視する
- 可能な限りコードベース評価を使用する - 決定論的 > 確率的
- セキュリティは人手レビュー - セキュリティチェックを完全に自動化しない
- 評価を高速に保つ - 遅い評価は実行されなくなる
- 評価をコードと一緒にバージョン管理する - 評価は第一級の成果物である
例：認証機能の追加
## EVAL: 認証機能の追加
### フェーズ1: 定義（10分）
Capability Evals:
- [ ] ユーザーがメール/パスワードで登録できる
- [ ] ユーザーが有効な認証情報でログインできる
- [ ] 無効な認証情報は適切なエラーで拒否される
- [ ] セッションがページリロード後も持続する
- [ ] ログアウトでセッションがクリアされる
Regression Evals:
- [ ] 公開ルートが引き続きアクセス可能
- [ ] APIレスポンスが変更されていない
- [ ] データベーススキーマに互換性がある
### フェーズ2: 実装（変動）
[コードを書く]
### フェーズ3: 評価
実行: /eval check 認証機能の追加
### フェーズ4: レポート
EVAL REPORT: 認証機能の追加
==============================
Capability: 5/5 合格 (pass@3: 100%)
Regression: 3/3 合格 (pass^3: 100%)
ステータス: リリース可能
ローカルフレームワークユーティリティ
機械的なユーティリティは scripts/lib/eval-harness/ に同梱されています：
node scripts/eval-harness.js example
- Capsule: ハッシュリンクされたジャーナルで、5つの系統とローカル整合性チェックを持ちます。
- Inspection: ソースダイジェスト、検証済みバリアントパス、および構文警告。
- Replay: 宣言されたツールとコンテンツアドレス指定されたフィクスチャ。不足しているフィクスチャはクローズドに失敗します。SE3以上はリプレイで拒否されます。レコードモードは登録された実装を呼び出すため、信頼できる関数のみを登録してください。
- Receipt: カプセルとアーティファクトのバイトをオフラインで検証し、名前付きチェックを行います。
- Retrospective preparation:
node scripts/eval-harness.js capsule group <dir> [<dir> ...]は、1から100までの明示的に選択された、検証済みのローカルカプセルスナップショットを1つのタスクファミリーから宣言されたハーネスバージョンでグループ化します。重複したスナップショットは1回としてカウントされ、競合するIDや無効なカプセルはレポート全体を拒否します。これは読み取り専用のレコードカウントであり、新しいロールアウト、スコア、プロモーションは含まれません。小さくて静的なカプセルを使用してください。ペイロード、ディレクトリ引数、および生の実行/カプセルIDは省略されますが、タスクファミリー/バージョンラベルはそのまま表示され、ダイジェスト参照はリンク可能です。共有する前にそれらをレビューしてください。運用上の検証は保留中です。
検証済みのOSコンテインメントバックエンドが実装されていないため、すべてのOSで候補の実行は無効になっています。gate run、runGate、runVariant、直接の子プロセス起動、および廃止されたエフェクトプリロードは、gate.isolation_required で拒否されます。信頼フラグや呼び出し元が提供するexecutorはこの拒否を回避できません。この例ではその拒否を記録し、ソースを実行やスコアリングなしで検査します。
静的な警告、カプセルのレシート、または成功したユーティリティテストを、候補のコンテインメントやプロモーションの証拠として提示しないでください。将来のゲートには、独立してレビューされたOS境界、保護されたチェッカーと監査チャネル、および致命的なベースライン拒否が必要です。docs/architecture/eval-harness-frameworks.md を参照してください。
プロダクト評価（v1.8）
単体テストだけでは振る舞いの品質を捉えられない場合に、プロダクト評価を使用します。
評価方法の種類
- コード評価（決定論的アサーション）
- ルール評価（正規表現/スキーマ制約）
- モデル評価（LLM-as-Judge ルーブリック）
- 人手評価（曖昧な出力に対する手動判定）
pass@k ガイダンス
pass@1: 直接的な信頼性pass@3: 制御された再試行下での実用的な信頼性pass^3: 安定性テスト（3回すべての実行が合格する必要がある）
推奨しきい値:
- Capability Evals: pass@3 >= 0.90
- Regression Evals: リリースクリティカルパスでは pass^3 = 1.00
評価のアンチパターン
- 既知の評価例にプロンプトを過学習させる
- ハッピーパス出力のみを測定する
- pass率を追求する一方で、コストとレイテンシの変動を無視する
- リリースゲートに不安定な評価を許可する
最小限の評価アーティファクト構成
.claude/evals/<機能>.md定義.claude/evals/<機能>.log実行履歴docs/releases/<バージョン>/eval-summary.mdリリーススナップショット