---
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)
```