eval-harness

Eval Harness 技能

Claude Code 工作階段的正式評估框架，實作評估驅動開發（EDD）原則。

何時啟用

• 為 AI 輔助工作流程設定評估驅動開發（EDD）
• 定義 Claude Code 任務完成的通過/失敗標準
• 使用 pass@k 指標衡量代理可靠性
• 為提示或代理變更建立回歸測試套件
• 跨模型版本基準測試代理效能

哲學

評估驅動開發將評估視為「AI 開發的單元測試」：

• 在實作前先定義預期行為
• 開發期間持續執行評估
• 每次變更追蹤回歸
• 使用 pass@k 指標衡量可靠性

評估類型

能力評估

測試 Claude 是否能做到以前做不到的事：

[CAPABILITY EVAL: feature-name]
Task: 描述 Claude 應完成的任務
Success Criteria:
  - [ ] 標準 1
  - [ ] 標準 2
  - [ ] 標準 3
Expected Output: 描述預期結果

回歸評估

確保變更不會破壞現有功能：

[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 通過（先前 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. 錯誤處理是否適當？

Score: 1-5（1=差，5=優）
Reasoning: [解釋]

3. 人工評分器

標記為人工審查：

[HUMAN REVIEW REQUIRED]
Change: 描述變更內容
Reason: 需要人工審查的原因
Risk Level: LOW/MEDIUM/HIGH

指標

pass@k

「k 次嘗試中至少一次成功」

• pass@1：首次嘗試成功率
• pass@3：3 次嘗試內成功
• 典型目標：pass@3 > 90%

pass^k

「所有 k 次嘗試都成功」

• 更高的可靠性標準
• pass^3：連續 3 次成功
• 用於關鍵路徑

評估工作流程

1. 定義（編碼前）

## EVAL DEFINITION: feature-xyz

### Capability Evals
1. 能建立新使用者帳戶
2. 能驗證電子郵件格式
3. 能安全雜湊密碼

### Regression Evals
1. 現有登入仍正常運作
2. 工作階段管理未變更
3. 登出流程完整

### Success Metrics
- 能力評估 pass@3 > 90%
- 回歸評估 pass^3 = 100%

2. 實作

撰寫程式碼以通過定義的評估。

3. 評估

# 執行能力評估
[執行每個能力評估，記錄 PASS/FAIL]

# 執行回歸評估
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 check feature-name

執行當前評估並回報狀態

實作後

/eval report feature-name

產生完整評估報告

評估儲存

將評估儲存在專案中：

.claude/
  evals/
    feature-xyz.md      # 評估定義
    feature-xyz.log     # 評估執行歷史
    baseline.json       # 回歸基準線

最佳實務

1. 在編碼前先定義評估 - 強迫釐清成功標準
2. 頻繁執行評估 - 及早發現回歸
3. 追蹤 pass@k 隨時間變化 - 監控可靠性趨勢
4. 盡可能使用程式碼評分器 - 確定性 > 機率性
5. 安全性需人工審查 - 絕不全面自動化安全檢查
6. 保持評估快速 - 慢的評估不會被執行
7. 將評估與程式碼一起版本化 - 評估是一級成品

範例：新增驗證

## EVAL: add-authentication

### Phase 1: Define (10 min)
Capability Evals:
- [ ] 使用者能以電子郵件/密碼註冊
- [ ] 使用者能以有效憑證登入
- [ ] 無效憑證被拒絕並顯示適當錯誤
- [ ] 工作階段在頁面重新整理後持續存在
- [ ] 登出清除工作階段

Regression Evals:
- [ ] 公開路由仍可存取
- [ ] API 回應不變
- [ ] 資料庫結構相容

### Phase 2: Implement (varies)
[撰寫程式碼]

### 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

產品評估（v1.8）

當行為品質無法僅由單元測試捕捉時，使用產品評估。

評分器類型

1. 程式碼評分器（確定性斷言）
2. 規則評分器（正則表達式/結構約束）
3. 模型評分器（LLM 作為評審的評分標準）
4. 人工評分器（針對模糊輸出的手動裁決）

pass@k 指引

• pass@1：直接可靠性
• pass@3：受控重試下的實用可靠性
• pass^3：穩定性測試（所有 3 次執行必須通過）

建議閾值：

• 能力評估：pass@3 >= 0.90
• 回歸評估：發布關鍵路徑 pass^3 = 1.00

評估反模式

• 過度擬合提示以符合已知評估範例
• 僅測量快樂路徑輸出
• 在追求通過率的同時忽略成本和延遲漂移
• 允許不穩定的評分器進入發布關卡

最小評估成品佈局

• .claude/evals/<feature>.md 定義
• .claude/evals/<feature>.log 執行歷史
• docs/releases/<version>/eval-summary.md 發布快照