eval-harness

# Eval Harness Skill（评估工具技能） <!-- 【教学说明】 这个技能提供了一种"测试驱动"的方法来开发 AI 工作流程。 就像程序员写代码前先写测试，这个技能教你在使用 AI 前先定义成功标准。 这是确保 AI 可靠地完成任务的系统化方法。 --> Claude Code 会话的正式评估框架，实现评估驱动开发（EDD）原则。 ## 何时激活此技能 - 为 AI 辅助工作流设置评估驱动开发（EDD） - 定义 Claude Code 任务完成的通过/失败标准 - 使用 pass@k 指标测量代理可靠性 - 为 prompt 或代理变更创建回归测试套件 - 跨模型版本基准测试代理性能 ## EDD 核心理念 <!-- 【教学说明】 EDD 将评估视为"AI 开发的单元测试"。 --> 评估驱动开发将评估视为"AI 开发的单元测试"： - 在实现**之前**定义预期行为 - 在开发期间持续运行评估 - 跟踪每次变更的回归 - 使用 pass@k 指标测量可靠性 **传统开发 vs EDD：** ``` 传统：写代码 → 希望 AI 理解 → 失败 → 调试 EDD： 定义成功 → 实现 → 验证 → 通过 ``` ## 评估类型 ### 能力评估（Capability Evals） <!-- 【教学说明】 能力评估测试 AI 能否做之前做不到的事情。 --> 测试 Claude 能否做之前做不到的事情： ```markdown [能力评估: feature-name] 任务：描述 Claude 应该完成什么 成功标准： - [ ] 标准 1 - [ ] 标准 2 - [ ] 标准 3 预期输出：预期结果的描述 ``` **示例：** ```markdown [能力评估: user-authentication] 任务：实现用户注册和登录 成功标准： - [ ] 用户可以使用邮箱和密码注册 - [ ] 密码使用 bcrypt 哈希 - [ ] 登录返回 JWT 令牌 - [ ] 无效凭据返回 401 错误 预期输出：工作身份验证系统 ``` ### 回归评估（Regression Evals） <!-- 【教学说明】 回归评估确保变更不会破坏现有功能。 --> 确保变更不会破坏现有功能： ```markdown [回归评估: feature-name] 基线：SHA 或检查点名称 测试： - existing-test-1: 通过/失败 - existing-test-2: 通过/失败 - existing-test-3: 通过/失败 结果：X/Y 通过（之前 Y/Y） ``` **示例：** ```markdown [回归评估: authentication] 基线：commit abc123 测试： - 用户登录仍然工作: 通过 - 会话管理未更改: 通过 - 注销流程完整: 通过 结果：3/3 通过（之前 3/3） ``` ## 评分器类型 <!-- 【教学说明】 评分器决定如何评估任务完成情况。 --> ### 1. 基于代码的评分器（Code-Based Grader） 使用代码进行确定性检查： ```bash # 检查文件是否包含预期模式 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 评估开放式输出： ```markdown [模型评分器提示] 评估以下代码更改： 1. 是否解决了所述问题？ 2. 结构是否良好？ 3. 是否处理了边缘情况？ 4. 错误处理是否适当？ 分数：1-5（1=差，5=优秀） 推理：[解释] ``` **优点：** - 可以评估质量 - 理解上下文 - 检测细微问题 **何时使用：** - 代码质量评估 - 架构决策 - 最佳实践检查 ### 3. 人工评分器（Human Grader） 标记手动审查： ```markdown [需要人工审查] 更改：更改的描述 原因：为什么需要人工审查 风险级别：低/中/高 ``` **优点：** - 最安全 - 捕获 AI 错过的东西 - 适合关键决策 **何时使用：** - 安全更改 - 性能关键路径 - 用户影响功能 ## 评估指标 <!-- 【教学说明】 pass@k 测量可靠性——在 k 次尝试中至少一次成功。 --> ### 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. 定义（编码前） <!-- 【教学说明】 在写任何代码之前，定义成功标准。 --> ```markdown ## 评估定义: feature-xyz ### 能力评估 1. 可以创建新用户账户 2. 可以验证邮箱格式 3. 可以安全哈希密码 ### 回归评估 1. 现有登录仍然工作 2. 会话管理未更改 3. 注销流程完整 ### 成功指标 - 能力评估 pass@3 > 90% - 回归评估 pass^3 = 100% ``` ### 2. 实现 编写代码通过定义的评估。 ### 3. 评估 ```bash # 运行能力评估 [运行每个能力评估，记录通过/失败] # 运行回归评估 npm test -- --testPathPattern="existing" # 生成报告 ``` ### 4. 报告 ```markdown 评估报告: 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 流程 ```markdown ## 评估: 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 可靠地交付高质量结果——就像单元测试确保代码质量一样。