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：既存の合成フィクスチャまたはベンチケースを実行し、ポジティブコントロールが合格し、ネガティブコントロールが拒否されることを確認します
   • skill-check：スキルディレクトリに対してquick_validate.pyを実行します（「スキルの検証」を参照）
   • script-check：名前を指定してカスタムmcp-scriptを実行します（「カスタム検証方法」を参照）
3. 結果を期待値と比較します
4. 証拠の強さを確認する — 存在確認や構造確認だけでは、動作に関するアサーションを満たせません。主張の基準を引き上げるのではなく、insufficient_evidenceとしてケースをfailにします
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）

組み込みの5つの方法（grep-check、command-check、file-check、 rule-check、behavior-check）に加えて、組み込みの方法では表現できない複雑なアサーション向けに、プロジェクトでカスタム検証ツールをmcp-scriptsとして定義できます。

例 — 昇格された認証ルールが適用されていることを検証する評価：

# 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);
      }

スクリプトを評価ケースで参照するには、mcp-script名とともにverification_method: script-checkを指定します。これは拡張ポイントです。組み込みの方法でほとんどのケースに対応できますが、mcp-scriptsはプロジェクト固有の動作アサーションに対応します。

永続化

評価ケースは、作業ディレクトリの.evals/に保存されます。このスキルは、対話型セッションで外部のメモリバックエンドと連携しません。CI側で永続的に保存する方法については、実行履歴をgh-awのrepo-memoryに任意で保存できるeval-creator-ciを参照してください。

スキルの検証（skill-check）

Anthropicの/skill-creatorスキルには、eval-creatorが利用できる2つの検証システムがあります。

quick_validate.pyによる構造検証

skill-check検証方法では、スキルディレクトリに対してskill-creatorのquick_validate.pyスクリプトを実行します。以下を確認します。

• SKILL.mdが存在し、有効なYAMLフロントマターが含まれている
• 許可されているフロントマターキー（name、description、license、allowed-tools、metadata、compatibility）のみが使用されている
• 名前がケバブケースで、最大64文字であり、先頭、末尾、連続するハイフンがない
• 説明に山括弧が含まれず、最大1024文字である
• compatibilityフィールドが指定されている場合、最大500文字である

評価ケースの例：

---
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がそのスキルを呼び出すかどうかをテストします。承認済みのスキル説明を変更した後や、外側のループが新しいスキルを作成した場合に役立ちます。評価によって、スキルが引き続き正しく呼び出されることを検証できます。

この検証にはClaude CLIへのアクセスが必要で、コストも高くなります。価値の高いスキルにのみ使用し、定期的なCIチェックとしては使用しないでください。

skill-check評価を作成するタイミング

次の2つのシナリオでは、外側のループとスキル検証を連携させます。

1. Harness-updaterがスキルを変更する場合：昇格されたルールをプロジェクトの指示ファイルではなくSKILL.mdに挿入するときは、編集後もスキルの構造が有効であることを検証するため、skill-check評価を作成します。

2. 自己改善によってスキルの不足が特定された場合：learning-aggregatorがパターンをskill_gapとして分類し、「新しいスキルを作成する」ことを推奨したときは、コミット前に新しいスキルがquick_validate.pyに合格する必要があります。そのスキルに対して、回帰テストとして保持されるskill-check評価を作成します。

これにより、失敗 → 学習 → 新規／更新スキル → 評価によるスキル品質の検証 → 回帰による品質低下の防止、というループが完結します。

このスキルが行わないこと

• 回帰を修正しません（エージェントまたは人間が修正できるよう、報告します）
• 学習内容を昇格しません（これは人間の承認が必要な自己改善ワークフローの役割です）
• パターンを分析しません（これはlearning-aggregatorの役割です）
• プロジェクトのテストスイートの代わりにはなりません。評価でテストするのはハーネスであり、コードではありません