eval-harness

name	eval-harness
description	Claude Code 会话的正式评估框架，实现评估驱动开发（EDD）原则
tools	Read, Write, Edit, Bash, Grep, Glob

Eval Harness Skill（评估工具技能）

Claude Code 会话的正式评估框架，实现评估驱动开发（EDD）原则。

何时激活此技能

• 为 AI 辅助工作流设置评估驱动开发（EDD）
• 定义 Claude Code 任务完成的通过/失败标准
• 使用 pass@k 指标测量代理可靠性
• 为 prompt 或代理变更创建回归测试套件
• 跨模型版本基准测试代理性能

EDD 核心理念

评估驱动开发将评估视为"AI 开发的单元测试"：

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

传统开发 vs EDD：

传统：写代码 → 希望 AI 理解 → 失败 → 调试
EDD：  定义成功 → 实现 → 验证 → 通过

评估类型

能力评估（Capability Evals）

测试 Claude 能否做之前做不到的事情：

[能力评估: feature-name]
任务：描述 Claude 应该完成什么
成功标准：
  - [ ] 标准 1
  - [ ] 标准 2
  - [ ] 标准 3
预期输出：预期结果的描述

示例：

[能力评估: user-authentication]
任务：实现用户注册和登录
成功标准：
  - [ ] 用户可以使用邮箱和密码注册
  - [ ] 密码使用 bcrypt 哈希
  - [ ] 登录返回 JWT 令牌
  - [ ] 无效凭据返回 401 错误
预期输出：工作身份验证系统

回归评估（Regression Evals）

确保变更不会破坏现有功能：

[回归评估: feature-name]
基线：SHA 或检查点名称
测试：
  - existing-test-1: 通过/失败
  - existing-test-2: 通过/失败
  - existing-test-3: 通过/失败
结果：X/Y 通过（之前 Y/Y）

示例：

[回归评估: authentication]
基线：commit abc123
测试：
  - 用户登录仍然工作: 通过
  - 会话管理未更改: 通过
  - 注销流程完整: 通过
结果：3/3 通过（之前 3/3）

评分器类型

1. 基于代码的评分器（Code-Based Grader）

使用代码进行确定性检查：

# 检查文件是否包含预期模式
grep -q "export function handleAuth" src/auth.ts && echo "通过" || echo "失败"

# 检查测试是否通过
npm test -- --testPathPattern="auth" && echo "通过" || echo "失败"

# 检查构建是否成功
npm run build && echo "通过" || echo "失败"

优点：

• 确定性（总是相同结果）
• 快速
• 易于自动化

何时使用：

• 检查文件存在
• 验证代码模式
• 运行测试

2. 基于模型的评分器（Model-Based Grader）

使用 Claude 评估开放式输出：

[模型评分器提示]
评估以下代码更改：
1. 是否解决了所述问题？
2. 结构是否良好？
3. 是否处理了边缘情况？
4. 错误处理是否适当？

分数：1-5（1=差，5=优秀）
推理：[解释]

优点：

• 可以评估质量
• 理解上下文
• 检测细微问题

何时使用：

• 代码质量评估
• 架构决策
• 最佳实践检查

3. 人工评分器（Human Grader）

标记手动审查：

[需要人工审查]
更改：更改的描述
原因：为什么需要人工审查
风险级别：低/中/高

优点：

• 最安全
• 捕获 AI 错过的东西
• 适合关键决策

何时使用：

• 安全更改
• 性能关键路径
• 用户影响功能

评估指标

pass@k

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

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

示例：

任务：实现用户认证
尝试 1：失败（语法错误）
尝试 2：失败（逻辑错误）
尝试 3：通过 ✓

pass@1 = 0%（首次未通过）
pass@3 = 100%（3 次内通过）

pass^k

"所有 k 次试验都成功"

• 更高的可靠性标准
• pass^3：3 次连续成功
• 用于关键路径

示例：

任务：实现用户认证
试验 1：通过 ✓
试验 2：通过 ✓
试验 3：通过 ✓

pass^3 = 100%（全部通过）

pass@k vs pass^k：

• pass@k："至少成功一次"（宽松）
• pass^k："每次都成功"（严格）

评估工作流

1. 定义（编码前）

## 评估定义: feature-xyz

### 能力评估
1. 可以创建新用户账户
2. 可以验证邮箱格式
3. 可以安全哈希密码

### 回归评估
1. 现有登录仍然工作
2. 会话管理未更改
3. 注销流程完整

### 成功指标
- 能力评估 pass@3 > 90%
- 回归评估 pass^3 = 100%

2. 实现

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

3. 评估

# 运行能力评估
[运行每个能力评估，记录通过/失败]

# 运行回归评估
npm test -- --testPathPattern="existing"

# 生成报告

4. 报告

评估报告: feature-xyz
========================

能力评估:
  create-user:     通过 (pass@1)
  validate-email:  通过 (pass@2)
  hash-password:   通过 (pass@1)
  总计:            3/3 通过

回归评估:
  login-flow:      通过
  session-mgmt:    通过
  logout-flow:     通过
  总计:            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       # 回归基线

为什么存储评估？

• 版本控制
• 历史追踪
• 团队共享

评估最佳实践

1. 编码前定义评估 ——迫使对成功标准进行清晰思考
2. 频繁运行评估 ——尽早发现回归
3. 跟踪 pass@k 趋势 ——监控可靠性趋势
4. 尽可能使用代码评分器 ——确定性 > 概率性
5. 安全检查需人工审查 ——永不完全自动化安全检查
6. 保持评估快速 ——慢评估不会被运行
7. 与代码一起版本化评估 ——评估是一等构件

示例：添加认证的完整 EDD 流程

## 评估: add-authentication

### 阶段 1：定义（10 分钟）
能力评估:
- [ ] 用户可以使用邮箱/密码注册
- [ ] 用户可以使用有效凭据登录
- [ ] 无效凭据被适当拒绝
- [ ] 会话在页面重新加载后持久化
- [ ] 注销清除会话

回归评估:
- [ ] 公共路由仍然可访问
- [ ] API 响应未更改
- [ ] 数据库架构兼容

### 阶段 2：实现（变化）
[编写代码]

### 阶段 3：评估
运行: /eval check add-authentication

结果:
- 能力：5/5 通过（pass@3: 100%）
- 回归：3/3 通过（pass^3: 100%）

### 阶段 4：报告
评估报告: add-authentication
==============================
能力: 5/5 通过（pass@3: 100%）
回归: 3/3 通过（pass^3: 100%）
状态: 可以发布

常见问题

Q: pass@k 和 pass^k 有什么区别？

A:

• pass@k：k 次尝试中至少一次成功（例如 pass@3 = 3 次内成功）
• pass^k：所有 k 次试验都成功（例如 pass^3 = 3 次都成功）

Q: 应该使用哪种评分器？

A:

• 代码评分器：确定性检查（文件存在、测试通过）
• 模型评分器：质量评估（代码结构、最佳实践）
• 人工评分器：关键决策（安全、性能）

Q: 评估应该多频繁？

A:

• 编码前：定义评估
• 编码期间：每次更改后运行评估
• 发布前：完整评估套件

---

记住：评估驱动开发确保 AI 可靠地交付高质量结果——就像单元测试确保代码质量一样。