bmad-eval-runner

スキル評価ランナー

スキルの評価を実行し、その結果を報告します。ユーザーが求めているのは演出ではなく、有益な情報です。そのため、具体的な調査結果を示し、些細な理由で合格している評価を明らかにし、実行が成功したように見せるために許容範囲を決して広げないでください。

このランナーはプラットフォームに依存しません。スキルの呼び出し方、認証情報の取得元、トランスクリプトの形式など、実行時にプラットフォーム固有となるものはすべて、references/platform-adapter.md に記載されたアダプターの接続部を介します。このスキル内にモデル名はハードコードされていません。

4 つのモード

各モードは、スキルについてそれぞれ異なる問いに答えます。ユーザーの依頼に合うモードを選ぶか、複数を実行してください。

モード	答える問い	スクリプト／リファレンス
baseline	同じ入力で、スキルはベースモデルを上回りますか？	references/eval-format.md、scripts/run_evals.py
variant	あるセクションは残す価値がありますか？ それとも、削ったバージョンでも同じ結果になりますか？	references/eval-format.md、scripts/run_evals.py
quality	出力は指定されたルーブリックを満たしていますか？	references/grader.md、references/eval-format.md
trigger	説明は適切なクエリで発動し、それ以外では発動を控えますか？	references/platform-adapter.md、scripts/run_triggers.py

Baseline では、すべてのケースを 2 回実行します。1 回目はスキルをクリーンな作業ディレクトリに配置し、2 回目は何も配置せずに実行します。これにより、同一条件でベースモデルを長期的な下限として測定します。Variant では、スキル全体と、それを削った最小バージョンを比較し、セクションが実際に役立っているかを確認します。Quality では、読み取り専用のグレーダーを使って、1 つの設定の出力をルーブリックに照らして採点します。Trigger では、アダプターを通じて実際の発動を測定し、複数のラウンドを通して説明を最適化できます。最適化のループについては references/description-optimization.md を参照してください。

ケースは input + rubric + optional state_prefix + optional fixture files で構成されます。state_prefix は、入力の前に付加する角括弧で囲まれたプライムです。1 回の入力でスキルをワークフローの途中の状態に置けるため、複数ターンのシミュレーターがなくても任意のターンを試せます。ケースの完全な形式と、期待値を強弱で分類する方法については references/eval-format.md を参照してください。

引数

• 位置引数：評価対象のスキルへのパス（SKILL.md を含むディレクトリ）。
• --evals <path>：ケースファイルへの明示的なパス。省略した場合は自動検出します。
• --mode baseline|variant|quality|trigger：実行するモード。複数回指定できます。
• --variant-path <path>：variant モードで比較する、削減版または以前のバージョンのスキルへのパス。
• --project-root <path>：スキルが属するプロジェクトのルート。デフォルトでは、スキルのパスから上位へたどり、_bmad/ または .git/ を探します。
• --output-dir <path>：実行フォルダーの出力先。デフォルトは、設定されていれば {bmad_builder_reports}/eval-runs/、そうでなければ ~/bmad-evals/ です。
• --runs <n>：ばらつきのベンチマークで、ケースごとに繰り返す回数。単一の確認ではデフォルトは 1 です。ユーザーが安定した平均値を求める場合は、より大きい値を指定します。
• --headless / -H：非対話モードで実行し、最終 JSON のみを出力します。

これらは、以下のスクリプト CLI に直接対応しています。ケースのサブセット、タイムアウト、ワーカー数など、ここに記載されていない項目については、スクリプトの docstring を参照してください。

有効化時

1. bmad-workflow-builder と同じ方法で設定を解決します（{project-root}/_bmad/config.yaml、次に config.user.yaml、いずれもない場合は bmb/config.yaml）。{user_name}、{communication_language}、{bmad_builder_reports} を解決し、セッションに適用します。

2. --headless が指定されている場合は、{headless_mode}=true に設定し、以下の確認をすべて省略して、最も安全なデフォルトを選択して続行します。

3. 再開チェック：出力ディレクトリを検索し、進行中の実行の .memlog.md があるか確認します。存在し、このスキルに一致する場合は、一度読み込んで状態を復元し、追記のみで続行します。決定や方針変更があったら、scripts/memlog.py を通じて実行の memlog に記録します。

4. スキルを特定し、<skill-path>/SKILL.md が存在することを確認します。存在しない場合は、明確なエラーを出して停止します。

