評估測試框架技能
Claude Code 會話的正式評估框架，實現評估驅動開發（EDD）原則。
何時啟用
- 為 AI 輔助工作流程設定評估驅動開發（EDD）
- 定義 Claude Code 任務完成的通過/失敗標準
- 使用 pass@k 指標衡量代理可靠性
- 為提示或代理變更建立回歸測試套件
- 跨模型版本基準測試代理效能
理念
評估驅動開發將評估視為「AI 開發的單元測試」：
- 在實施之前定義預期行為
- 在開發過程中持續運行評估
- 每次變更追蹤回歸
- 使用 pass@k 指標衡量可靠性
評估類型
能力評估
測試 Claude 是否能做到以前做不到的事：
[能力評估：功能名稱]
任務：描述 Claude 應完成的目標
成功標準：
- [ ] 標準 1
- [ ] 標準 2
- [ ] 標準 3
預期輸出：預期結果的描述
回歸評估
確保變更不會破壞現有功能：
[回歸評估：功能名稱]
基準：SHA 或檢查點名稱
測試：
- 現有測試-1：通過/失敗
- 現有測試-2：通過/失敗
- 現有測試-3：通過/失敗
結果：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 評估開放式輸出：
[模型評分提示]
評估以下程式碼變更：
1. 它是否解決了所述問題？
2. 結構是否良好？
3. 是否處理了邊界情況？
4. 錯誤處理是否得當？
分數：1-5（1=差，5=優秀）
理由：[解釋]
3. 人工評分者
標記需要人工審查：
[需要人工審查]
變更：變更的描述
原因：為何需要人工審查
風險等級：低/中/高
指標
pass@k
「在 k 次嘗試中至少成功一次」
- pass@1：首次嘗試成功率
- pass@3：3 次嘗試內成功
- 典型目標：pass@3 > 90%
pass^k
「所有 k 次嘗試都成功」
- 更高的可靠性標準
- pass^3：連續 3 次成功
- 用於關鍵路徑
評估工作流程
1. 定義（編碼前）
## 評估定義：功能-xyz
### 能力評估
1. 可以建立新使用者帳戶
2. 可以驗證電子郵件格式
3. 可以安全地雜湊密碼
### 回歸評估
1. 現有登入仍然正常
2. 會話管理未更改
3. 登出流程完整
### 成功指標
- 能力評估 pass@3 > 90%
- 回歸評估 pass^3 = 100%
2. 實施
撰寫通過所定義評估的程式碼。
3. 評估
# 運行能力評估
[運行每個能力評估，記錄通過/失敗]
# 運行回歸評估
npm test -- --testPathPattern="existing"
# 生成報告
4. 報告
評估報告：功能-xyz
========================
能力評估：
建立使用者： 通過（pass@1）
驗證電子郵件： 通過（pass@2）
雜湊密碼： 通過（pass@1）
總計： 3/3 通過
回歸評估：
登入流程： 通過
會話管理： 通過
登出流程： 通過
總計： 3/3 通過
指標：
pass@1：67%（2/3）
pass@3：100%（3/3）
狀態：準備審查
整合模式
實施前
/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 # 回歸基準
最佳實踐
- 在編碼之前定義評估 – 強制清晰思考成功標準
- 頻繁運行評估 – 及早捕捉回歸
- 持續追蹤 pass@k – 監控可靠性趨勢
- 盡可能使用程式碼評分者 – 確定性 > 機率性
- 安全相關需人工審查 – 永遠不要完全自動化安全檢查
- 保持評估快速 – 緩慢的評估不會被運行
- 將評估與程式碼版本化 – 評估是一級工件
範例：新增身份驗證
## 評估：新增身份驗證
### 階段 1：定義（10 分鐘）
能力評估：
- [ ] 使用者可以使用電子郵件/密碼註冊
- [ ] 使用者可以使用有效憑證登入
- [ ] 無效憑證被拒絕並顯示適當錯誤
- [ ] 會話在頁面重新載入後持續存在
- [ ] 登出清除會話
回歸評估：
- [ ] 公共路由仍然可訪問
- [ ] API 回應未更改
- [ ] 資料庫結構相容
### 階段 2：實施（時間不定）
[撰寫程式碼]
### 階段 3：評估
執行：/eval check add-authentication
### 階段 4：報告
評估報告：新增身份驗證
==============================
能力：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 會被省略，但任務家族/版本標籤會原樣保留，摘要參考可以連結；在分享前請審查它們。操作驗證仍待處理。
由於未實現經過驗證的 OS 隔離後端，因此在所有作業系統上都停用了候選執行。gate run、runGate、runVariant、直接子程序啟動以及已退役的效果預載入都會以 gate.isolation_required 拒絕。沒有任何信任旗標或呼叫者提供的執行器可以繞過此拒絕。範例記錄了該拒絕，並檢查原始碼而不執行或評分。
不要將靜態警告、膠囊收據或成功的工具測試作為候選隔離或提升證據。未來的閘道器需要獨立審查的 OS 邊界、受保護的檢查器和稽核通道，以及致命的基準拒絕。請參閱 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/<feature>.md定義.claude/evals/<feature>.log運行歷史docs/releases/<version>/eval-summary.md發布快照