waxa-eval

waxa-eval

実際の反復実行から体系化した、スキルプロンプトの実証的な評価ループです。 このスキルは waxa の運用マニュアルです。CLI 本体は tools/waxa/ にあります（引数レベルのリファレンスについては README を参照してください）。

waxa は microsoft/waza を拡張し、 その上に empirical-prompt-tuning のセマンティクスを追加します。強制的な Self-report、反復をまたぐ台帳、4 種類のグレーダー、収束検出が含まれます。

呼び出すタイミング

明示的にユーザーから依頼された場合のみです。

• 「このスキルを waxa で評価して」
• 「収束するまで <skill> を反復して」
• 「<scenario> 用の waxa シナリオを追加して」
• 「これらの不明点／Self-report を解釈して」

使用しない場合：

• 単発のスキル編集（誤字修正、1 文の引き締め） — 直接編集し、評価サイクルは実行しません。
• スキルが新規でシナリオがまだない — まず SKILL.md を作成します。測定対象が安定してから評価を実行してください。
• ユーザーが評価を依頼していない — メタスキルのため、自動で呼び出しません。

4 段階の反復パターン

skill-selector、nix-setup、skill-finder の評価で繰り返し確認されたパターンです。これを標準的な進め方としてください。スキルの構造に問題がなければ、3〜4 回の反復で収束します。

段階	修正する内容	典型的な反復	この段階にある症状
1. 構造的な修正	挙動全体が欠けている — スキルが実行者に X を行うよう指示していない。	1 → 2	LLM グレーダーと表層グレーダーの両方が失敗し、1 回の編集後に合格率が上がる。
2. グレーダーの対象範囲	スキルは正しいが、表層グレーダーの対象範囲が狭すぎる（正規表現が 1 つの言い回しにしか一致しない）。	2 → 3	LLM グレーダーは合格し、表層グレーダーは同じ評価軸で失敗する。正規表現の範囲を広げます。LLM に 1 つの言い回しを「強制」してはいけません。
3. 表層形式の網羅	LLM が、正規表現で想定していなかった日本語／同義語／略語を使う。	3 → 4	片方の試行は合格し、もう片方は同じグレーダーで失敗する。見落としは内容の欠落ではなく、表層形式によるものです。
4. 残る不明点	残る問題はスキル本文ではなく、評価設定の構造に起因する（白紙状態の実行者は実際のツールを実行できない）。	最終段階	Self-report が「実行が停止 — Web 取得／外部コマンドを実行できない」と示す。台帳に記録し、それ以上追及しないでください。

4 回を超える反復が必要なスキルには、より根本的な設計上の問題がある可能性が高いです。グレーダーを追加する前に、スキル本文を読み直してください。

