235 lines
5.7 KiB
Markdown
235 lines
5.7 KiB
Markdown
|
---
|
|||
|
|
name: eval-harness
|
|||
|
|
description: 針對 Claude Code 會話的正向評估框架，實踐評估驅動開發 (EDD) 原則。
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 評估測試組件技能 (Eval Harness Skill)
|
|||
|
|
|
|||
|
|
針對 Claude Code 會話的正向評估框架，實踐評估驅動開發 (Eval-Driven Development, EDD) 原則。
|
|||
|
|
|
|||
|
|
## 何時啟用
|
|||
|
|
|
|||
|
|
- 為 AI 輔助工作流設置評估驅動開發 (EDD)。
|
|||
|
|
- 為 Claude Code 任務完成定義「通過/失敗」基準。
|
|||
|
|
- 使用 `pass@k` 指標衡量 Agent 的可靠性。
|
|||
|
|
- 為提示詞 (Prompt) 或 Agent 變更建立回歸測試套件。
|
|||
|
|
- 在各個模型版本間進行 Agent 效能基準測試。
|
|||
|
|
|
|||
|
|
## 核心哲學
|
|||
|
|
|
|||
|
|
評估驅動開發 (EDD) 將評估視為「AI 開發的單元測試」：
|
|||
|
|
- 在實作「之前」定義預期行為。
|
|||
|
|
- 在開發過程中持續執行評估。
|
|||
|
|
- 追蹤每次變動可能產生的回歸 (Regressions)。
|
|||
|
|
- 使用 `pass@k` 指標衡量可靠度。
|
|||
|
|
|
|||
|
|
## 評估類型
|
|||
|
|
|
|||
|
|
### 能力評估 (Capability Evals)
|
|||
|
|
測試 Claude 是否能做到以前做不到的事情：
|
|||
|
|
```markdown
|
|||
|
|
[能力評估：功能名稱]
|
|||
|
|
任務：描述 Claude 應完成的目標
|
|||
|
|
成功標準：
|
|||
|
|
- [ ] 準則 1
|
|||
|
|
- [ ] 準則 2
|
|||
|
|
- [ ] 準則 3
|
|||
|
|
預期輸出：預期結果的描述
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 回歸評估 (Regression Evals)
|
|||
|
|
確保變動不會破壞現有功能：
|
|||
|
|
```markdown
|
|||
|
|
[回歸評估：功能名稱]
|
|||
|
|
基準線：SHA 雜湊值或是檢查點 (Checkpoint) 名稱
|
|||
|
|
測試項：
|
|||
|
|
- 現有測試-1：通過/失敗
|
|||
|
|
- 現有測試-2：通過/失敗
|
|||
|
|
- 現有測試-3：通過/失敗
|
|||
|
|
結果：通過 X/Y 個 (先前為 Y/Y)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 評分器類型 (Grader Types)
|
|||
|
|
|
|||
|
|
### 1. 基於程式碼的評分器
|
|||
|
|
使用程式碼進行確定性檢查：
|
|||
|
|
```bash
|
|||
|
|
# 檢查檔案是否包含預期模式
|
|||
|
|
grep -q "export function handleAuth" src/auth.ts && echo "通過" || echo "失敗"
|
|||
|
|
|
|||
|
|
# 檢查測試是否通過
|
|||
|
|
npm test -- --testPathPattern="auth" && echo "通過" || echo "失敗"
|
|||
|
|
|
|||
|
|
# 檢查建置是否成功
|
|||
|
|
npm run build && echo "通過" || echo "失敗"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 基於模型的評分器
|
|||
|
|
使用 Claude 評估開放式的輸出：
|
|||
|
|
```markdown
|
|||
|
|
[模型評分器提示詞]
|
|||
|
|
請評估以下程式碼變動：
|
|||
|
|
1. 它是否解決了所述問題？
|
|||
|
|
2. 結構是否良好？
|
|||
|
|
3. 是否處理了邊際案例 (Edge cases)？
|
|||
|
|
4. 錯誤處理是否妥切？
|
|||
|
|
|
|||
|
|
評分：1-5 (1=差，5=優)
|
|||
|
|
推論過程：[解釋原因]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 人工評分器
|
|||
|
|
標記需要人工審查：
|
|||
|
|
```markdown
|
|||
|
|
[需要人工審查]
|
|||
|
|
變動內容：對變動的描述
|
|||
|
|
原因：為何需要人工審查
|
|||
|
|
風險程度：低/中/高
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 指標 (Metrics)
|
|||
|
|
|
|||
|
|
### pass@k
|
|||
|
|
「在 k 次嘗試中至少成功一次」
|
|||
|
|
- `pass@1`：第一次嘗試的成功率。
|
|||
|
|
- `pass@3`：3 次嘗試內的成功率。
|
|||
|
|
- 典型目標：`pass@3 > 90%`。
|
|||
|
|
|
|||
|
|
### pass^k
|
|||
|
|
「所有 k 次試驗皆成功」
|
|||
|
|
- 更高標準的可靠性。
|
|||
|
|
- `pass^3`：連續 3 次成功。
|
|||
|
|
- 用於關鍵路徑。
|
|||
|
|
|
|||
|
|
## 評估工作流
|
|||
|
|
|
|||
|
|
### 1. 定義 (開發前)
|
|||
|
|
```markdown
|
|||
|
|
## 評估定義：功能-xyz
|
|||
|
|
|
|||
|
|
### 能力評估
|
|||
|
|
1. 可以建立新的使用者帳號
|
|||
|
|
2. 可以驗證電子郵件格式
|
|||
|
|
3. 可以安全地雜湊密碼
|
|||
|
|
|
|||
|
|
### 回歸評估
|
|||
|
|
1. 現有登入功能仍正常運作
|
|||
|
|
2. 會話 (Session) 管理未受影響
|
|||
|
|
3. 登出流程完好
|
|||
|
|
|
|||
|
|
### 成功指標
|
|||
|
|
- 能力評估之 pass@3 > 90%
|
|||
|
|
- 回歸評估之 pass^3 = 100%
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 實作
|
|||
|
|
撰寫程式碼以通過定義好的評估項目。
|
|||
|
|
|
|||
|
|
### 3. 執行評估
|
|||
|
|
```bash
|
|||
|
|
# 執行能力評估
|
|||
|
|
[執行各個能力評估項，記錄通過/失敗]
|
|||
|
|
|
|||
|
|
# 執行回歸評估
|
|||
|
|
npm test -- --testPathPattern="existing"
|
|||
|
|
|
|||
|
|
# 生成報告
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 報告
|
|||
|
|
```markdown
|
|||
|
|
評估報告：功能-xyz
|
|||
|
|
========================
|
|||
|
|
|
|||
|
|
能力評估：
|
|||
|
|
建立使用者： 通過 (pass@1)
|
|||
|
|
驗證電子郵件： 通過 (pass@2)
|
|||
|
|
密碼雜湊： 通過 (pass@1)
|
|||
|
|
整體情況： 3/3 通過
|
|||
|
|
|
|||
|
|
回歸評估：
|
|||
|
|
登入流程： 通過
|
|||
|
|
會話管理： 通過
|
|||
|
|
登出流程： 通過
|
|||
|
|
整體情況： 3/3 通過
|
|||
|
|
|
|||
|
|
數據指標：
|
|||
|
|
pass@1: 67% (2/3)
|
|||
|
|
pass@3: 100% (3/3)
|
|||
|
|
|
|||
|
|
狀態：準備好接受審查 (READY FOR REVIEW)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 整合模式
|
|||
|
|
|
|||
|
|
### 實作前
|
|||
|
|
```
|
|||
|
|
/eval define 功能名稱
|
|||
|
|
```
|
|||
|
|
在 `.claude/evals/功能名稱.md` 建立評估定義檔。
|
|||
|
|
|
|||
|
|
### 實作過程中
|
|||
|
|
```
|
|||
|
|
/eval check 功能名稱
|
|||
|
|
```
|
|||
|
|
執行目前的評估並報告狀態。
|
|||
|
|
|
|||
|
|
### 實作完成後
|
|||
|
|
```
|
|||
|
|
/eval report 功能名稱
|
|||
|
|
```
|
|||
|
|
生成完整的評估報告。
|
|||
|
|
|
|||
|
|
## 評估儲存方式
|
|||
|
|
|
|||
|
|
將評估儲存在專案中：
|
|||
|
|
```
|
|||
|
|
.claude/
|
|||
|
|
evals/
|
|||
|
|
feature-xyz.md # 評估定義
|
|||
|
|
feature-xyz.log # 評估執行紀錄
|
|||
|
|
baseline.json # 回歸測試基準線
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 最佳實踐
|
|||
|
|
|
|||
|
|
1. **在寫程式「之前」定義評估項** - 強迫自己對成功標準有清晰的思考。
|
|||
|
|
2. **頻繁執行評估** - 儘早發現回歸問題。
|
|||
|
|
3. **長期追蹤 pass@k** - 監控可靠性趨勢。
|
|||
|
|
4. **盡可能使用程式碼評分器** - 確定性優於機率性。
|
|||
|
|
5. **針對安全性進行人工審查** - 絕不要完全自動化安全性檢查。
|
|||
|
|
6. **保持評估快速** - 緩慢的評估不會被執行。
|
|||
|
|
7. **將評估項與程式碼一同進行版本控制** - 評估項是第一等產出物。
|
|||
|
|
|
|||
|
|
## 範例：新增身分驗證功能
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
## 評估：新增身分驗證
|
|||
|
|
|
|||
|
|
### 階段 1：定義 (10 分鐘)
|
|||
|
|
能力評估：
|
|||
|
|
- [ ] 使用者可以使用電子郵件/密碼註冊
|
|||
|
|
- [ ] 使用者可以使用有效憑證登入
|
|||
|
|
- [ ] 無效憑證將被拒絕並顯示正確錯誤
|
|||
|
|
- [ ] 重新整理頁面後會話仍保持
|
|||
|
|
- [ ] 登出後會清除會話
|
|||
|
|
|
|||
|
|
回歸評估：
|
|||
|
|
- [ ] 公開路由仍可存取
|
|||
|
|
- [ ] API 回應未改變
|
|||
|
|
- [ ] 資料庫架構相容
|
|||
|
|
|
|||
|
|
### 階段 2：實作 (因人而異)
|
|||
|
|
[撰寫程式碼]
|
|||
|
|
|
|||
|
|
### 階段 3：執行評估
|
|||
|
|
執行：/eval check 新增身分驗證
|
|||
|
|
|
|||
|
|
### 階段 4：報告
|
|||
|
|
評估報告：新增身分驗證
|
|||
|
|
==============================
|
|||
|
|
能力評估：5/5 通過 (pass@3: 100%)
|
|||
|
|
回歸評估：3/3 通過 (pass^3: 100%)
|
|||
|
|
狀態：可以發佈 (SHIP IT)
|
|||
|
|
```
|