eval-harness

name	eval-harness
description	正式评估框架，实现 eval-driven development (EDD) 原则。 用于定义 pass/fail 标准、测量 pass@k 指标、创建回归测试套件。
origin	adapted from ECC

Eval Harness Skill

一个用于 Claude Code 会话的正式评估框架，实现 eval-driven development (EDD) 原则。

何时激活

• 为 AI 辅助工作流设置 EDD
• 定义 Claude Code 任务完成的 pass/fail 标准
• 使用 pass@k 指标测量 agent 可靠性
• 为 prompt 或 agent 更改创建回归测试套件
• 跨模型版本基准测试 agent 性能

理念

Eval-Driven Development 将评估视为"AI 开发的单元测试":

• 在实现前定义预期行为
• 在开发期间持续运行评估
• 用每次变更追踪回归
• 使用 pass@k 指标测量可靠性

评估类型

Capability Evals

测试 Claude 能否做以前不能做的事:

[CAPABILITY EVAL: points-calculation]
Task: 计算用户积分并确定等级
Success Criteria:
  - [ ] 积分正确累加
  - [ ] 等级边界正确
  - [ ] 权益解锁逻辑正确
Expected Output: 用户总积分 = 1500，等级 = L3

Regression Evals

确保变更不破坏现有功能:

[REGRESSION EVAL: login-flow]
Baseline: sha-abc123
Tests:
  - existing-login: PASS
  - session-management: PASS
  - logout-flow: PASS
Result: 3/3 passed (previously 3/3)

Grader 类型

1. Code-Based Grader

使用代码的确定性检查:

# 检查文件是否包含预期模式
grep -q "export function handlePoints" src/points.ts && echo "PASS" || echo "FAIL"

# 检查测试是否通过
npm test -- --testPathPattern="points" && echo "PASS" || echo "FAIL"

2. Model-Based Grader

使用 Claude 评估开放式输出:

[MODEL GRADER PROMPT]
评估以下代码变更：
1. 它是否解决了陈述的问题？
2. 结构是否良好？
3. 边界情况是否处理？
4. 错误处理是否适当？

Score: 1-5 (1=差, 5=优秀)
Reasoning: [解释]

3. Human Grader

标记为手动审查:

[HUMAN REVIEW REQUIRED]
Change: 描述变更内容
Reason: 为什么需要人工审查
Risk Level: LOW/MEDIUM/HIGH

指标

pass@k

"k 次尝试中至少一次成功"

• pass@1: 首次尝试成功率
• pass@3: 3 次内成功
• 典型目标: pass@3 > 90%

pass^k

"所有 k 次试验都成功"

• 更高可靠性标准
• 用于关键路径

评估工作流

1. 定义（编码前）

## EVAL DEFINITION: points-system

### Capability Evals
1. 可以计算用户积分
2. 可以确定用户等级
3. 可以解锁权益

### Regression Evals
1. 现有登录仍然有效
2. 会话管理未改变
3. 登出流程完整

### Success Metrics
- pass@3 > 90% for capability evals
- pass^3 = 100% for regression evals

2. 实现

编写代码通过定义的评估。

3. 评估

# 运行 capability evals
[Run each capability eval, record PASS/FAIL]

# 运行 regression evals
npm test -- --testPathPattern="existing"

# 生成报告

4. 报告

EVAL REPORT: points-system
==========================

Capability Evals:
  calculate-points:  PASS (pass@1)
  determine-level:  PASS (pass@2)
  unlock-benefits: 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

评估存储

在项目中存储评估:

.claude/
  evals/
    points-system.md      # 评估定义
    points-system.log     # 评估运行历史
    baseline.json         # 回归基线

最佳实践

1. 编码前定义评估 - 强制清晰思考成功标准
2. 频繁运行评估 - 尽早捕获回归
3. 追踪 pass@k 趋势 - 监控可靠性趋势
4. 尽可能使用 code graders - 确定性 > 概率性
5. 人工审查安全 - 永远不完全自动化安全检查
6. 保持评估快速 - 慢评估不会被运行
7. 版本评估与代码 - 评估是一级 artifacts

与 Error Experience Library 的关系

• Error Experience Library 记录已解决的错误
• Eval Harness 验证新能力是否正确实现
• 两者都可用于回归测试