Eval Harness 技能
適用於 Claude Code 會話的正式評測框架，實作評測驅動開發 (EDD) 原則。
啟動時機
- 為 AI 輔助工作流程設定評測驅動開發 (EDD)
- 為 Claude Code 任務完成定義通過/失敗標準
- 使用 pass@k 指標衡量代理程式的可靠性
- 為提示或代理程式的變更建立迴歸測試套件
- 跨模型版本比較代理程式的效能
理念
評測驅動開發將評測視為「AI 開發的單元測試」：
- 在實作之前定義預期行為
- 在開發過程中持續執行評測
- 追蹤每次變更的迴歸問題
- 使用 pass@k 指標衡量可靠度
評測類型
能力評測
測試 Claude 是否能夠做到以前做不到的事：
[CAPABILITY EVAL: 功能名稱]
任務：描述 Claude 應該完成什麼
成功標準：
- [ ] 標準 1
- [ ] 標準 2
- [ ] 標準 3
預期輸出：描述預期結果
迴歸評測
確保變更不會破壞現有功能：
[REGRESSION EVAL: 功能名稱]
基準：SHA 或檢查點名稱
測試：
- 現有測試-1：通過/失敗
- 現有測試-2：通過/失敗
- 現有測試-3：通過/失敗
結果：X/Y 通過 (之前為 Y/Y)
評分器類型
1. 程式碼評分器
使用程式碼進行確定性檢查：
# 檢查檔案是否包含預期模式
grep -q "export function handleAuth" src/auth.ts && echo "通過" || echo "失敗"
# 檢查測試是否通過
npm test -- --testPathPattern="auth" && echo "通過" || echo "失敗"
# 檢查建置是否成功
npm run build && echo "通過" || echo "失敗"
2. 模型評分器
使用 Claude 來評估開放式輸出：
[MODEL GRADER PROMPT]
評估以下的程式碼變更：
1. 它是否解決了所述問題？
2. 它的結構是否良好？
3. 是否處理了邊界情況？
4. 錯誤處理是否恰當？
分數：1-5 (1=差，5=優良)
理由：[說明]
3. 人工評分器
標記為人工審查：
[HUMAN REVIEW REQUIRED]
變更：描述變更的內容
原因：為什麼需要人工審查
風險等級：低/中/高
指標
pass@k
「在 k 次嘗試中至少成功一次」
- pass@1：首次嘗試成功率
- pass@3：3 次嘗試內成功
- 典型目標：pass@3 > 90%
pass^k
「所有 k 次嘗試都成功」
- 可靠性的更高標準
- pass^3：連續 3 次成功
- 用於關鍵路徑
評測工作流程
1. 定義 (編寫程式碼前)
## EVAL DEFINITION: 功能-xyz
### 能力評測
1. 能夠建立新使用者帳戶
2. 能夠驗證電子郵件格式
3. 能夠安全地雜湊密碼
### 迴歸評測
1. 現有登入仍然有效
2. 會話管理未變更
3. 登出流程完好
### 成功指標
- 能力評測的 pass@3 > 90%
- 迴歸評測的 pass^3 = 100%
2. 實作
編寫程式碼以通過定義的評測。
3. 評估
# 執行能力評測
[執行每個能力評測，記錄通過/失敗]
# 執行迴歸評測
npm test -- --testPathPattern="existing"
# 產生報告
4. 報告
EVAL REPORT: 功能-xyz
========================
能力評測：
建立使用者： 通過 (pass@1)
驗證電子郵件： 通過 (pass@2)
雜湊密碼： 通過 (pass@1)
總計： 3/3 通過
迴歸評測：
登入流程： 通過
會話管理： 通過
登出流程： 通過
總計： 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 分鐘)
能力評測：
- [ ] 使用者可以透過電子郵件/密碼註冊
- [ ] 使用者可以使用有效憑證登入
- [ ] 無效憑證被拒絕並顯示適當錯誤
- [ ] 會話在頁面重新整理後持續存在
- [ ] 登出清除會話
迴歸評測：
- [ ] 公開路由仍然可存取
- [ ] API 回應未變更
- [ ] 資料庫架構相容
### 階段 2：實作 (時間不定)
[編寫程式碼]
### 階段 3：評估
執行：/eval check 新增-驗證功能
### 階段 4：報告
EVAL REPORT: 新增-驗證功能
==============================
能力：5/5 通過 (pass@3：100%)
迴歸：3/3 通過 (pass^3：100%)
狀態：可以發布
本機框架工具集
機械工具集會部署在 scripts/lib/eval-harness/ 中：
node scripts/eval-harness.js example
- 膠囊：帶有雜湊連結的日誌，包含五個譜系和本機完整性檢查。
- 檢查：原始碼摘要、經驗證的變體路徑和語法警告。
- 重播：宣告的工具和內容定址的固定資源。缺少固定資源時會以失敗閉合；SE3 及以上版本在重播中被拒絕。記錄模式會呼叫已註冊的實作，因此僅註冊受信任的函式。
- 收據：離線驗證膠囊和產出物位元組，並附有名稱檢查。
- 回顧性準備：
node scripts/eval-harness.js capsule group <dir> [<dir> ...]將 1 到 100 個明確選取、經驗證的本機膠囊快照從一個任務系列中按宣告的框架版本分組。重複的快照僅計數一次；衝突的身分或無效膠囊會拒絕整個報告。這是唯讀的記錄計數，沒有新的推出、分數或晉升。請使用小型、靜止的膠囊。酬載、目錄引數以及原始執行/膠囊 ID 會被省略，但任務系列/版本標籤會原樣保留，且摘要參考是可連結的；在分享前請審查它們。操作驗證仍待處理。
候選程式的執行在所有作業系統上皆已停用，因為沒有實作經驗證的作業系統容器後端。gate run、runGate、runVariant、直接子行程啟動以及已退役的效果預載會拒絕並顯示 gate.isolation_required。沒有信任旗標或呼叫者提供的執行器可以繞過此拒絕。範例會記錄該拒絕，並檢查原始碼但不執行或評分。
請勿將靜態警告、膠囊收據或成功的工具測試呈現為候選程式容器或晉升的證據。未來的閘道需要一個獨立審查的作業系統邊界、受保護的檢查器和稽核通道，以及致命的基準拒絕。請參閱 docs/architecture/eval-harness-frameworks.md。
產品評測 (v1.8)
當行為品質無法僅由單元測試捕捉時，請使用產品評測。
評分器類型
- 程式碼評分器 (確定性斷言)
- 規則評分器 (正規表達式/結構約束)
- 模型評分器 (LLM 作為裁判的評分規約)
- 人工評分器 (針對模糊輸出的手動裁決)
pass@k 指引
pass@1：直接可靠性pass@3：受控重試下的實際可靠性pass^3：穩定性測試 (所有 3 次執行都必須通過)
建議閾值：
- 能力評測：pass@3 >= 0.90
- 迴歸評測：發布關鍵路徑的 pass^3 = 1.00
評測反模式
- 過度擬合提示以符合已知的評測範例
- 僅測量快樂路徑的輸出
- 在追求通過率的同時忽略成本和延遲漂移
- 在發布閘道中允許不穩定的評分器
最小評測產出物佈局
.claude/evals/<功能>.md定義.claude/evals/<功能>.log執行歷史docs/releases/<版本>/eval-summary.md發布快照