Eval Harness Skill 是 Everything Claude Code 体系下的核心 Skill，专为 AI 辅助编程场景设计的正式评测框架，实现了 Eval 驱动开发（EDD）理念。它让开发者能像写单元测试一样定义、执行和追踪 AI Agent 的能力与回归评测，支持 pass@k、pass^k 等可靠性指标，灵活切换 Checkpoint（阶段性）与 Continuous Eval（持续）模式，并结合代码、模型、人工多种 Grader 类型，全面提升 AI 代码输出的可控性和生产级质量保障。

Everything Claude Code Eval Harness Skill：Eval 驱动开发（EDD）、Checkpoint vs Continuous Eval 与 Grader 类型

在 AI 编程助手（如 Claude Code、Codex、Cursor 等）逐步走向生产级协作的今天，如何系统性评估和保障 AI 代码输出的质量、稳定性与可回归性，成为团队工程落地的核心难题。Eval Harness Skill 正是为此而生——它为 Claude Code 会话提供了类似“单元测试”的正式评测驱动开发（Eval-Driven Development, EDD）框架，让 AI 代码开发从“试试看”转变为“有标准、可追踪、能回归”的工程化闭环。

本指南将详细介绍 Eval Harness Skill 解决的问题、激活时机、完整使用流程、输出示例、常见配套 Agent 及与其他 Skill 的协作关系，帮助你在实际项目中用好这一生产级评测体系。

Eval Harness Skill 能解决什么问题？

在没有 Eval Harness Skill 的情况下，AI 代码助手的输出质量通常依赖人工主观判断，缺乏系统性标准和自动化回归能力，容易出现以下痛点：

• 需求不明确：没有明确的“完成标准”，AI 输出难以自动判定优劣。
• 回归难追踪：每次 Prompt、Agent、模型升级后，旧功能是否被破坏无法量化。
• 可靠性不可量化：没有 pass@k 等指标，无法评估 AI 方案的稳定性和改进空间。
• 评测方式混乱：人工评测、脚本检测、模型打分各自为政，难以统一管理和复用。

Eval Harness Skill 正式引入 EDD 流程，将评测定义、执行、追踪与报告标准化，具体能力包括：

• 支持能力评测（Capability Eval）和回归评测（Regression Eval）双模式
• pass@k、pass^k 等可靠性指标自动追踪
• 支持 Checkpoint（阶段性）与 Continuous Eval（持续）两种评测模式
• 代码、模型、人工多种 Grader 类型灵活组合
• 评测定义、历史与报告全项目结构化存储，便于版本管理和团队协作

什么时候激活 Eval Harness Skill？

Eval Harness Skill 适用于以下典型场景：

• AI 辅助开发流程初建：希望像 TDD 一样，为 AI 代码定义“验收标准”与自动化评测流程
• 新功能开发前：明确预期行为和成功标准，防止目标漂移
• Prompt/Agent/模型版本升级：快速回归验证，量化变更影响
• CI/CD 发布前：作为质量门槛，自动阻断不达标输出
• 团队协作/多 Agent 横向对比：标准化评测体系，便于横评和持续优化

Eval Harness Skill 使用流程（Step by Step）

1. 评测定义（Define）

在编码前，先用 /eval define feature-name 命令创建评测定义文件（如 .claude/evals/feature-xyz.md），明确列出能力评测与回归评测项，并设定通过标准。例如：

## EVAL DEFINITION: user-auth

### Capability Evals
1. 支持用户注册
2. 能校验邮箱格式
3. 密码加密存储

### Regression Evals
1. 旧登录流程不受影响
2. 会话管理无回归
3. 登出流程正常

### Success Metrics
- pass@3 > 90%（能力评测）
- pass^3 = 100%（回归评测）

最佳实践：在Everything Claude Code 完全指南中也强调，评测定义要在编码前完成，避免“边做边补标准”。

2. 实现功能（Implement）

根据评测定义，开发代码或配置 Agent/Prompt，目标是让所有评测项都能通过。

3. 执行评测（Evaluate）

使用 /eval check feature-name 命令自动运行所有定义的评测项。Eval Harness Skill 支持多种 Grader：

• 代码 Grader：用脚本或断言直接检测输出（如 grep、npm test）
• 模型 Grader：通过 LLM（如 Claude）判定复杂/开放性输出质量
• 人工 Grader：对于安全、合规等高风险项，自动标记为人工审核

示例代码 Grader：

# 检查 auth.ts 是否包含 handleAuth 方法
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"

# 跑测试
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

示例模型 Grader：

