Eval Harness Skill

Claude Code セッション向けの正式な評価フレームワーク。eval-driven development (EDD) の原則を実装しています。

有効化するタイミング

• AI支援ワークフロー向けの eval-driven development (EDD) をセットアップする場合
• Claude Code タスク完了の合格/不合格基準を定義する場合
• pass@k メトリクスでエージェント信頼性を測定する場合
• プロンプト変更またはエージェント変更向けの回帰テストスイートを作成する場合
• モデルバージョン間でエージェントパフォーマンスをベンチマークする場合

哲学

Eval-Driven Development は eval を「AI開発の単体テスト」として扱います:

• 実装の前に予期される動作を定義する
• 開発中に継続的に eval を実行する
• 各変更で回帰を追跡する
• pass@k メトリクスで信頼性を測定する

Eval タイプ

能力 (Capability) Eval

Claude が以前はできなかったことができるかどうかをテストします:

[CAPABILITY EVAL: feature-name]
Task: Claude が達成すべきことの説明
Success Criteria:
  - [ ] 基準 1
  - [ ] 基準 2
  - [ ] 基準 3
Expected Output: 予期される結果の説明

回帰 (Regression) Eval

変更が既存機能を壊していないことを確認します:

[REGRESSION EVAL: feature-name]
Baseline: SHA またはチェックポイント名
Tests:
  - existing-test-1: PASS/FAIL
  - existing-test-2: PASS/FAIL
  - existing-test-3: PASS/FAIL
Result: X/Y passed (previously Y/Y)

Grader タイプ

1. コードベース Grader

コードを使った決定論的チェック:

# ファイルが予期されたパターンを含んでいるか確認
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. モデルベース Grader

Claude を使ってオープンエンドの出力を評価します:

[MODEL GRADER PROMPT]
以下のコード変更を評価してください:
1. 述べられた問題を解決していますか?
2. よく構造化されていますか?
3. エッジケースが処理されていますか?
4. エラーハンドリングは適切ですか?

Score: 1-5 (1=poor, 5=excellent)
Reasoning: [説明]

3. 人間 Grader

手動レビュー用にフラグを立てます:

[HUMAN REVIEW REQUIRED]
Change: 何が変わったかの説明
Reason: 人間によるレビューが必要な理由
Risk Level: LOW/MEDIUM/HIGH

メトリクス

pass@k

「k 回の試行中で少なくとも 1 回の成功」

• pass@1: 最初の試行の成功率
• pass@3: 3 試行以内での成功
• 典型的な目標: pass@3 > 90%

pass^k

「k 回の試行すべてが成功」

• より高い信頼性基準
• pass^3: 3 回連続での成功
• クリティカルパス向け

Eval ワークフロー

1. 定義 (コーディング前)

## EVAL DEFINITION: feature-xyz

### Capability Evals
1. 新しいユーザーアカウントを作成できる
2. メール形式を検証できる
3. パスワードを安全にハッシュ化できる

### Regression Evals
1. 既存のログインがまだ動作する
2. セッション管理が変わっていない
3. ログアウトフローが機能している

### Success Metrics
- capability evals に対して pass@3 > 90%
- regression evals に対して pass^3 = 100%

2. 実装

定義された eval に合格するコードを書きます。

3. 評価

# capability eval を実行
[各 capability eval を実行して PASS/FAIL を記録]

# regression eval を実行
npm test -- --testPathPattern="existing"

# レポートを生成

4. レポート

EVAL REPORT: feature-xyz
========================

Capability Evals:
  create-user:     PASS (pass@1)
  validate-email:  PASS (pass@2)
  hash-password:   PASS (pass@1)
  Overall:         3/3 passed

Regression Evals:
  login-flow:      PASS
  session-mgmt:    PASS
  logout-flow:     PASS
  Overall:         3/3 passed

Metrics:
  pass@1: 67% (2/3)
  pass@3: 100% (3/3)

Status: READY FOR REVIEW

統合パターン

実装前

/eval define feature-name

.claude/evals/feature-name.md に eval 定義ファイルを作成します

実装中

/eval check feature-name

現在の eval を実行して状態をレポートします

実装後

/eval report feature-name

完全な eval レポートを生成します

Eval ストレージ

プロジェクトに eval を保存:

.claude/
  evals/
    feature-xyz.md      # Eval 定義
    feature-xyz.log     # Eval 実行履歴
    baseline.json       # 回帰ベースライン

ベストプラクティス

1. コーディング前に eval を定義 - 成功基準について明確に考えることを強制する
2. eval を頻繁に実行 - 回帰を早期に発見する
3. pass@k の時間経過を追跡 - 信頼性のトレンドを監視する
4. 可能な限りコード grader を使用 - 決定論的 > 確率論的
5. セキュリティについては人間レビュー - セキュリティチェックを完全に自動化しない
6. eval は高速に保つ - 遅い eval は実行されない
7. コードと一緒に eval をバージョン管理 - Eval は第一級の成果物

例: 認証の追加

## EVAL: add-authentication

### Phase 1: Define (10 分)
Capability Evals:
- [ ] ユーザーがメール/パスワードで登録できる
- [ ] ユーザーが有効な認証情報でログインできる
- [ ] 無効な認証情報が適切なエラーで却下される
- [ ] セッションがページ再読み込みをまたいで保持される
- [ ] ログアウトでセッションがクリアされる

Regression Evals:
- [ ] パブリックルートがまだアクセス可能
- [ ] API レスポンスが変わっていない
- [ ] データベーススキーマが互換性がある

### Phase 2: Implement (可変)
[コードを書く]

### Phase 3: Evaluate
実行: /eval check add-authentication

### Phase 4: Report
EVAL REPORT: add-authentication
==============================
Capability: 5/5 passed (pass@3: 100%)
Regression: 3/3 passed (pass^3: 100%)
Status: SHIP IT