シナリオの作成（tasks/*.yaml）

必須の役割は 2 つです。

• 典型例（中央値） — ユーザーの依頼として最もよくある形式です。収束時に合格する必要があります。判定基準となるのは「スキルがそもそも機能したか」です。
• エッジケース — スキルが対処することを想定した既知の失敗パターンです。例：スキルが拒否すべき対象範囲外の依頼、またはスキルが別の関連スキルに委ねるべき領域。

落とし穴：白紙状態の実行者は外部ツールを実行できません

waxa は claude -p --no-session-persistence --disable-slash-commands と、外部ツールを明示的に禁止するシステムプロンプトを使って実行者を呼び出します。実行者は apm view を実行したり、Web URL を取得したり、ファイルを一覧表示したりできません。ワークフローでこれらが必要になる場合は、シナリオのプロンプトにこの制約を明記してください。

inputs:
  prompt: |
    <task description>
    Real network fetches and `apm view` calls are not available;
    narrate the workflow you would run and the candidates you would
    expect, with rubric application and waxa eval / pinning notes.

この説明がないと、実行者は実行できないフェーズを Self-report で「実行：停止」と記録します。これは誤ったシグナルであり、問題はスキルにありません。

落とし穴：期待する出力形式が指定されていないプロンプト

プロンプトが「スキルの一覧を教えて」と指示していても、グレーダーの正規表現が playwright-test というトークンそのものを必要とする場合、実行者はユーザーの意図を満たしつつ正規表現には一致しない同義語を出力することがあります。次のいずれかを行ってください。

• 回答に含める必要がある内容をプロンプトで列挙する（不自然さは増します）、または
• すべての表層グレーダーに意味的な LLM グレーダーを組み合わせる（推奨 — 以下を参照）。

グレーダーの選定

4 種類あります。ペアで使用してください。

種類	用途	コスト	失敗モード
text（regex）	表層的な文字列の有無	ほぼ無料	範囲が狭すぎると、同義語／日本語／略語を見逃します。幅広い選択肢を含むパターンをデフォルトにしてください。
code（JS expr）	出力に対する構造的なアサーション（行数、JSON の形状）	ほぼ無料	書式の変化に弱いため、内容ではなく形状の確認に限定してください。
self-report	フェーズの追跡／不明点に関する規律	ほぼ無料	LLM は常に「OK」と自己報告する可能性があります。別のグレーダーと組み合わせてください。
llm（LLM-as-Judge）	意味的な同等性と評価基準のチェック	高コスト	非決定的です。trials_per_task ≥ 2 で合格率を確認してください。

標準的なペアのパターン

各動作軸について、2 つのグレーダーを作成します。

1. 意図的に幅広い選択肢を含む表層的な text グレーダー。目的：決定的かつ高速に、明白な見落としを検出します。
2. 複数の条項からなる評価基準を持つ llm グレーダー。目的：意味的に同等な表現を検出し、ニュアンスを判断します。

同じ軸で LLM グレーダーは合格し、表層的なグレーダーは不合格になる場合は、表層的な正規表現の範囲を広げてください（ステージ 2）。特定の言い回しを強制するようにプロンプトを変更しないでください。スキルの自然な出力が歪められます。

実際に役立つ正規表現のカバレッジ

• 日本語と英語：スクレイプ と scrape、非互換 と incompatible、信頼 と trust。必ず両方を含めてください。
• バージョン固定に関する用語：pin to a tag、pinned via SHA、resolved with apm view、tag-pinned。幅広い選択肢を 1 つのパターンに含めてください。
• 「停止」の同義語：stop、do not adopt、refuse、reject、defer、redirect。

便利なテンプレート：

- name: pinning_vocab
  type: text
  config:
    regex_match:
      - "(?i)(pin(ned|ning)?\\s*(to|via|with)?\\s*(a\\s+)?(tag|sha|ref|version))|(apm\\s+view)|(adopt.*after.*eval)"

自己報告 — 確認すべき内容

各試行の末尾に、構造化された自己報告ブロックが追加されます。以下のフィールドを確認してください。

• フェーズの追跡 — Understanding / Planning / Execution / Formatting。「stuck」という項目は、トリアージの手掛かりになります。プロンプトが不明瞭だったのか、それともそのフェーズに関する指示がスキルに不足しているのかを確認してください。
• 不明点 — 最も有用な診断情報です。それぞれに Issue / Cause / General Fix Rule があります。台帳に記録するのは Rule です。
• 裁量による補足 — 実行者が独自に補った箇所です。いずれも「スキルで明示すべきこと」の候補です。
• 再試行 — 正常な実行では 0 であるべきです。> 0 は、タスクの途中でスキルに確認が必要だったことを意味します。

問題のない実行では、すべてのフェーズが OK、不明点が 0、補足が（なし）、再試行が 0 です。不明点が 0 になった後の次の妥当な目標は、再び不明点を 0 にすることです。この状態が 2 回連続すれば収束です。

台帳のパターン（evals/<skill>/ledger.yaml）

反復ごとに 1 エントリを記録します。スキーマ（作業用フィールドのみ）：

iterations:
  - id: iter-N
    date: YYYY-MM-DD
    scope: <full or per-task>
    overall_pass_rate: <number>
    per_task: [...]
    unclear_points:
      - issue: ...
        cause: ...
        general_fix_rule: ...        # this is the durable artifact
    actions:
      - <one-line summary of the change made>

convergence:
  status: <converging | near_convergence | converged>
  rationale: |
    <why you stopped — be specific about what residuals remain>

一般的な修正ルールの抽出

不明点を見つけたら、どの種類の誤りがこれを引き起こしたのかを考えてください。「今回、具体的に何が問題だったのか」ではなく、どのような形の誤りが、常にこの種の失敗を引き起こすのかを考えます。一般化できるのはクラスレベルのルールであり、追跡記録は単なる事例です。

Issue:    "skill never told executor to stop when catalog has a fit"
Cause:    "When NOT to use" stated alternative but didn't enforce halt
General Fix Rule:
  Meta-skills that delegate to a sibling must add a mandatory
  pre-flight check that explicitly halts the workflow (not merely
  advises an alternative).

このルールは複数のスキルで再利用できます。同様のパターンに遭遇した今後の評価では、ルールを再発見するのではなく、既存のルールを参照してください。

収束

empirical-prompt-tuning では、収束を不明点がゼロの実行が 2 回連続することと定義しています。実際には、次のように扱います。

• 評価の設定に構造的に起因する残存不明点（例：「URL を取得できない」）は、収束を妨げません。台帳に記録し、収束のカウントから除外してください。
• 非決定的な残存不明点（一方の試行では検出され、次の試行では検出されない）は、弱い兆候です。スキルがほかの点で安定しており、不明点が対応のしきい値を下回っている場合は、収束と判断してください。
• 決定的で内容に関連する残存不明点は、収束を宣言する前に対処する必要があります。これはステージ 1 の作業であり、完了処理ではありません。

台帳に記録します。

convergence:
  status: converged
  rationale: |
    Iter 1 (X%) → Iter 2 (Y%) → ... → Iter N (Z%).
    Residual <name> is <reason it does not block adoption>.

テストレイアウトの規約

waxa 0.2.0 以降、評価ファイルはagentskills.io のスキル評価レイアウトにならって、スキルディレクトリ内に配置します。これにより、単一のスキルリポジトリに独自の評価スイートを含め、自己完結した単位として配布できます。

<skill>/                                # the target skill (distribution unit)
├── SKILL.md
└── evals/
    ├── eval.yaml                       # config + top-level graders + task glob
    ├── ledger.yaml                     # iter history (created on first `iterate` run)
    └── tasks/
        ├── scenario-typical.yaml       # median — passes at convergence
        └── scenario-edge.yaml          # known failure mode — exercises the rule

ワークスペース（反復ごとの実行結果）は、スキルの外に <workspace-root>/results/<skill>/iteration-N/<task-id>/<with_skill|without_skill>/{output-trial-*.txt, timing.json, grading.json} と benchmark.json の形式で配置されます。.waxa.yaml / .waza.yaml が存在する場合、<workspace-root> はそのディレクトリです。存在しない場合は、スキルディレクトリの親ディレクトリです。.gitignore に results/ を追加してください。

waxa init は TODO マーカー付きの eval.yaml と 2 つのタスクテンプレートを生成します。ledger.yaml は反復の開始時に生成されます。

0.2.0 より前のモノレポレイアウト（<repo-root>/evals/<skill>/eval.yaml + <repo-root>/<skill>/SKILL.md）も引き続き自動検出されるため、既存の評価はそのまま動作します。新しい評価ではスキル内のレイアウトを使用してください。

ループの実行

最低限の実行方法：

# Scaffold the eval skeleton (run inside the skill's own dir).
npx @mizchi/waxa init [--skill <name>] [--force]

# Single eval pass.
npx @mizchi/waxa <skill>/evals/eval.yaml

# Single task.
npx @mizchi/waxa <skill>/evals/eval.yaml --task <task-id>

# Single eval with baseline (with_skill vs without_skill, reports Delta).
npx @mizchi/waxa <skill>/evals/eval.yaml --baseline

# Iteration loop (auto re-runs while pass rate improves; writes ledger.yaml).
npx @mizchi/waxa iterate <skill>/evals/eval.yaml --max 4

# Audit a skill directory (apm audit hidden-Unicode scan + waxa native
# quality checks: frontmatter, body length, When-NOT-to-use, suspicious
# scripts, LICENSE).
npx @mizchi/waxa audit <skill>/ [--no-apm] [--json]

npm パッケージには references/empirical-prompt-tuning.md が同梱されているため、waxa をインストールした場所であればどこでも方法論を参照できます。npx @mizchi/waxa の初回実行後、このファイルは <node_modules>/@mizchi/waxa/references/empirical-prompt-tuning.md に配置されます。

--baseline — スキルに価値があるか？

--baseline は各タスクを試行ごとに 2 回（with_skill と without_skill）実行してから、Delta 行を出力し、両方の設定を iteration-N/<task-id>/ に書き込みます。これは、agentskills.io 方式の「スキル本文によって、何もない状態のモデルより実際に改善するか？」を確認する方法です。合格率を上げずにトークン数やレイテンシだけを増やすスキルも、単一設定での実行ではわからない形で確認できます。

1 反復あたりの所要時間（claude-opus-4-8、3 シナリオ × 2 試行）：実時間で約 3〜5 分です。反復は順番に実行してください。同じ評価に対して waxa プロセスを並列で起動しないでください。API とロックファイルを取り合うことになります。単一タスクの実行（--task <id>）は、スイート全体を再実行せずに小さな変更を確認するのに便利です。

trials_per_task: 2 が最低値です。1 回の試行では、「スキルが不安定」なのか「LLM のサンプルが悪かった」だけなのかを判別できません。重要な評価軸で非決定性が疑われる場合に限り、3 に増やしてください。

よくある落とし穴

間違い	対処法
スキルを編集せずに反復を再実行する	スキル本文が変わっていなければ、結果が変わるのは LLM のサンプルが異なるだけです。再実行する前に編集してください。
LLM グレーダーだけを使う	非決定的で、処理も遅くなります。サーフェスグレーダーと併用してください。
失敗のたびにグレーダーを追加する	安全網となるのはグレーダーではなく、スキルです。測定されていない挙動が重要な場合にのみ、グレーダーを追加してください。
executor: mock を実際の設定として扱う	現在の tools/waxa/src/cli.ts はこのフィールドを無視し、すべての実行で claude -p を使用します。それに応じて予算を計画してください。
4 回を超えてもスキルを読み直さず反復する	4 回を超えても失敗を追い続けているなら、スキル本文に構造上の欠陥があります。反復を止めて、そのセクションを書き直してください。
台帳をコミットしない	台帳は永続的な成果物です。今後の評価は、過去の General Fix Rules を土台にします。台帳を失うと、組織の知見も失われます。

empirical-prompt-tuningとの範囲の違い

このスキルは実装ガイドであり、empirical-prompt-tuningは方法論です。両者は相補的であり、どちらかがもう一方を包含することはありません。ディスパッチの仕組みが異なるためです（Task-toolのサブエージェントと、外部CLIプロセス）。

懸念事項	waxa-eval	empirical-prompt-tuning
方法論／第一原理（バイアスのない実行者、Self-reportの根拠）	（参照）	担当
CLIの操作（waxa run / iterate / variant / compare）	担当	該当なし
シナリオYAMLの作成	担当	該当なし
グレーダーの選択（text / code / self-report / llm）	担当	該当なし
実際のiterループから導き出したIterパターン（4段階のシグネチャ）	担当	該当なし
台帳スキーマ（ledger.yaml）とGeneral Fix Ruleの抽出	担当	共有
収束の定義（不明点が2回連続でゼロ）	共有	正式版を担当
Iter 0の説明／本文の一貫性チェック（静的、ディスパッチなし）	該当なし	担当
tool_usesの相対値分析（Task-toolのサブエージェントを介する場合のみ可能）	該当なし	担当
要件チェックリストの[critical]タグ	該当なし	担当
修正の伝播パターン（保守的／過剰修正／ゼロ修正）	該当なし	担当
ペアワイズ比較の注意事項（順序のカウンターバランス）	（参照）	担当
構造レビューのモード（実行ではなくテキストの一貫性のみ）	該当なし	担当
環境上の制約（現在のセッションでTaskツールが利用できない）	該当なし	担当
危険信号の表（自己再読による正当化など）	該当なし	担当

次の場合はempirical-prompt-tuningを使用してください： Task-toolのサブエージェントへのディスパッチを通じてClaude Codeのセッション内で評価する場合、実行者のtool_uses測定が必要な場合、Iter 0の静的な一貫性チェックを実行する場合、[critical]タグ付きの要件チェックリストを作成する場合。

次の場合はwaxa-eval（このスキル）を使用してください： 外部CLIプロセスとして評価を実行する場合、反復履歴を再現性やCIのためにYAMLで永続化する場合、スキルを編集するたびに再実行するシナリオを記述する場合、採用前に外部のスキル候補を評価のゲートにかける場合（skill-finderを参照）。

実際のワークフローでは、多くの場合、両方を使用します。セッション内のIter 0と最初のディスパッチにはempiricalを使って方向性を確認し、その後のiterループと永続的な台帳にはwaxa-evalを使用します。

関連項目

• empirical-prompt-tuning — このスキルが実用化する方法論。役割分担については上記の範囲の表を参照してください
• superpowers:writing-skills — スキル向けのTDDの考え方。このスキルと組み合わせて使用します（スキルを作成 → 評価 → 反復）
• skill-finder — 異なるソースからの候補を採用する際のゲートとしてwaxa-evalを使用します
• tools/waxa/README.md — CLI引数のリファレンス
• tools/waxa/RFC-waza.md — 上流のwazaとの互換性に関する注意事項