eval-creator

Eval Creator

将已提升的经验转化为永久评测用例。运行回归检查，验证已提升的规则是否仍然有效。这是外层循环中的回归测试步骤。

博客中写道：“如果一次失败让你学到了重要的东西，它就应该成为永久测试用例。否则，这些知识依然脆弱。”

使用时机

• 自我改进流程在人工批准后提升了某种模式时——为它创建评测
• 按计划执行时——运行所有评测以检查是否出现回归
• 重要版本发布前——验证测试框架是否正常运行
• 某条已提升规则似乎不再生效时——通过有针对性的评测运行进行诊断

评测目录结构

.evals/
  EVAL_INDEX.md          # Index of all eval cases with status
  cases/
    eval-YYYYMMDD-001.md # Individual eval case
    eval-YYYYMMDD-002.md
    ...

创建评测用例

输入

来自自我改进提升流程，或手动提供：

• 已提升经验的 Pattern-Key
• 添加到项目指令文件（CLAUDE.md、AGENTS.md、.github/copilot-instructions.md）中的规则
• 要测试的内容（断言）
• 验证方法

评测用例格式

---
id: eval-YYYYMMDD-NNN
pattern-key: [from learning]
source: [LRN-YYYYMMDD-001, ERR-YYYYMMDD-003]
promoted-rule: "[the rule text in project instruction files]"
promoted-to: CLAUDE.md  # or AGENTS.md, .github/copilot-instructions.md, or equivalent
created: YYYY-MM-DD
last-run: YYYY-MM-DD
last-result: pass | fail | skip
evidence-level: presence | structural | behavioral
---

## What This Tests

[One sentence: what failure this eval prevents from recurring]

## Precondition

[What must be true for this eval to be runnable]
- File X exists
- Project uses framework Y
- etc.

## Verification Method

[One of: grep-check, command-check, file-check, rule-check, behavior-check]

### grep-check
Search for a pattern that should (or should not) exist:

target: src/**/*.ts pattern: "hardcoded-secret-pattern" expect: not_found

### command-check
Run a command and check the exit code or output:

command: npm run typecheck expect_exit: 0

### file-check
Verify a file or section exists:

target: CLAUDE.md # or AGENTS.md, .github/copilot-instructions.md section: "## Verification" expect: exists

### rule-check
Verify a rule exists in an instruction file:

target: CLAUDE.md # or AGENTS.md, .github/copilot-instructions.md contains: "[the promoted rule text or key phrase]" expect: found

`rule-check` proves only that guidance is installed. It must not be reported as
proof that an agent follows the guidance.

### behavior-check
Exercise the relevant behavior with synthetic positive and negative controls:

command: bash bench/run-contract-case.sh bounded-retry expect_exit: 0 positive_control: "transient failure is retried within budget" negative_control: "deterministic failure changes input or stops"

A behavioral pass requires observable evidence for both controls. Prefer the
repository's existing test, bench, or fixture mechanism; do not create a new
test framework for one eval.

## Expected Result

**Pass:** [What "good" looks like]
**Fail:** [What regression looks like]

## Recovery Action

If this eval fails:
1. [Specific step to diagnose]
2. [Specific step to fix]
3. Re-run this eval to verify

运行评测

运行全部评测

读取 .evals/EVAL_INDEX.md，遍历所有用例，并执行每种验证方法。

按 Pattern-Key 运行

筛选与指定模式匹配的评测。

按领域运行

筛选源文件属于某个领域（前端、后端等）的评测。

执行

对于每个评测用例：

1. 检查前置条件——如果不满足，则标记为 skip
2. 执行验证方法：
   • grep-check：使用 Grep 工具在目标文件中搜索模式
   • command-check：通过 Bash 运行命令，并检查退出代码和／或输出
   • file-check：使用 Read／Glob 验证文件／章节是否存在
   • rule-check：读取目标文件，搜索预期内容
   • behavior-check：运行现有的合成夹具或 bench 用例，并要求正向对照测试通过、负向对照测试被拒绝
   • skill-check：对技能目录运行 quick_validate.py（参见下文的技能验证）
   • script-check：按名称运行自定义 mcp-script（参见自定义验证方法）
3. 比较结果与预期
4. 检查证据强度——存在性／结构性方法无法满足行为断言。将用例标记为 fail，并设为 insufficient_evidence，而不是提高结论的可信度。
5. 在评测用例文件中更新 last-run 和 last-result
6. 使用结果更新 EVAL_INDEX.md

回归报告

## Eval Run: YYYY-MM-DD

**Total:** N evals
**Passed:** N
**Failed:** N
**Skipped:** N

### Failures

#### eval-YYYYMMDD-001 — [pattern-key]
- **What regressed:** [description]
- **Expected:** [X]
- **Got:** [Y]
- **Recovery action:** [from eval case]

### Summary
[All green / N regressions need attention]