[MODEL GRADER PROMPT]
请评价以下代码变更：
1. 是否解决了需求？
2. 结构是否合理？
3. 是否覆盖边界情况？
4. 错误处理是否充分？

评分：1-5
理由：[说明]

4. 生成报告（Report）

用 /eval report feature-name 命令自动生成结构化评测报告，内容包括各项评测结果、pass@k 指标、历史对比等。例如：

EVAL REPORT: user-auth
======================

Capability Evals:
  register-user:     PASS (pass@1)
  validate-email:    PASS (pass@2)
  hash-password:     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

5. 持续追踪与版本管理

所有评测定义、运行历史、基线快照等均存储于 .claude/evals/ 目录，便于版本控制与团队协作。例如：

.claude/
  evals/
    user-auth.md      # 评测定义
    user-auth.log     # 运行历史
    baseline.json     # 回归基线

Checkpoint vs Continuous Eval

• Checkpoint Eval：在关键节点（如功能开发完成、PR 合并前）手动触发评测，适合阶段性验收和回归对比。
• Continuous Eval：每次 Agent/Prompt 变更、CI/CD 构建、甚至每次保存代码时自动评测，适合早发现回归、持续监控 pass@k 指标。

两种模式可灵活结合，支持团队按需定制评测频率与触发机制。

Grader 类型详解

Eval Harness Skill 支持以下 Grader 组合，满足不同场景需求：

1. 代码 Grader（Code-Based）：脚本/断言自动化检测，适合结构明确、可编程判定的输出。
2. 模型 Grader（Model-Based）：用 LLM 作为“裁判”，适合开放性、主观性较强的任务（如文档、代码风格等）。
3. 人工 Grader（Human Grader）：自动标记高风险或歧义项，由人工最终裁决，常用于安全、合规等场景。
4. 规则 Grader（Rule Grader，v1.8+）：用正则、Schema 等规则自动判定，适合格式化输出检测。

推荐实践：优先用代码 Grader 保证确定性，安全项永远要求人工 Grader，模型 Grader 适合主观性强但可控的场景。

输出示例

完整的评测定义与报告示例：

## EVAL: add-authentication

### Phase 1: Define
- [ ] 用户可用邮箱/密码注册
- [ ] 用户可用有效凭证登录
- [ ] 错误凭证有明确提示
- [ ] 会话可持久化
- [ ] 登出清理会话

### Phase 2: Implement
[开发代码]

### Phase 3: Evaluate
Run: /eval check add-authentication

### Phase 4: Report
EVAL REPORT: add-authentication
==============================
Capability: 5/5 passed (pass@3: 100%)
Regression: 3/3 passed (pass^3: 100%)
Status: SHIP IT

常见配套 Agent 与 Skill 协作

Eval Harness Skill 通常与以下 Agent/Skill 协同使用：

• Agent Eval Skill：横向对比多个 Agent 的 pass rate、成本与一致性
• Verification Loop Skill：将评测流程自动化为端到端验证闭环
• Agentic Engineering Skill：Eval-First 任务分解与工程化执行
• TDD Guide Agent：强制测试先行与评测驱动开发

通过这些组合，可以实现“AI 生成-自动评测-回归验证-持续优化”的完整工程闭环。

最佳实践与注意事项

• 评测定义要先于编码，强制明确需求与完成标准
• 频繁运行评测，及时捕捉回归和可靠性波动
• 优先用代码 Grader，安全项必须人工 Grader
• 评测要快，否则没人愿意跑
• 所有评测与代码同版本管理，成为一等公民
• 警惕过度拟合、只测 happy path、忽略成本/延迟漂移等反模式

更多高级技巧可参考Claude Code 高级技巧。

---

FAQ

Q: Eval Harness Skill 和传统单元测试有何不同？
A: Eval Harness Skill 针对 AI 代码助手的输出质量和行为评测，支持开放性任务、模型判分和人工审核，适合 AI 驱动的工程场景，而传统单元测试多为确定性代码逻辑。

Q: 如何选择代码 Grader、模型 Grader 和人工 Grader？
A: 结构化、可编程判定的用代码 Grader，主观性强但可 rubric 量化的用模型 Grader，安全/合规等高风险项必须人工 Grader 终审。

Q: pass@k 和 pass^k 指标如何理解和应用？
A: pass@k 表示 k 次尝试内至少一次成功，适合衡量实际可靠性；pass^k 表示连续 k 次全部成功，适合关键路径的稳定性要求。实际项目中常用 pass@3 > 90%、pass^3 = 100% 作为门槛。

---