评估测试框架 (Eval Harness)

评估测试框架技能

一个专为 Claude Code 会话设计的正式评估框架，实现了基于评估的开发（EDD）原则。

何时激活

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

理念

评估驱动开发将评估视为“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 "通过" || echo "失败"

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

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

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 功能名称

在 .claude/evals/功能名称.md 创建评估定义文件

实现期间

/eval check 功能名称

运行当前评估并报告状态

实现后

/eval report 功能名称

生成完整的评估报告

评估存储

将评估存储在项目中：

.claude/
  evals/
    功能-xyz.md      # 评估定义
    功能-xyz.log     # 评估运行历史
    baseline.json       # 回归基准

最佳实践

1. 在编码前定义评估 - 迫使清晰地思考成功标准
2. 频繁运行评估 - 尽早捕获回归
3. 跟踪 pass@k 随时间变化 - 监控可靠性趋势
4. 尽可能使用代码评测器 - 确定性优于概率性
5. 安全相关要人工审核 - 绝不完全自动化安全检查
6. 保持评估快速 - 慢的评估不会被运行
7. 将评估与代码一起版本化 - 评估是一等开发制品

示例：添加身份验证

## 评估: 添加身份验证

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

回归评估:
- [ ] 公共路由仍然可访问
- [ ] API 响应不变
- [ ] 数据库模式兼容

### 阶段 2: 实现（时间不定）
[编写代码]

### 阶段 3: 评估
运行: /eval check 添加身份验证

### 阶段 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 <目录> [<目录> ...] 将 1 到 100 个明确选择的、已验证的本地胶囊快照按声明的测试框架版本从同一任务系列分组。重复快照只计数一次；冲突的标识或无效胶囊会拒绝整个报告。这是只读的记录计数，不涉及新的发布、评分或提升。使用小而安静的胶囊。负载、目录参数和原始运行/胶囊 ID 被省略，但任务系列/版本标签是逐字的，摘要引用是可链接的；共享前请审核它们。操作验证仍待处理。

由于没有实现经过验证的操作系统沙箱后端，候选执行在所有操作系统上都被禁用。gate run、runGate、runVariant、直接子进程启动以及已退役的效果预加载都会拒绝并报 gate.isolation_required。没有信任标志或调用者提供的执行器可以绕过此拒绝。该示例记录了该拒绝并检查了源代码，但没有执行或评分。

不要将静态警告、胶囊收据或成功的工具测试作为候选沙箱或提升证据。未来的门控需要一个独立审核的操作系统边界、受保护检查器和审计通道，以及灾难性的基线拒绝。请参阅 docs/architecture/eval-harness-frameworks.md。

产品评估 (v1.8)

当行为质量无法仅通过单元测试捕获时，使用产品评估。

评测器类型

1. 代码评测器（确定性断言）
2. 规则评测器（正则表达式/模式约束）
3. 模型评测器（LLM 作为评判员评分标准）
4. 人工评测器（对模糊输出进行手动裁决）

pass@k 指南

• pass@1：直接可靠性
• pass@3：受控重试下的实际可靠性
• pass^3：稳定性测试（所有 3 次运行都必须通过）

推荐阈值：

• 能力评估：pass@3 >= 0.90
• 回归评估：pass^3 = 1.00（针对发布关键路径）

评估反模式

• 在 prompt 中过度拟合已知的评估示例
• 仅测量快乐路径输出
• 在追求通过率时忽略成本和延迟漂移
• 允许不稳定的评测器进入发布门控

最小评估制品布局

• .claude/evals/<功能>.md 定义
• .claude/evals/<功能>.log 运行历史
• docs/releases/<版本>/eval-summary.md 发布快照