5. references/platform-adapter.md の検出ルールに従ってアダプター設定を解決します（明示的な --adapter、BMAD_EVAL_ADAPTER、ケースファイルの隣にある adapter.json）。何も設定されておらず、現在のランタイムが Claude Code の場合は、{skill-root}/assets/adapter-claude-code.json を使用します。

6. ケースファイルを検出します。まず --evals、次に <skill-path>/evals/、<skill-path>/../../evals/<skill-name>/、<project-root>/evals/<skill-name>/、最後に <project-root>/evals/ 以下全体を確認します。最初に見つかったものを使用します。見つからない場合は停止してその旨を伝えます。ランナーがケースを作成することはありません。

7. ヘッドレスモードでない場合は、実行の概要（スキル、見つかったケース、モード、出力ディレクトリ）を確認してから実行します。

実行

各ケースはクリーンな作業ディレクトリで実行されます。テスト対象のスキルはそのディレクトリにステージングされ、環境は一から構築されるため、ホストのシェル設定、過去の実行、親ディレクトリにある指示ファイルが結果に影響することはありません。分離に関する仕様は references/platform-adapter.md に記載されています。コンテナも、ターミナルエミュレーションも、認証情報のステージングもありません。

ベースライン、バリアント、品質の各モードでは：

uv run {skill-root}/scripts/run_evals.py \
  --cases <cases-file> --skill-path <skill> --output-dir <dir> \
  --mode quality|baseline|variant [--variant-path <skill>] \
  [--adapter <adapter.json>] [--runs N]

スクリプトはスキルとケースのフィクスチャをステージングし、入力に state_prefix を適用してから各設定を実行します（ベースライン＝スキルをステージングした状態と何もない状態、バリアント＝スキルと --variant-path）。結果は <run-dir>/<config>/<case-id>/ に書き込みます。各呼び出しの完了時に、タイミングとトークン数を取得して直ちに timing.json に書き込むため、その後クラッシュしても測定値は失われません。

トリガーモードでは：

uv run {skill-root}/scripts/run_triggers.py \
  --skill-path <skill> --queries <queries-file> --output-dir <dir> \
  [--adapter <adapter.json>] [--runs-per-query N]

ランタイムがスキルを検出する場所に合成スキルをステージングし、各クエリをアダプター経由で送信して、スキル読み込みツールの呼び出しを検出します。安定性を確認するため、各クエリを複数回実行します。単に測定するだけでなく、ユーザーが説明文の最適化を希望する場合は、references/description-optimization.md に従います。

品質モードでは、ケースごとに references/grader.md に記載された評価器を起動し、ケースのルーブリック、トランスクリプトのパス、成果物ディレクトリ（ケースの cwd/）、および <case-folder>/grading.json を指定する grading_path を渡します。評価器はそのファイルを書き込み、部分点は与えず、弱い主張や判別力のない主張を指摘します。そのフィードバックを伝えてください。評価器のサブエージェントでエラーが発生した場合、そのケースを grading_error として記録します。デフォルトの判定で代用してはいけません。

--runs が 1 より大きい場合は、uv run {skill-root}/scripts/aggregate_benchmark.py --baseline <run-dir>/<config-a> --variant <run-dir>/<config-b> を呼び出して、平均、標本標準偏差、最小値、最大値、および設定間の差分を算出します（単一設定のばらつきを算出する場合は --runs <run-dir>/<config>）。

実行に失敗した場合、または結果が不十分で、ユーザーがその結果をもとにスキルを改善したい場合は、references/self-improvement.md に従います。

アーティファクト

実行のたびに、出力ディレクトリ内に日付付きの実行フォルダーが作成され、これらのアーティファクトは永久に保存されます。各ケースフォルダーには、プロンプト、トランスクリプト、スキルが書き込んだファイルを含む cwd/、timing.json、そして品質モードを実行した場合は grading.json が格納されます。実行フォルダーを削除、上書き、またはローテーションしないでください。ディスク使用量をどうするかはユーザーが決めます。実行の .memlog.md には判断や差分が記録されるため、実行を再開した場合や監査する場合にも、内容を明確に読み返せます。

完了したら、実行フォルダーの場所をユーザーに伝えてください。

結果

• 実行結果には、メモリや設定を備えたホストシェルの動作ではなく、クリーンな作業ディレクトリでのスキルの動作が反映されます。
• 実行時間とトークン数は、測定された時点でディスクに保存されます。
• 失敗は具体的な期待事項を根拠とともに示し、表面的な合格は取り繕わずに指摘します。
• スキルがベースラインの実行に勝てなくなった場合は、スキルを修正するのではなく、廃止を検討します。