eval-harness

eval-harness 技能概览

eval-harness 的作用

eval-harness 技能是一套面向 Claude Code 会话和 eval 驱动开发的正式评估框架。它帮助你在发布前先定义“什么算好”，再衡量某个 agent、prompt 或工作流是否真的达到这个标准。

谁适合使用它

如果你需要对 AI 辅助编码、prompt 调整或 agent 行为做可重复的检查，就适合使用 eval-harness 技能。它尤其适合用来比较不同模型版本、追踪回归问题，或者把模糊的任务预期转成明确的通过/失败标准。

为什么它重要

eval-harness for Model Evaluation 的核心价值是可靠性：它不是凭感觉判断结果，而是通过编写 eval 来暴露行为变化。这样更容易排查 agent 性能问题、对比不同运行结果，也能避免发布那些会悄悄拉低质量的 prompt 更新。

什么时候最适合用

当任务可以表达为可观察的成功标准、输出结构，或者带检查点的行为时，它最有用。若是开放式创意工作，除非你仍然能定义可衡量的验收条件，否则它的作用会明显下降。

如何使用 eval-harness 技能

安装并启用

进行 eval-harness install 时，先在你的 Claude Code 环境里走仓库提供的技能安装流程，然后直接打开技能文件。该技能位于 skills/eval-harness/SKILL.md，这是第一份要读的文件，因为它定义了何时启用这个框架，以及 eval 应该如何组织。

先构建一个技能可以评估的 prompt

如果要做好 eval-harness usage，不要一上来就说“测试我的 agent”。先给出具体目标，比如：agent 必须完成什么任务，什么算成功，什么算失败，以及你是在检查能力还是回归。更好的输入可以是：“评估 agent 能否在不破坏校验逻辑的前提下更新一个 React 表单，并要求给出三个明确的成功标准。”这样 harness 才有可衡量的内容。

先读对的文件

如果你是在自己的工作流里采用 eval-harness guide 这种方式，先读 SKILL.md，再查看仓库中任何描述评估风格、评分逻辑或输出约定的说明。在这个仓库里，没有辅助脚本或额外的支持目录，所以技能文件本身就是唯一的事实来源。

在实际工作流中使用它

一个比较稳妥的工作流是：先定义行为，再为 happy path 写一个 eval，接着为已知失败点补一个回归 eval，然后运行 harness 并收紧标准。这样既能让 eval 保持足够小、便于调试，也能减少把测试写得过于宽泛、最后难以解释的风险。

eval-harness 技能 FAQ

eval-harness 只适用于 Claude Code 吗？

不是。这个技能是围绕 Claude Code 会话编写的，但其底层方法在任何需要结构化 agent 评估的场景里都适用。如果你的技术栈使用的是别的工具，也可以沿用相同的 eval 格式和评分逻辑。

eval-harness 和普通 prompt 是一回事吗？

不是。普通 prompt 是要求给出一个答案；eval-harness 要求的是一套可重复判断答案的方法。当你需要的是跨版本的一致性，而不只是某一次答得好，这个区别就非常关键。

它适合新手吗？

适合，只要你能把任务描述清楚。真正难的不是语法，而是如何写出好的成功标准。新手通常从一个简单的能力 eval 开始，会比试图一次性建模整个工作流更容易上手。

什么时候不该用它？

如果工作高度主观、输出无法稳定一致地检查，或者你只需要一次性答案，就可以跳过 eval-harness。当真正目标是可靠性、回归追踪或模型比较时，它的优势才最明显。

如何改进 eval-harness 技能

让标准变得可观察

最大的质量提升来自把判断变成检查。把“做得更好”改成类似“保留现有 API 形状”“返回合法 JSON”“通过全部三个回归用例”这样的条件。标准越可观察，eval-harness 就越容易运行，也越值得信任。

区分能力和回归

如果把新功能检查和旧行为检查混在一起，失败结果就会很难解读。能力 eval 应该聚焦 Claude 能不能做成某个新事情，回归 eval 则应该聚焦某个已知基线是否仍然成立。

给 harness 真正的边界案例

更强的 eval 不只包含 happy path，也要包含失败模式。加入棘手输入、上下文不完整或指令含糊的情况，才能让 eval-harness skill 暴露出 agent 到底是真稳健，还是只是在干净样例上运气好。

第一次运行后继续迭代

把第一次运行当作校准，而不是结论。如果结果不够清楚，就收紧成功标准、补一个基线，或者把一个过宽的 eval 拆成更小的检查项。通常这也是提升 eval-harness usage、拿到真正可行动结果的最快方式。