评测索引格式

.evals/EVAL_INDEX.md：

# Eval Index

| ID | Pattern-Key | Rule Summary | Last Run | Result | Created |
|----|-------------|-------------|----------|--------|---------|
| eval-YYYYMMDD-001 | auth-middleware-lock | Run migrations on test DB first | YYYY-MM-DD | pass | YYYY-MM-DD |
| eval-YYYYMMDD-002 | pnpm-not-npm | Use pnpm in this repo | YYYY-MM-DD | fail | YYYY-MM-DD |

集成

上游

• self-improvement 在人工批准提升后标记候选评测，并提供规则、源 ID、Pattern-Key、断言和验证方法
• learning-aggregator 识别具有明确通过／失败条件的模式

下游

• 回归失败会作为新的错误条目反馈给 self-improvement
• 持续失败可能表明已提升规则需要改进 → 反馈给需人工把关的 self-improvement 提升流程

定期使用

对于采用 CI 流水线的项目，eval-creator 可以作为定期检查运行：

• 每周：运行所有评测
• 每个 PR：运行与变更文件相关的评测
• 提升后：立即运行新创建的评测

自定义验证方法（mcp-scripts）

除了五种内置方法（grep-check、command-check、file-check、 rule-check、behavior-check）之外，项目还可以将自定义验证工具定义为 mcp-scripts，用于执行内置方法无法表达的复杂断言。

示例 —— 验证一条已推广的身份验证规则是否得到执行的 eval：

# In gh-aw workflow config
mcp-scripts:
  check-auth-middleware:
    lang: javascript
    description: "Verify all /admin routes have auth middleware"
    run: |
      const routes = require('./src/routes/admin');
      const unprotected = routes.filter(r => !r.auth);
      if (unprotected.length) {
        console.error('Unprotected admin routes:', unprotected.map(r => r.path));
        process.exit(1);
      }

在 eval 用例中，将脚本引用为 verification_method: script-check，并指定 mcp-script 名称。这是一个扩展点——内置方法涵盖了大多数情况，但 mcp-scripts 可处理特定于项目的行为断言。

持久化

Eval 用例存放在工作目录的 .evals/ 中。该技能在交互式会话中不集成外部记忆后端。如需在 CI 端进行持久化存储，请参阅 eval-creator-ci，它可以选择使用 gh-aw 的 repo-memory 保存运行历史。

技能验证（skill-check）

Anthropic 的 /skill-creator 技能包含两个 eval-creator 可以使用的验证系统：

通过 quick_validate.py 进行结构验证

skill-check 验证方法会在技能目录上运行 skill-creator 的 quick_validate.py 脚本。它会检查：

• SKILL.md 是否存在且包含有效的 YAML frontmatter
• 是否仅使用允许的 frontmatter 键（name、description、license、allowed-tools、metadata、compatibility）
• 名称是否为 kebab-case，最多 64 个字符，且不以连字符开头或结尾，也不含连续连字符
• 描述是否不包含尖括号，且最多 1024 个字符
• 如果存在 compatibility 字段，其长度是否不超过 500 个字符

Eval 用例示例：

---
id: eval-YYYYMMDD-NNN
pattern-key: skill-quality.verify-gate
verification_method: skill-check
target: skills/verify-gate
expect: valid
---

## What This Tests
Verify that the verify-gate skill passes structural validation after harness updates.

执行方式：python .claude/skills/skill-creator/scripts/quick_validate.py <target>。退出码为 0 表示通过，退出码为 1 表示失败。

通过 run_eval.py 进行行为验证

如需深入验证，skill-creator 的 run_eval.py 会测试技能的描述是否会促使 Claude 针对给定查询调用该技能。在批准的技能描述变更后，或外层循环创建新技能时，这很有用——该 eval 可验证技能是否仍能正确触发。

这需要访问 Claude CLI，且开销较大。仅用于高价值技能，不要将其作为常规 CI 检查。

何时创建 skill-check eval

以下两种情况会将外层循环与技能验证关联起来：

1. Harness-updater 修改技能：当一条已推广的规则被插入 SKILL.md（而非项目指令文件）时，创建一个 skill-check eval，以验证编辑后技能仍保持结构有效。

2. 自我改进发现技能缺口：当 learning-aggregator 将某种模式归类为 skill_gap 并建议“创建新技能”时，提交前应使用 quick_validate.py 验证新技能。为其创建一个持久化的 skill-check eval，作为回归测试。

这样就形成了闭环：失败 → 学习 → 新建／更新技能 → eval 验证技能质量 → 回归测试防止质量退化。

此技能不执行的操作

• 不修复回归问题（会报告问题，由 Agent 或人工修复）
• 不推广经验（这是需要人工审核的自我改进工作流）
• 不分析模式（这是 learning-aggregator 的职责）
• 不替代项目测试套件——eval 测试的是工具链，而非代码