evals でプラグインをテストする

claude plugin eval シェルコマンドはプラグインをテストケースのスイートに対して実行し、結果をスコア化します。各ケースは現実的なプロンプトと 1 つ以上のグレーダーで構成されます。グレーダーは Claude が生成したものに対する合格/不合格チェックで、返信に対する正規表現、特定のツールが呼び出されたかどうか、または第 2 のモデルが返信を判定するルーブリックなどです。スイートを手動で作成する必要はありません。claude plugin eval init はプラグインについて質問し、ケースとグレーダーを提案し、それらを試し、ファイルを作成します。既に開いているセッションから Claude に同じことを行うよう依頼することもできます。 evals を使用して以下を実行します。

プラグインがどの程度確実に Claude を正しい結果に導くかを測定する
プラグインを変更したり新しいモデルがリリースされたりしたときの回帰を検出する
プラグインなしの場合と比較してプラグインが何を貢献しているかを確認する

このページはプラグインとスキル作成者向けで、動作するプラグインがあり、その動作をテストしたい場合、および CI でプラグイン変更をゲートするチーム向けです。Claude Code 会話内で 1 つのスキルを反復処理する場合、skill-creator プラグインは独自の evals/evals.json 形式で同様の比較を実行し、どちらのツールも他方のケースファイルを読み込みません。プラグインを作成するにはプラグインを作成するを参照してください。プラグインの動作ではなく構文とスキーマエラーをチェックするには、claude plugin validate を使用します。

すべての eval 実行とすべてのジャッジグレーダーは、アカウント上の実際のモデル呼び出しで、プランの使用量または API 請求に対してカウントされます。そのため、最初に要件を確認してください。その後、最初の eval スイートを作成するか、既にスイートがある場合は CI で evals を実行に進んでください。

要件

プラグイン evals を実行するには、以下が必要です。

Claude Code v2.1.269 以降。claude --version で確認し、claude update でアップグレードしてください。
Git 2.31 以降（Git がインストールされている場合）。git --version で確認してください。古いバージョンの Git では、claude plugin eval はケースを実行する前に停止します。Git がない場合は、通常どおり実行されます。
plugin.json または .claude-plugin/plugin.json マニフェストを含むプラグインディレクトリ、または skills-directory プラグイン。
通常の Claude Code セッションで使用するのと同じ認証とモデルプロバイダー。Eval 実行、judge-scored graders、および claude plugin eval init はユーザーの認証情報でモデルを呼び出すため、プランの使用制限または API 請求に対してカウントされます。コマンドがコストを報告する場合、その数値はそれらの呼び出しの定価見積もりです。Amazon Bedrock、Google Cloud の Agent Platform、または Microsoft Foundry で Claude Code を実行している場合は、通常のセッションと同じプロバイダー変数をエクスポートするシェルからスイートを実行してください。env フィールドで説明されているとおり、各実行はそのシェルからこれらの変数を継承するためです。

eval 実行の仕組み

eval スイートはプラグイン内の evals/ というディレクトリに存在し、ケースを作成して改善するに示すようにレイアウトされます。各ケースはプロンプトと 1 つ以上のグレーダーを含む独自のサブディレクトリです。プロンプトは、プラグインを使用している人が入力するようなもので、そのスキルの 1 つが処理すべきリクエストなどです。

実行中に何が起こるか

ケースの各実行について、Claude Code は新しい分離された非対話型セッションを開始し、プラグインのみをロードし、プロンプトを送信し、Claude が完了するか、ケースのターン制限または時間制限に達するまで動作させます。その後、各グレーダーは最終的な返信、トランスクリプト、または Claude が作成したファイルをチェックし、合格または不合格を判定します。

ケースのスコア化方法

非決定論的なエージェントの 1 回の実行では、ほとんど情報が得られないため、各ケースはデフォルトで 3 回実行されます。実行のスコアは、重み付けを設定した場合は重み付けされた、合格したグレーダーの割合であり、ケースのスコアは実行全体の平均です。ケースは、そのスコアが --threshold（デフォルトは 1.0）を満たすときに合格します。モデル呼び出しでは、スイートはおおよそ cases × runs のエージェント実行をプラグインで行い、プラグインなしベースラインでも同じ数だけ行い、さらに実行ごとに llm または baseline グレーダーごとに 3 つの短いジャッジ呼び出しを行います。

プラグインなしベースライン

プラグインなしでも Claude が同じくらい上手くいく可能性があるため、単独のスコアが高いだけではプラグインが役に立ったことを示しません。この 2 つを分離するために、各ケースの実行はプラグインをロードせずに繰り返され、2 つのスコア WITH と W/OUT が得られます。その差 Δ は、プラグインが貢献したものです。ケースがプラグインの有無にかかわらず 1.0 でスコアされた場合、プラグインはそれが合格した理由ではありません。 2 つの実行セットは with-arm と without-arm と呼ばれます。プラグインなしベースラインに対してスコアを付けるでは、どのケースが with-arm のみを実行するか、およびグレーダーが 2 つの arm にわたってどのようにスコア化されるかについて説明します。

最初の eval スイートを作成する

このチュートリアルは、独自のプラグイン用に 1 つのケースを作成し、実行し、結果を読みます。開始する前に、以下があることを確認してください。

Claude Code v2.1.269 以降およびその他の要件
プラグインのルートディレクトリで開いているターミナル（plugin.json または .claude-plugin/plugin.json を含むディレクトリ）
テストしたいプラグイン内の 1 つのスキルと、ユーザーが入力すべきリクエスト（それがスキルをトリガーすべき）

ケースを作成する

プラグインルートから、以下を実行します。

claude plugin eval init

Claude Code がこのディレクトリをまだ信頼していない場合、最初に Trust this plugin directory? と尋ねます。y で答えてください。その後、対話型 Claude Code セッションが開きます。Claude はプラグインを読み、良い結果がどのようなものかを尋ね、プラグインをトリガーすべき、またはトリガーすべきでないプロンプトを提案し、各プロンプト用のグレーダーを設計し、それらを試行として 1 回実行して動作を確認し、evals/ の下にプロンプトごとに 1 つのケースディレクトリを作成します。各ディレクトリにはそのプロンプトに基づいた名前が付けられます。Claude がスイートの準備ができたことを伝えたら、/exit または Ctrl+D でそのセッションを終了してシェルに戻ります。プラグインルートで既に Claude Code セッションが開いている場合は、代わりにそこで Claude に claude plugin eval init を実行するよう依頼できます。Claude はコマンドを実行し、その会話で同じ質問をします。ケースを自分で作成して、ファイルが正確に何を含むかを確認したい場合は、ケースを手動で作成するに従い、ここに戻ってそれを実行します。

スイートを実行する

プラグインルートのシェルに戻り、evals/ の下のすべてのケースを実行します。

claude plugin eval .

ステップ 1 でこのディレクトリを既に信頼しているため、実行はすぐに開始されます。代わりにケースを手動で作成した場合、実行は最初に Trust this plugin directory? [y/N] と尋ねます。y で答えてください。実行がアクセスできるものは、同意していることを説明します。各ケースはプラグイン付きで 3 回、プラグインなしで 3 回実行されるため、1 つのケースは 6 回の実行です。各実行が完了すると、その実行のスコアと各グレーダーの判定を含む進捗行が出力されます。

サマリーを読む

スイートが完了すると、サマリーテーブルが表示され、その後にレポートの場所が表示されます。

CASE        WITH  W/OUT Δ      RUNS COST    NOTES
first-case  1.00  0.33  +0.67  6    $0.41

1 case(s) · mean Δ +0.67 · 74s · $0.41
Report: /Users/you/my-plugin/evals/results/2026-09-10T17-02-11-482Z/report.html
Published: https://claude.ai/... · keep local next time with --no-publish

WITH はプラグインをロードしたケースのスコア、W/OUT はロードしないでのスコア、正の Δ はプラグインがスコアを上げたことを意味します。COST はモデル呼び出しの定価見積もりで、NOTES は最も高い重みの失敗したグレーダーの説明、または with-arm の実行エラーを示します。

レポートを開いて反復する

Published: URL、または Published: 行が表示されない場合は Report: パスを開いて、すべての実行のすべてのグレーダーの判定と説明を確認し、llm グレーダーについてはジャッジの投票と判定した抜粋を確認します。Published: 行は、アカウントがレポートを公開できる場合にのみ表示されます。最初の一般的な発見は、ケースの tool_used: Skill グレーダーが失敗している Δ がほぼゼロで、Claude が自然な表現でスキルを選択していないことを意味します。スキルの description を調整し、claude plugin eval . を再度実行し、比較します。実行回数を減らして 1 つのケースを反復するには、1 つの arm を 1 回実行します。1 回の実行はノイズが多いため、信頼する前にデフォルトの 3 回で変更を確認してください。1 つの arm では、テーブルは WITH、W/OUT、Δ の列の代わりに SCORE と PASS% の列を表示します。

claude plugin eval . --case <case-name> --runs 1 --ablation none

<case-name> を evals/ の下のディレクトリ名の 1 つに置き換えます。

ケースを作成して改善する

claude plugin eval init が作成するケースは、開いて変更し、追加できるプレーンファイルです。ケースはプラグインの eval ディレクトリの下のディレクトリで、prompt.md、case.yaml、またはその両方を含みます。グレーダーのないケースは読み込みに失敗するため、各ケースには graders/<name>.md ファイルまたは case.yaml の graders: エントリとして、少なくとも 1 つのグレーダーを付与してください。ケースをグループ化するには、それ自体がケースではないディレクトリの下にネストします。graders/ やフィクスチャファイルなど、ケースディレクトリ内のすべてはそのケースに属します。これは claude plugin eval init が作成するレイアウトで、新しいスイートに使用するレイアウトです。eval スイートリファレンスには、モックと結果を含む完全なツリーがあります。

my-plugin/
├── .claude-plugin/plugin.json
├── skills/...
└── evals/
    ├── first-case/
    │   ├── prompt.md          # frontmatter: case fields; body: the prompt
    │   ├── graders/
    │   │   ├── criteria.md    # frontmatter: type + options; body: rubric or pattern
    │   │   └── skill-fired.md
    │   └── case.yaml          # optional: only for context.* fields
    ├── ignores-unrelated-request/
    │   └── ...
    └── results/               # written by each run; add to .gitignore

ケースを手動で作成する

Claude にケースを claude plugin eval init で作成させることが推奨パスです。代わりに自分で作成するには、空のテンプレートから開始します。次のコマンドは、プレースホルダー prompt.md と 1 つのプレースホルダーグレーダーを含む first-case という名前のケースを作成し、何も実行しません。

claude plugin eval init --bare first-case

evals/first-case/
├── prompt.md            # the prompt sent to Claude, plus run limits
└── graders/
    └── criteria.md      # one grader: how to score the result

prompt.md では、各実行で Claude が受け取るメッセージを作成し、フロントマターで実行の制限とケースが使用できるツールを設定します。evals/first-case/prompt.md を開き、プレースホルダー本文をスキルの 1 つが処理すべきリクエストに置き換えます。スキル名を挙げるのではなく、ユーザーが入力するであろう表現で記述してください。この例はコミットメッセージを作成するスキル用です。独自のリクエストを使用してください。

---
max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
---

Write me a commit message for this change: I renamed getUser to fetchUser and updated the three call sites.

各実行は空の作業ディレクトリで開始されるため、タスクに必要なものをプロンプト自体に含めるか、先にワークスペースをセットアップしてください。フロントマターフィールドの完全なリストは、モデル、タイムアウト、タグ、および環境変数をカバーしています。 graders/ の下の各ファイルは、実行後に適用される 1 つのチェックです。evals/first-case/graders/criteria.md を開き、プレースホルダーをジャッジモデル用のルーブリックに置き換えます。具体的な PASS および FAIL 条件として作成されます。

---
type: llm
---

PASS if <what a correct response contains>.
FAIL if <what a wrong or missing response looks like>.

その後、スキルが答えを生成したかどうかをチェックする 2 番目のグレーダーを追加します。evals/first-case/graders/skill-fired.md を作成し、your-skill-name をスキルのディレクトリ名（skills/ の下）に置き換えます。これは Claude が呼び出す名前です。

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'
---

これは Claude がその実行中にそのスキルを少なくとも 1 回呼び出した場合に合格します。これには、その名前空間付き plugin-name:skill-name 形式も含まれます。グレーダータイプは、正規表現のマッチングやファイルが作成されたことの確認など、利用可能な他のチェックをリストします。両方のファイルを保存したら、クイックスタートが行うように、プラグインルートから claude plugin eval . でケースを実行します。

prompt.md で実行制限とツールを設定する

prompt.md フロントマターでケースの max_turns、timeout_seconds、model、tags、および使用可能な allowed_tools を設定します。prompt.md フロントマターリファレンスはすべてのフィールドとそのデフォルトをリストします。 Claude は本文を正確に作成したとおりに受け取ります。その中の @path メンションはファイル添付に展開されないため、Claude がファイルを読む必要がある場合は、allowed_tools でツールを付与します。

グレーダーを選択して重み付けする

グレーダーのフロントマターはその type を設定し、オプションで実行のスコアでより多くをカウントする weight と、ベースラインに対してどのようにスコア化されるかを制御する arm を設定します。6 つのタイプのうち、regex、tool_used、tool_order、file_exists はトランスクリプトとファイルから計算され、コストはかかりませんが、llm と baseline はジャッジモデルを呼び出し、実行のコストに追加されます。カスタムコードグレーダーはありません。グレーダータイプは各タイプのオプションと合格条件をリストし、グレーダーが見ることができるものは target と focus が受け入れる値をリストします。デフォルトでは、llm および baseline グレーダーのジャッジは、Claude Code がバックグラウンドタスクに使用するモデルです。ジャッジを自分で選択するには、--judge-model sonnet または完全なモデル ID を渡します。

安定した信号を与えるグレーダーを選択する

llm グレーダーはモデルに判定を求めるため、その答えは実行間で異なる可能性があり、読む必要があるテキストが長いほど異なります。これらの習慣はスイートのスコアを十分に安定させて信頼できるようにします。

生成されたファイルなどの長い出力については、ファイルの内容に対する regex グレーダーでグレード化します。これは毎回同じ方法でファイル全体をチェックします。短い出力には llm グレーダーを保持し、ルーブリックを具体的な PASS および FAIL 条件として作成します。
各ケースに、最終メッセージや生成されたファイルなどの結果に対する 1 つのグレーダーと、tool_used や tool_order など Claude がそれを生成するためにたどった手順に対する 1 つのグレーダーを付与します。一緒に、答えが正しかったかどうかと、プラグインがそれを生成したかどうかの両方を示します。
ケースの tool_used: Skill グレーダーが合格しているが Δ が負の場合、プラグインの前にジャッジを疑います。小さいジャッジモデルは、ルーブリックが説明する内容と異なる形式であるため、正しい答えを間違いとマークできます。--judge-model sonnet で再実行し、形式が判定を決定しないようにルーブリックを厳しくします。
ビルドまたはテストが実行内で合格したことを確認するには、プロンプトで Claude にそれを実行し、結果をファイルに書き込むよう依頼し、そのファイルをグレード化し、コマンドが tool_used グレーダーで実行されたことを主張します。その input_match はコマンドに名前を付けます。

プラグインなしベースラインに対してスコア化する

プラグインがテスト対象の場合、ケースは通常 2 つの arm で実行されます。with-arm はプラグインをロードした実行で、without-arm はプラグインをまったくロードせずに同じ回数行う実行です。サマリーとレポートは両方のスコアと Δ（with-arm スコアから without-arm スコアを引いたもの）を表示します。次の状況では、ケースは with-arm のみで実行されるため、W/OUT スコアや Δ は得られません。

--ablation none を渡した場合: すべてのケースが 1 つの arm で実行されます。グレーダーを反復改善している間など、比較が不要な場合にコストを半減できます。
ケースがトランスクリプトを再開し、ターゲットがパスである場合: インストール済みプラグインの名前ではなく . などのターゲットを指定すると、context.history_file ケースは、記録された会話にすでにプラグインが反映されているという前提のもと、デフォルトで 1 つの arm で実行されます。実行時には、これらのケースを示す single-arm (no Δ) 通知が stderr に出力されます。再開したターンをプラグインありとなしで比較するには、--ablation with-without を渡します。
ケースのプラグインが見つからなかった場合: ターゲットがパスのとき、Claude Code がプラグインを特定できなかったケースもデフォルトで 1 つの arm で実行されます。修正方法はベースライン arm にプラグインが表示されないを参照してください。

2 つの arm 実行では、一部のグレーダーは scored: false で報告されます。「スキルが呼び出された」などのチェックはプラグインなしでは決して合格できないため、カウントすると without-arm がゼロに向かい、Δ を膨らませます。2 つの arm を比較可能に保つために、Claude Code はそのようなグレーダーを両方の arm のスコアから除外し、with-arm でそれらを合格/不合格インジケーターのみとして報告します。これには以下が含まれます。

tool が Skill である各 tool_used グレーダー
target: mock_calls を持つ各 regex グレーダーと、各モック化されたサーバーがケース内にあり、プラグインが宣言するものである場合の focus: mock_calls を持つ各 llm グレーダー
arm: with-only でマークするグレーダー

3 つの設定がその除外を変更します。

すべてのグレーダーが除外される: ケース内のすべてのグレーダーが除外対象に含まれる場合、スコア化するものが何も残らないため、代わりに通常スコア化されます。
arm: both: グレーダーに arm: both を設定して、それに関わらず両方の arm でスコア化します。これは「スキルを呼び出してはいけない」チェックに min: 0 と max: 0 を使用する場合に必要です。
--ablation none: --ablation none の下では何も除外されないため、同じスイートは 2 つのモードで異なる絶対スコアを生成できます。

別の eval ディレクトリを使用する

evals/ が既に別のツールで使用されている場合は、スイートを別のディレクトリに保持します。プラグインの plugin.json にそのディレクトリを記録して、すべての実行とすべての共同作業者がそれを使用するようにするか、単一の実行のためにコマンドラインで渡すことができます。

plugin.json で: "experimental": { "evals": "quality/evals" } を追加します。
コマンドラインで: claude plugin eval と claude plugin eval init の両方に --eval-dir quality/evals を渡します。

両方を設定した場合、フラグのディレクトリが使用されます。qa または quality/evals などのプレーンディレクトリ名の相対パスを指定します。絶対パスまたは .. を含むパスは受け入れられません。フラグ値としてはエラーで、マニフェスト値として使用できない場合は Warning: 行が出力され、実行は evals/ を使用します。ケース、結果、および init 出力はすべてそのディレクトリに移動します。

フィクスチャとモックをセットアップする

ケースはプロンプト以上のものが必要な場合があります。ワークスペース内のファイルまたは git リポジトリ、続行する以前の会話、またはプラグインが通信する MCP サーバーからの回答。これらのそれぞれはケースの横にセットアップされるため、実行は繰り返し可能なままです。

ワークスペースまたは会話をシードする

各実行は空のワークスペースで開始されます。ケースがプロンプト以上のものが必要な場合は、context ブロックを含む case.yaml を prompt.md の横に追加します。

フィクスチャファイルまたは git リポジトリ: ケースディレクトリに Bash スクリプトを作成し、context.scaffold_script で名前を付けます。スクリプトはエージェントのサンドボックスの外でユーザー自身として実行され、--scaffold を渡したときのみ実行されるため、そのフラグはユーザー自身またはユーザーの組織が作成したスイートに対してのみ渡してください。
以前の会話を続行する: トランスクリプトを .jsonl ファイルとして保存し、context.history_file で名前を付けます。ケースのプロンプトは次のユーザーターンになります。ターゲットがパスの場合、このようなケースはデフォルトでベースラインアームなしで実行されます。
実行中に Claude が読むことができるフィクスチャディレクトリ: context.add_dirs にそれらをリストします。

case.yaml には schema_version: "1.1" と name も必要です。case.yaml フィールドリファレンスには完全なリストがあります。この case.yaml はスクリプトからワークスペースをシードし、Claude が resources/ ディレクトリからフィクスチャを読むことができるようにします。

schema_version: "1.1"
name: changelog-from-diff
tags: [smoke]
context:
  scaffold_script: fixture.sh
  add_dirs: [resources]

スキャフォールドスクリプトは、小さな固定環境を持つ空のワークスペースで開始されます。この環境には、シェルの PATH、実行の一時ホームディレクトリに設定された HOME、TMPDIR、および TERM=dumb などのいくつかの定数が含まれます。シェルのそれ以外のものはスクリプトに渡されず、ケースの EVAL_* 変数も渡されません。スクリプトが 0 以外で終了するか、120 秒より長く実行された場合、その実行は scaffold failed エラーでスコア 0 になります。スクリプトが書き込むプロジェクト設定は読み込まれないため、スクリプトはファイルと git の状態のためだけに使用してください。

MCP サーバーをモックする

スキルが MCP ツールを呼び出すプラグインを評価できます。その背後にある実際のサービスなしで。スイート全体の場合は evals/mocks/<server>/<tool>.md の下に 1 つのツールごとに 1 つの Markdown ファイルを配置するか、1 つのケースの場合はケース独自の mocks/ ディレクトリの下に配置します。<server> はプラグインの MCP 設定のサーバーの名前です。実行は、要求しない限り、プラグインの実際の MCP サーバーを開始しません。Claude Code は各サーバー独自の名前で代替サーバーを登録します。モックファイルを持つツールはそのファイルから回答し、--allow-tools 付与なしで許可されます。モックファイルを持たないツールは Claude で利用できません。モックがまったくないサーバーは、ケースの mocked: 進捗行に plugin_<plugin>_<server>[not started: no mock] として表示されます。ファイルの本文は、ツールが Claude に返すものです。このモックは tracker という名前のサーバー上の create_issue ツールの代わりになり、Claude が送信する入力をチェックし、タイトルをエコーバックします。evals/mocks/tracker/create_issue.md として保存します。

---
expect:
  title: string
  priority: [low, medium, high]
---

Created issue #4821: {{input.title}}

モックファイルの本文とフロントマターは、これらのオプションを受け入れます。

置換: {{input.<field>}} で呼び出しの入力からフィールドを挿入し、{{file:fixtures/{input.<field>}.json}} でモックの横のフィクスチャファイルの内容を挿入します。
expect:: expect: ブロックは入力を保護します。呼び出しがそれに違反する場合、実行はスコア 0 で中止され、理由が記録されます。そのため、ケースはプラグインがサーバーに何を求めたかを主張できます。
error: true: error: true を設定して本文をツールエラーとして返します。
type: agent: type: agent を設定してジャッジモデルが本文の指示からサーバーとして答えるようにします。エージェントモックへの呼び出しは、ケースの max_turns の 4 倍となる実行ごとの 1 つの予算を共有し、それを超えた呼び出しは実行をスコア 0 で中止します。

モックファイルリファレンスはすべてのキーと _server.md および _tools.json ファイルをリストします。呼び出し自体をグレード化するには、グレーダーを target: mock_calls に指します。プラグインの実際の MCP サーバーに対して実行するには、これらのフラグの 1 つを渡します。どちらの方法でも、これらのプロセスは実行のサンドボックスの外でユーザー自身として実行され、それらのツールには --allow-tools 付与が必要です。

--allow-real-servers: モックしていない各サーバーの実際のプロセスを開始し、モックしたツールには引き続きそれぞれのファイルから回答します。
--mocks off: mocks/ を完全に無視し、プラグインが宣言するすべてのサーバーを開始します。

エージェントモック回答を再生する

type: agent モックは --judge-model への呼び出しで答えるため、その出力は実行間で異なり、ジャッジを変更すると変わります。実行がエラーまたは中止なしで完了すると、Claude Code はエージェントモックが返した各回答を、結果ディレクトリ内の mock-recordings/ の下に保存します。そこにある ADOPT.txt を開くと、各記録と、その記録のコピー先となる .replay/<server>/ ディレクトリ（記録を生成したモックの横）を確認できます。記録をそこにコピーした後は、以降の実行で同一の呼び出しに対してモデル呼び出しなしでその記録から回答します。mocks/.replay/ を mocks/ の残りと一緒にコミットして、CI 実行が繰り返し可能になるようにします。

evals を実行する

スイートが存在すると、claude plugin eval はそれを実行します。ターゲット引数でどのプラグインとケースを実行するかを選択し、--allow-tools でケースが読み取り専用セット以上に必要とするツールを付与し、他のオプションで実行数、モデル、コスト、出力を制御します。

評価対象を選択する

ほとんどの場合、プラグインルートから claude plugin eval . を実行します。これはスイート内のすべてのケースをロードされたプラグインで実行します。単一のケースファイルを実行するか、開発中のプラグインではなくインストール済みのプラグインを評価するには、別のターゲットを渡します。

ターゲット	実行内容
プラグインのルートディレクトリ（`.` など）	その eval ディレクトリの下のすべてのケース（そのプラグインをロード）
単一の `prompt.md` または `case.yaml` ファイル	そのケース（その囲むプラグインをロード）
インストール済みプラグイン（名前、`name` または `name@marketplace`）	プラグインとその eval ディレクトリ内のケース。元の場所から、またはインストール済みコピーから読み取られます。結果は現在のディレクトリの `./evals/results/` または `--eval-dir` で `./<dir>/results/` に書き込まれます。
`name@skills-dir`	skills-directory プラグインの場合も同じ
省略	現在のディレクトリをパスとして

--case <glob> を追加してケース名でフィルタリングし、--tag <tag> を使用して指定されたタグのいずれかを持つケースを保持します。ターゲットを --tag、--allow-tools、--json の前に配置します。最初の 2 つはリストを取り、--json はオプションのパスを取るため、それぞれは後に続くターゲットを独自の値として読み取ります。

ツールを付与する

実行は権限を求めるために停止することはありません。付与しなかった許可が必要な組み込みツール（Bash、Write、Edit、WebFetch、WebSearch など）はセッションから削除されるため、Claude はそれらをまったく呼び出すことができません。実行は、ケースが allowed_tools にリストする読み取り専用ツール（Read、Glob、Grep、NotebookRead、Skill、AskUserQuestion、Agent、TodoWrite、およびタスクツール TaskCreate、TaskGet、TaskList、TaskUpdate、TaskStop）と、--allow-tools で付与するもののみを許可します。その付与は実行内のすべてのケースに適用されます。ケースが Bash、Write、Edit、WebFetch、WebSearch を使用できるようにするには、自分で付与します。

claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"

ケースが付与しなかったツールを要求した場合、進捗出力は not granted としてリストします。モックされた MCP サーバー上のツールは許可が不要です。実際のプラグイン MCP サーバー上のツールは、サーバーが開始されている必要があります（--allow-real-servers または --mocks off で）、および --allow-tools "mcp__plugin_my-plugin_github__*" などの名前による付与。プラグインの MCP ツールは mcp__plugin_<plugin>_<server>__<tool> という名前です。任意の形式で Bash を付与すると、すべてのコマンドは Claude Code の OS レベルサンドボックスの下で実行されます。書き込みは実行のワークスペースに限定され、ホームディレクトリと Claude Code 設定は読み取り不可で、ネットワークアクセスは --allow-tools "WebFetch(domain:example.com)" で付与するドメインに限定されます。サンドボックスバックエンドのないマシンで Bash または PowerShell を付与すると、Claude Code は制限なしで実行するのではなく各実行を拒否し、ケースは実行エラーを表示し、通常はスコア 0 になります。ネイティブ Windows にはバックエンドがないため、WSL2 の下でシェル付与スイートを実行します。Linux では、最初に bubblewrap と socat をインストールします。サンドボックスの前提条件を参照してください。

コマンドオプション

この表は、実行数、モデル、スコアリング、コスト、ツール付与、モック、出力のオプションをカバーしています。claude plugin eval --help を実行して完全なリストを確認します。これには --case、--tag、--eval-dir、--no-scaffold、--report、--verbose も含まれます。

オプション	デフォルト	効果
`--runs <n>`	各ケースの `runs`、またはそれ以外は 3	arm ごとのケースごとの実行
`-j`, `--concurrency <n>`	`1`	最大 1 から 8 のエージェント実行を同時に実行します。アカウントのレート制限を共有するため、これはそのレート制限を超えるスループットを上げるのではなく、壁時間を短縮します。結果はケース順を保持します。
`--model <model>`	各ケースの `model`、またはそれ以外は `ANTHROPIC_MODEL` が設定されている場合はそれ、またはそれ以外は Claude Code のデフォルト	テスト中のエージェント用のモデル。CI でモデルロールアウトがプラグイン回帰と間違われないようにそれを固定します。
`--judge-model <model>`	バックグラウンドタスク用のモデル	`llm` および `baseline` グレーダー用のモデル
`--ablation <mode>`	ケースごとに決定されます。プラグインなしベースラインに対してスコアを付けるを参照してください	プラグインが何を追加するかを測定するために、各ケースをプラグインなしでも実行するかどうか。`none` は 1 つの arm を実行します。`with-without` はプラグインなしベースラインを追加します。
`--threshold <0..1>`	`1.0`	ケースが with-arm スコアがこれ以上の場合に合格します。これ以下のケースはコマンドを終了 1 にします。
`--max-cost-usd <usd>`	上限なし	実行の定価コスト見積もりの上限（プラン使用量ではなく）。各実行開始前にチェックされます。使用後、さらに何も開始されません。既に開始された実行は完了するため、支出はそれらの実行の分だけ上限を超える可能性があります。未開始の実行が残っている場合、コマンドは部分的な結果で終了 2 になります。
`--allow-tools <tools...>`	なし	読み取り専用セット以上のツールを付与します。ツールを付与するを参照してください。
`--scaffold`	オフ	各ケースの `scaffold_script` を実行します。
`--trust-plugin`	オフ	自分で実行するコードとスイートを持つプラグインの最初の実行信頼プロンプトをスキップします。CI でジョブがプロンプトで拒否されたり待機したりしないようにそれを渡します。実行がアクセスできるものを参照してください。
`--mocks <mode>`	`record`	`record` はモックから MCP ツール呼び出しに答え、プラグインの実際のサーバーを開始せず、再生用にエージェントモック回答を保存します。`off` はモックを無視し、プラグインの実際の MCP サーバーを開始します。
`--allow-real-servers`	オフ	`--mocks record` で、モックを持たないサーバーのプラグインの実際の MCP サーバーも開始します。
`--json [path]`	オフ	結果ドキュメントを stdout に出力するか、`.json` で終わるパスに書き込みます。実行は静かです。進捗行またはサマリーテーブルはありません。
`--output-dir <dir>`	`<eval dir>/results/<timestamp>/`	`aggregate-result.json` と `report.html` が行く場所
`--no-publish`		HTML レポートをローカルに保持します。HTML レポートを参照してください。
`--publish-report`		Claude Code セッションが開始した実行など、デフォルトではローカルに留まる場所でもレポートを公開します。
`--keep-temp`	オフ	すべての実行のサンドボックスディレクトリを保持し、そのパスを出力します（Claude が生成したものをデバッグするため）。

CI で evals を実行する

CI ジョブで、--json でスイートを実行して結果をアーカイブ用に書き込み、終了コードでビルドを失敗させます。ジョブが最初の実行信頼プロンプトで待機しないように --trust-plugin を渡し、スコアが時間とともに比較可能になるように両方のモデルを固定し、レポートをローカルに保持し、コスト上限を上限として設定します。

claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --model claude-sonnet-5 \
  --judge-model claude-haiku-4-5 \
  --no-publish \
  --max-cost-usd 20

ジョブの終了コードは何が起こったかを示します。

終了コード	意味
0	スイートが合格しました。すべてのケースが `--threshold` 以上のスコアとなり、その他に実行を失敗させる要因もありませんでした。
1	ケースが閾値を下回るスコアとなった、ケースファイルのロードに失敗した、ケースが見つからなかった、実行を開始できなかった、または実行が API エラーで終了した。プラグインディレクトリが信頼されておらず `--trust-plugin` が渡されなかった場合、オプションが無効だった場合、または `--json` の結果を書き込めなかった場合にも返されます。
2	部分的な実行。`--max-cost-usd` 上限に達した、または認証情報が最初の実行の前または時点で拒否されました。それでも `results.json` は `partial: true` と理由とともに書き込まれます。
130	中断。部分的な結果が書き込まれます。
143	終了（CI タイムアウトなど）。

with-minus-without デルタは報告されますが、終了コードを変更することはなく、HTML レポートの書き込みまたは公開の問題も同様です。ケースがなぜ低くスコア化されたかを確認するには、ローカルで --json なしで実行して、実行ごとの進捗とグレーダー行が出力されるようにします。 CI ランナーには、以下も必要です。

インストールと認証情報：CI ランナーは Claude Code インストールと環境の認証情報（ANTHROPIC_API_KEY やクラウドプロバイダーの変数など）が必要です。
信頼：--trust-plugin なしで、チェックアウトディレクトリを Claude Code がまだ信頼していないジョブは、最初の実行信頼プロンプトが必要で、質問できない実行は終了 1 で拒否されます。
CI での init：claude plugin eval init は質問をするためにターミナルが必要です。CI では、claude plugin eval init --bare <name> を実行して空のテンプレートを取得します。

コストを予測可能に保つために、クイックな毎変更スイートにはジャッジを呼び出さないグレーダーのみを付与し、Δ が不要な場所で --ablation none を使用し、partial: true ドキュメントと skippedPaidGraders を持つ実行をチャートするトレンドから除外します。

結果を読む

少なくとも 1 つのケースを持つすべての実行は、eval ディレクトリ内に results/<timestamp>/ ディレクトリを書き込み、aggregate-result.json と report.html を含みます。パスターゲットの場合はプラグインの下。プラグインに名前を付けた場合は現在のディレクトリの下。ターゲットテーブルに示すように。サマリーテーブル、JSON、レポートはすべて同じ結果データをレンダリングします。

HTML レポート

report.html は単一の自己完結型ファイルで、外部リクエストを行わないため、CI ジョブに添付したり、ディスクから開いたりできます。この例は、--threshold 0.8 で実行された 3 ケーススイートのレポートの上部です。表示されるコストは定価見積もりで、モデルとケース数によって異なります。

eval レポートの上部。「Plugin effect: +33.3 pts vs baseline, improved 2, flat 1, regressed 0 of 3 cases」と読む判定行、スイートスコア、アブレーションデルタ、ベースラインスコア、閾値を通過するケース、完全な実行の 5 つのサマリータイル、その後、デルタ、スコアバー、2 つのグレーダーが両方とも合格を示す 1 つの実行を持つ最初のケース。

上から下に読みます。

判定行とタイル は、プラグインがスイート全体で役に立ったかどうかに答えます。スイートスコアはケースごとのプラグイン付きスコアの平均、アブレーション Δ はそれがベースラインスコアの上または下にどの程度座っているか、ケースは何が閾値を満たしたかをカウントします。完全な実行はすべてのグレーダーが合格した with-plugin 実行の共有です。
各ケースカード はケース独自の Δ とプラグイン付きスコアを表示し、バーの閾値にティックを付けます。Δ が負のケースは赤い左端を取得するため、スクロール時に回帰が目立ちます。
ケース内 では、プラグイン付き実行が最初に来て、ベースライン実行が後に来ます。各実行はグレーダーを合格または不合格チップでリストします。失敗したグレーダーは説明付きで既に展開されており、llm グレーダーはジャッジの投票とジャッジに提示された証拠も表示します。ここで、実行のスコアが低かった理由を確認できます。スコアに算入されないグレーダー（tool_used: Skill など）には plugin-fired indicator バッジが付きます。
プロンプトとグレーダー は実行の下に表示され、ケースのプロンプトと各グレーダーのルーブリックまたはパターンを示すため、スイートを持たずにレポートを読む人でも、何が尋ねられ、何が良いとみなされたかを確認できます。

claude.ai サブスクリプションでサインインしており、アーティファクトがアカウントで利用可能な場合、Claude Code はレポートをプライベートアーティファクトとして公開し、Published: <url> を出力します。--no-publish を渡してローカルに保持します。Published: 行が表示されない場合（API キー認証など）、ローカルファイルがレポートです。 Claude Code セッションが開始した実行（Claude にスイートを実行するよう依頼するなど）もローカルに留まり、その Report: 行は kept local と言います。そのコマンドに --publish-report を追加して公開します。

JSON 結果

aggregate-result.json および --json 出力は、CI スクリプトが解析するための schemaVersion: 1 を持つバージョン付きドキュメントです。フィールド名は camelCase で、新しいフィールドは既存のフィールドを名前変更せずに追加されるため、認識しないフィールドを無視するようにスクリプトを作成します。これらはゲートスクリプトが通常読むフィールドです。ドキュメントはスイート設定、すべてのグレーダー定義、および説明と証拠を持つ実行ごとのグレーダー結果も含みます。

フィールド	意味
`partial`, `partialReason`	`cost_ceiling`、`interrupted`、`auth_failed` で `true` の場合、スイートが完了しませんでした。部分的な結果をトレンドチャートから除外します。
`aggregates.overallScore`	スイート全体のケーススコアの平均
`aggregates.casesPassed`, `aggregates.casesTotal`	`--threshold` 以上のケース、および合計
`aggregates.meanDelta`	ケース全体の平均 `Δ`（2 arm モード下）
`cases[].name`	ケース名
`cases[].aggregates.score`	ケースの平均 with-arm 実行スコア
`cases[].aggregates.delta`	with-arm スコアから without-arm スコアを引いたもの。ケースが 1 つの arm のみで実行された場合、または arm が比較可能でない場合は省略。
`cases[].arms.with[].error`	`null`、または実行が異常終了した理由（`timed out after 300s` など）。こうした実行の一部は生成したものに基づいて引き続き採点されるため、null 以外のエラーはスコア 0 を意味しません。API エラーで終了した実行は採点されずにスコア 0 になります。
`cases[].arms.with[].aborted`	モックが `expect:`、`abort_when`、または agent-mock の呼び出し予算によって実行を停止した場合に存在し、`server`、`tool`、`reason` を持ちます。実行はスコア 0 で、`error` は `null` のままです。
`cases[].arms.with[].skippedPaidGraders`	コスト上限がこの実行のジャッジグレーダーをスキップした場合は `true`。そのスコアは比較可能ではありません。
`costUsd`, `durationSeconds`, `claudeVersion`	定価でのジャッジ呼び出しを含む推定コスト、壁時間秒、スイートを実行した Claude Code バージョン

実行がアクセスできるもの

claude plugin eval はターゲットプラグインのスキル、フック、エージェントを読み込み、ユーザーのマシン上で、ユーザーとして eval スイートを実行します。プラグインを指定することは claude --plugin-dir と同じ信頼判断であるため、信頼できるプラグインのみを評価してください。このセクションで説明する分離は、テスト中のエージェントが到達できるものを制限します。これはプラグイン自体のコードに対する境界ではなく、スイートが合格したことは、プラグインが安全であるかどうかについて何も述べていません。

プラグインディレクトリを信頼する

初めて claude plugin eval をディレクトリに対して実行する場合、Claude Code は何かを読み込む前に Trust this plugin directory? と尋ねます。ただし、インタラクティブな claude セッションでそこで既に信頼プロンプトを受け入れている場合は除きます。Git リポジトリ内では、「はい」と答えるとリポジトリ全体が信頼され、インタラクティブセッションでも同様です。stdin または stdout がターミナルでない場合、または --json の下では、実行は尋ねることができず、終了コード 1 で拒否されます。--trust-plugin を渡して信頼を自分で主張してください。これは自分のマシンで実行するプラグインに対してのみ行ってください。パスとして与えるのではなく名前で指定したターゲット、つまりインストール済みプラグインまたはスキルディレクトリプラグインは、プロンプトをスキップします。プラグインとスイートの一部は、その実行のためにそのフラグを渡す場合にのみ実行されます。

ケースの scaffold_script は --scaffold で実行されます
読み取り専用セット以外のツールは --allow-tools で実行されます
プラグインの実際の MCP サーバーは --allow-real-servers または --mocks off で実行されます

ケースの allowed_tools とスキル自体の allowed-tools フロントマターは、これらのいずれも拡大することはできません。自分で作成していないフックがプラグインに含まれている場合、または実際の MCP サーバーを開始する場合は、コンテナや CI ランナーなどの分離された環境で実行しない限り、スコアを参考情報として扱ってください。フックとサーバーはエージェントのサンドボックスの外で実行され、グレーダーが読み取るファイルを変更する可能性があるためです。

実行がどのように分離されるか

各実行は、一時的なホームディレクトリ、作業ディレクトリ、Claude Code 設定を取得し、テスト中のエージェントはそこで claude -p 子プロセスとして実行され、プラグインのみが読み込まれます。ケースを作成する際は、これらの結果を念頭に置いてください。

個人またはプロジェクトレベルのものは読み込まれません。 ユーザー設定、フック、CLAUDE.md ファイル、MCP サーバー、その他のインストール済みプラグイン、メモリ、スキルは存在しません。プロジェクトスコープの設定もどこからも読み取られません。ワークスペースの上位からも内部からも、.claude/ ディレクトリ、CLAUDE.md、.mcp.json は読み込まれず、scaffold_script が書き込んだものであっても同様です。また、add_dirs のディレクトリは読み取りアクセスのみを付与します。シェル環境のほとんども保留されます。許可リストと EVAL_* 変数のみが実行に到達します。scaffold_script が提供できるのはファイルと Git の状態のみであるため、ケースが依存するスキル、エージェント、フック、MCP サーバーはテスト対象のプラグインに含めてください。
管理ポリシーは引き続き実行を制限できます。 管理者がマシンに展開した管理設定の制限は実行内に適用されるため、管理マシン上の結果は、そのポリシーによって管理されていないマシンと異なる場合があります。
Artifact ツールはオフです。 アーティファクトを公開するスキルは、そのステップの前に生成するものについてのみグレード可能です。
ケース定義はエージェントから隠されています。 実行は eval ディレクトリを読み取ることができないため、Claude はケースのプロンプト、グレーダー、または兄弟ケースを見ることができません。
シェルコマンド外のネットワークサンドボックスはありません。 付与するシェルコマンドはサンドボックスのネットワークルールの下で実行されます。WebFetch(domain:…) 付与はそのドメインに直接到達し、プラグイン自体のフックと開始する実際の MCP サーバーは任意のホストに到達できます。

Eval スイートリファレンス

eval スイートに含めることができるものはすべて、プラグインの eval ディレクトリの下に配置されます。このディレクトリは、別のディレクトリを設定していない限り evals/ です。prompt.md または case.yaml を含むディレクトリはケースとみなされます。グレーダーが 1 つもないケースは、graders を示す invalid case.yaml エラーで読み込みに失敗します。このツリーは、claude plugin eval が eval ディレクトリ内で読み書きするすべてのファイルを示しています。

evals/
├── <case>/                        # ケースごとに 1 つのディレクトリ。グループ化するために非ケースディレクトリの下にネストします
│   ├── prompt.md                  # frontmatter: case と run フィールド。本文: プロンプト
│   ├── case.yaml                  # オプション: context.* フィールド、または 1 つのファイル内の全ケース
│   ├── graders/
│   │   └── <name>.md              # ファイルごとに 1 つのグレーダー。frontmatter: type と options。本文: ルーブリック
│   ├── mocks/                     # オプション: このケースのみのモック。以下と同じレイアウト
│   └── <case.yaml で参照されるフィクスチャ、スクリプト、トランスクリプト>
├── mocks/                         # オプション: スイート全体の MCP モック
│   ├── <server>/
│   │   ├── <tool>.md              # 1 つのモック化されたツール。本文: ツール結果
│   │   ├── _server.md             # オプション: 複数のツールに答える 1 つのエージェント
│   │   ├── _tools.json            # オプション: 実際の説明とスキーマのために保存された tools/list レスポンス
│   │   └── fixtures/              # {{file:fixtures/...}} で挿入されるファイル
│   └── .replay/<server>/          # 採用されたエージェント-モック記録。モデル呼び出しなしで応答
└── results/<timestamp>/           # 各実行で書き込まれます。results/ を .gitignore に追加してください
    ├── aggregate-result.json
    ├── report.html
    └── mock-recordings/           # クリーン実行からのエージェント-モック応答。ADOPT.txt 付き

prompt.md フロントマター

prompt.md フロントマターは以下のフィールドを受け入れます。未知のキーはエラーです。

フィールド	デフォルト	目的
`schema_version`	`"1.1"`。自動設定	ケース形式バージョン。`prompt.md` として記述されたケースは自動的に取得されるため、ほとんど設定しません
`name`	ディレクトリ名	ケース名。`--case` グロブはこれにマッチし、レポートはこれをキーにします
`description`		人間向け。実行時には使用されません
`tags`	`[]`	`--tag` フィルタリング用のラベル。任意のタグがマッチすればケースが実行されます
`plugins`	最も近い囲むプラグイン	テスト対象のプラグインディレクトリ。ケースディレクトリからの相対パス。自動検出がプラグインを見つけられない場合は `plugins: ["../.."]` を設定してください。プラグインが読み込まれないを参照
`runs`	`3`	アーム当たりの実行数。1 から 50。`--runs` で上書きされます
`expected_outcome`		人間向け。実行時には使用されません
`model`	子セッションのデフォルト	テスト対象のエージェント用モデル。`--model` で上書きされます
`max_turns`	`10`	ターンキャップ。最大 200。これに達するとランエラーとして記録され、通常はスコアを低下させるため、寛容に設定してください
`timeout_seconds`	`300`	実行ごとの壁時間キャップ。最大 3600
`allowed_tools`	`[]`	ケースが必要とするツール。例えば `[Read, Glob, Grep, Skill]`。読み取り専用ツールはここにリストされると付与されます。その他については、ツールを付与を参照してください
`append_system_prompt`		子セッションのシステムプロンプトに追加されるテキスト
`env`	`{}`	子セッション用の追加環境変数。キーは `EVAL_[A-Z0-9_]` にマッチする必要があります。その他のキーは実行を失敗させます。実行は、シェルからの許可リストのみを継承します。`PATH` とロケール、プロキシと証明書設定、モデルプロバイダーを選択・認証する変数、ほとんどの `ANTHROPIC_` と `CLAUDE_CODE_` 設定、および `EVAL_` です。プラグインに他のもの（ツールチェーン設定など）を渡すには、`EVAL_*` 変数としてエクスポートしてください

case.yaml フィールド

case.yaml は YAML でケースを説明する別の方法または補足です。他のファイルを指すフィールドを追加します。schema_version: "1.1" と name が必須です。prompt.md フィールドの description、tags、plugins、runs、expected_outcome はトップレベルに配置されます。model、max_turns、timeout_seconds、allowed_tools、append_system_prompt、env は execution: の下に配置されます。両方のファイルが存在する場合、prompt.md フロントマターは一致する case.yaml フィールドを上書きし、prompt.md 本文がプロンプトになり、graders/*.md は case.yaml にリストされたグレーダーの後に追加されます。これらのフィールドは case.yaml にのみ存在します。

フィールド	目的
`context.scaffold_script`	ケースディレクトリ内の Bash スクリプト。Claude が開始する前に空のワークスペースで実行され、フィクスチャファイルまたは git リポジトリを作成します。`--scaffold` を渡したときのみ、最小限の環境と 120 秒の制限で実行されます。0 以外の終了コードで終了すると実行は失敗します
`context.history_file`	ケースディレクトリ内の `.jsonl` トランスクリプト。再開するために使用されます。ケースのプロンプトは次のユーザーターンになります
`context.add_dirs`	ケースディレクトリ内のディレクトリ。Claude が実行中に読み取ることができます。読み取り専用で付与されます
`execution.prompt`	プロンプト。ケース全体を `case.yaml` に保持し、`prompt.md` を省略する場合
`graders`	グレーダーのリスト。各グレーダーは `name` と `graders/*.md` ファイルがフロントマターで取得するのと同じキーを持ちます。`llm` グレーダーの場合、ルーブリックを `criteria` に配置します

グレーダーフロントマター

graders/ の下のすべてのグレーダーファイルは、フロントマターでこれらのキーと、そのタイプのオプションを取得します。グレーダーの名前は .md なしのファイル名です。

キー	デフォルト	目的
`type`	必須	グレーダータイプの 1 つ
`weight`	`1`	実行のスコアにおける相対的な重み。任意の正の数
`arm`	未設定	`with-only` は 2 アーム実行でグレーダーをスコアリングから除外します。`both` は Claude Code が除外する可能性があるグレーダーを両方のアームでスコアリングするよう強制します

グレーダーが見ることができるもの

regex グレーダーは target を取得し、llm グレーダーは focus を取得します。両方とも同じ値を受け入れます。

値	グレーダーが見るもの
`last_message`	Claude の最終応答テキスト。これがデフォルトです
`trace`	JSON としてのセッション。1 行に 1 つのメッセージ。`regex` グレーダーはすべてのメッセージを見ます。`llm` ジャッジは最初の 12 と最後の 12 を見ます。その中の引用符と改行は JSON エスケープされるため、regex は `"` ではなく `\"` にマッチします
`files`	実行中に Claude が作成したパスのリスト。1 行に 1 つ。その内容ではなく、スキャフォルドが作成したファイルや Claude が単に変更したファイルではありません
`{ source: file, path: <path> }`	実行後のワークスペース内の 1 つのファイルの内容。プラグインが生成したものをグレードするために使用します。PNG、JPEG、GIF、または WebP ファイルは `llm` ジャッジに画像として表示されます。`llm` ジャッジは `.pptx` または PDF などの他のバイナリファイルを拒否します。画像にレンダリングするか、テキストとして書き出してグレードしてください
`mock_calls`	Claude がモック化された MCP ツールに行った各呼び出し。その入力とモックの応答を含みます

グレーダータイプ

以下の各グレーダータイプは、そのオプションと合格時を列挙しています。

タイプ	オプション	合格時
`regex`	`pattern`、`flags`、`match`、`target`	JavaScript regex `pattern` がターゲットで見つかります。`match: not_contains` を設定して不在を要求するか、`match: "count:N"` を設定して正確に N 回のマッチを要求します。大文字小文字を区別しないようにするには `flags: i` に配置します。インライン `(?i)` はサポートされていません
`tool_used`	`tool`、`input_match`、`min`、`max`	JSON エンコードされた入力がオプションの `input_match` regex にマッチする `tool` への呼び出し数が `min`（デフォルト 1）と `max`（デフォルト無制限）の間です。ツールが呼び出されなかったことを主張するには、`min: 0` と `max: 0` の両方を設定します
`tool_order`	`before`、`after`	両方のツールが呼び出され、最初にマッチする `before` 呼び出しが最初にマッチする `after` 呼び出しより前です。各々はツール名または `{ tool, input_match }` です
`file_exists`	`path`、`exists`	Claude が作成したファイルが `path` グロブにマッチするか、`exists: false` で何もマッチしません。実行中に作成されたファイルのみがカウントされます
`llm`	`criteria`、`focus`	ジャッジモデルが少なくとも 3 回中 2 回のルーブリックで PASS に投票します。`.md` レイアウトではファイル本文が criteria です
`baseline`	`baseline_file`、`criteria`	ジャッジが実行が `baseline_file`（ケースディレクトリ内の `.jsonl`）の参照トランスクリプトと同じくらい criteria を満たしていることを検出します

モックファイル

mocks/<server>/ の下の <tool>.md ファイルは 1 つのツールに答えます。その本文はツール結果で、{{input.<field>}} と {{file:fixtures/<name>}} の置換があります。そのフロントマターは以下のキーを受け入れます。

キー	デフォルト	目的
`type`	`fixed`	`fixed` は本文をそのまま返します。`agent` は本文をジャッジモデルへの指示として扱います。このモデルは実行中にサーバーとして振る舞い、以前の呼び出しを履歴として見ます
`expect`	未設定	ドット記法の入力パスから `string`、`number`、`boolean`、`array`、`object` などのタイプ名、`/regex/`、リテラル、または許可されたリテラルのリストへのマップ。それに違反する呼び出しはスコア 0 で実行を中止し、サーバー、ツール、理由を含む `aborted` として報告されます
`error`	`false`	`fixed` のみ。本文をツールエラーとして返します
`abort_when`	未設定	`agent` のみ。エージェントが実行を中止できる唯一の条件をリストする散文

2 つのオプションファイルがサーバーのディレクトリ内のツールファイルの横に配置されます。

_server.md: 複数のツールに答える単一の type: agent モック。その tools: フロントマターキーにリストされています。同じツール用の <tool>.md が優先されます。ここに expect: ガードを置くと、tools: に単一のツールしかリストされていない場合を除いて読み込みエラーになるため、ガードは個別の <tool>.md に配置してください
_tools.json: 実際のサーバーから保存された tools/list レスポンス。モック化されたツールが許可的なプレースホルダーの代わりに実際の説明と入力スキーマを持つようにします

ケース独自の mocks/ ディレクトリは同じレイアウトを使用し、スイートのモックをファイルごとに上書きします。

expect での正規表現パターン

expect: 内の /regex/ 値は、Claude Code がスイートの読み込み時にチェックする小さな方言を使用します。

リテラル文字、.、\d などのエスケープ、[a-z] などの文字クラス
量指定子 *、+、?、および {m,n} 形式。それぞれ単一の文字、エスケープ、またはクラスに適用します
先頭のオプションの ^ と末尾の $
フラグは i と s のみ

グループ、選択、後方参照、先読み・後読み、その他のフラグを含むパターンなど、この方言の範囲外のパターンがあると、ケースは読み込まれません。ケースのスコアは 0 になり、そのエラーにはパターンが示されます。複数の正確な値を許可するには、選択の代わりにリテラルのリストを記述してください。各パターンは最大長までの値のみをチェックし、それより長い値は違反とみなされます。量指定子はその長さを短くし、先頭の ^ は長くするため、パターンは ^ でアンカーし、量指定子は少なくしてください。

トラブルシューティング

これらは著者が最も頻繁に遭遇する問題であり、表示される内容に基づいてキーが付けられています。

「plugin eval is currently in early access」

ビルドはコマンドの一般提供より前のものです。claude update を実行してから、新しいセッションでコマンドを再度実行してください。

「plugin eval is currently unavailable」

Anthropic がサーバー側でコマンドをオフにしています。マシン上の何もそれをオンに戻すことはできません。claude update を実行して、後で新しいセッションで再度試してください。

「is not a trusted plugin directory, and this run cannot stop to ask you about it」

これは Claude Code がまだ信頼していないディレクトリに対する最初の実行であり、stdin または stdout がターミナルでないか、--json を渡したため、質問することができません。ターミナルで claude plugin eval <dir> を一度実行してプロンプトに答えるか、プラグインのコードとスイートを信頼する場合は --trust-plugin を渡してください。実行がアクセスできるものを参照してください。

「is too old for claude plugin eval」

PATH 上の git が 2.31 より古いため、claude plugin eval はケースを実行する前に停止し、バージョンを名前付けするメッセージで 1 で終了しました。

git 2.30 is too old for claude plugin eval: it ignores the environment configuration (GIT_CONFIG_COUNT, added in git 2.31) that switches off the repository's git hooks and helper programs for the run. Install git 2.31 or newer.

各実行について、Claude Code は git フック、認証情報ヘルパー、およびリポジトリの git 設定が開始できるその他のプログラムをオフにします。これは git がバージョン 2.31 からのみ読み取る環境設定を通じて行われます。古い git はその設定を無視するため、スイートはそれらのプログラムが実行される可能性のある実行をスコアリングするのではなく停止します。git 2.31 以降をインストールしてスイートを再度実行してください。 v2.1.283 より前では、claude plugin eval は git バージョンをチェックしなかったため、古い git ではスイートはそれらのプログラムがオンのままで実行されました。

“cannot be evaluated where sessions load it”

シェルで、ローカルパスから追加したマーケットプレイスからインストールしたプラグインの名前を指定して claude plugin eval を実行しました。現在、そのマーケットプレイスからプラグインを読み込めるセッションがないため、コマンドはこのメッセージを表示して実行を拒否し、コード 1 で終了します。

Error: formatter@my-marketplace cannot be evaluated where sessions load it: no session could load it now. Its marketplace is a folder whose catalog could not be read, or lists it no more. Check the marketplace with `claude plugin marketplace list`, or pass ./<dir> to evaluate a directory.

no session could load it now. の後の文が、何が失敗したかを示しています。シェルで claude plugin marketplace list を実行し、メッセージが示す問題を修正してください。たとえば、マーケットプレイスのディレクトリを復元するか、プラグインのエントリをカタログに戻します。マーケットプレイスを介さずにプラグインのソースを評価するには、claude plugin eval ./plugins/formatter のように、そのディレクトリをターゲットとして渡してください。

「No eval cases found」

有効な eval ディレクトリの下に <case>/prompt.md または <case>/case.yaml が存在しないか、--case および --tag フィルターがケースと一致しません。プラグインルートから実行するか、claude plugin eval init を実行してスイートを作成してください。

ベースラインアームにプラグインが表示されない、またはデルタがゼロ

サマリーに W/OUT 列がない場合、またはケースが「ablation requested but no plugin resolved」で失敗する場合、通常の原因はケースのプラグインが見つからなかったことです。すべてのケースが context.history_file を通じてトランスクリプトを再開する場合は、列がないことは想定どおりです。これらのケースはデフォルトで 1 つのアームで実行されるためです。それ以外の場合は、plugins: ["../.."] をケースに追加し、ケースディレクトリからプラグインディレクトリへのパスを指定してください。プラグインが読み込まれたにもかかわらず Δ がゼロに近く、tool_used: Skill グレーダーが失敗している場合、これは通常、スキルの description がプロンプトの表現でトリガーされていないことを意味する実際の発見です。説明を調整して、同じスイートを再度実行してください。

プラグインのエージェントの 1 つに対して「Agent type ’…’ not found」

デフォルトでは、各ケースはプラグインありとプラグインなしの両方で実行され、プラグインなしの実行はプラグインなしベースラインです。Claude がベースライン実行でプラグインのエージェントの 1 つをディスパッチする場合、Agent ツール呼び出しは Agent type '<plugin>:<agent-name>' not found. Available agents: ... で失敗します。リストは、組み込みサブエージェントなど、プラグインなしで存在するエージェントのみを名前付けします。エラーは予期されています。Δ はプラグインの実行をベースラインと比較するためです。JSON 結果では、ベースライン実行は cases[].arms.without の下にあります。プラグインが読み込まれた実行では、allowed_tools に Agent をリストするケースは、名前空間付きの名前でプラグインのエージェントの 1 つをディスパッチできます。たとえば、my-plugin という名前のプラグイン内の code-reviewer エージェントであれば my-plugin:code-reviewer です。ベースライン実行をスキップするには、--ablation none を渡してください。

正しいファイルが生成されたにもかかわらず、すべてがゼロスコアになる

グレーダーが files（作成されたパスのリスト）をターゲットにしているが、ファイルの内容を意図していました。{ source: file, path: <path> } を target または focus として使用してください。別途、file_exists は実行中に作成されたファイルのみをカウントするため、スキャフォルドが作成したファイルまたは Claude が編集のみしたファイルは見えません。その内容をグレードするか、Edit で tool_used を使用してください。

トレース上の正規表現が表示されるテキストと一致しない

ターゲットが間違っている: デフォルトの target はトレースではなく last_message です。
JSON エスケープ: target を trace にする場合、行ごとに JSON であるため、引用符は \" として表示されます。
正規表現構文: 正規表現は JavaScript 構文を使用するため、(?i) を記述するのではなく、flags に i を入れてください。

ツールが拒否される、MCP ツールが見つからない、または Bash が実行されない

読み取り専用セット以外のすべてのものには、--allow-tools Bash Write などの許可が必要です。個人用 MCP サーバーは実行中に読み込まれません。プラグイン自体のサーバーは、オプトインしない限り開始されず、それらのツールは --allow-tools "mcp__plugin_<plugin>_<server>__*" 許可も必要です。モック化されたツールはどちらも必要ありません。

実行が 1 で終了するが、結果は問題ないように見える

すべてのケースが --threshold 以上のスコアを取得したにもかかわらずコマンドが 1 で終了する場合、--json 指定時でも、stderr の行に原因が示されます。たとえば、ケースファイルの読み込みに失敗した場合や、実行が API エラーで終了した場合です。その他の原因については、終了コードを参照してください。デフォルトの --threshold は 1.0 であるため、ケースが完璧未満のスコアを取得するとコマンドは 1 で終了します。必要なスコアに一致するしきい値を設定してください。

`--json output path must end in .json`

--json の後にターゲットを配置したため、出力パスとして読み取られました。claude plugin eval . --json のようにターゲットを最初に配置するか、--json に明示的な .json パスを指定してください。

グレーダーが 1.0 のスコアを取得した実行の下で passed: false を表示する

そのグレーダーは設計上、2 アーム実行でスコアから除外され、その scored フィールドは false です。プラグインなしベースラインと比較を参照してください。

“ended on an API error and scored 0 without grading”

この stderr 警告は、少なくとも 1 つの実行の最後のリクエストに対して、API がレート制限やプランの使用制限などの HTTP エラーで応答したことを意味します。このような実行はグレーダーの結果なしでスコア 0 となり、スコアや --threshold に関係なく、コマンドは 0 以外のコードで終了します。修正するには、影響を受けた各実行のエラーを見つけ、それが報告する原因を解決してから、スイートを再度実行してください。

--json なしの場合: エラーは実行の進行状況の行の末尾、error: の後にあります
--json 指定時: エラーは JSON 結果の cases[].arms.with[].error または cases[].arms.without[].error にあります

このカウントにはベースライン実行も含まれます。ベースライン実行のスコアはケースの合否を決定しないため、すべてのケースが合格してもコマンドが失敗することがあります。2 アーム実行では、影響を受けたケースの W/OUT と Δ は — と表示されます。使用制限またはレート制限については、実行がスイートの途中で使用制限またはレート制限エラーで失敗するを参照してください。 v2.1.299 より前では、このような実行は生成されたものに基づいてグレード化されていました。

実行がスイートの途中で使用制限またはレート制限エラーで失敗する

使用制限またはレート制限エラーで終了した実行はグレード化されずにスコア 0 となり、コマンドは 0 以外のコードで終了します。スイートはそれでも完了し、partial としてマークされません。制限がリセットされた後に再度実行してください。制限内に留まる必要がある場合は、--runs 1 または --case フィルターを使用してください。

“mock call budget exceeded”

1 回の実行内のすべての type: agent モックは、ケースの max_turns の 4 倍という 1 つの呼び出し予算を共有します。デフォルトの 10 では 40 回の呼び出しです。.replay/ の記録から応答された呼び出しもカウントされ、ケースの mock budget 進行状況の行に予算が表示されます。予算を超えた呼び出しは、スコア 0 とこの理由で実行を中止させるため、エージェントモックを多数呼び出すスキルについては、ケースの max_turns を上げてください。

実行がタイムアウトするか、ターンキャップに達する

デフォルトは 10 ターンと 300 秒です。より多くを必要とするタスクの場合、ケースで max_turns と timeout_seconds を上げ、厳密な実行ごとの制限ではなく、--max-cost-usd をコスト上限として使用してください。

​要件

​eval 実行の仕組み

​実行中に何が起こるか

​ケースのスコア化方法

​プラグインなしベースライン

​最初の eval スイートを作成する

​ケースを作成して改善する

​ケースを手動で作成する

​prompt.md で実行制限とツールを設定する

​グレーダーを選択して重み付けする

​安定した信号を与えるグレーダーを選択する

​プラグインなしベースラインに対してスコア化する

​別の eval ディレクトリを使用する

​フィクスチャとモックをセットアップする

​ワークスペースまたは会話をシードする

​MCP サーバーをモックする

​エージェントモック回答を再生する

​evals を実行する

​評価対象を選択する

​ツールを付与する

​コマンドオプション

​CI で evals を実行する

​結果を読む

​HTML レポート

​JSON 結果

​実行がアクセスできるもの

​プラグインディレクトリを信頼する

​実行がどのように分離されるか

​Eval スイートリファレンス

​prompt.md フロントマター

​case.yaml フィールド

​グレーダーフロントマター

​グレーダーが見ることができるもの

​グレーダータイプ

​モックファイル

​expect での正規表現パターン

​トラブルシューティング

​「plugin eval is currently in early access」

​「plugin eval is currently unavailable」

​「is not a trusted plugin directory, and this run cannot stop to ask you about it」

​「is too old for claude plugin eval」

​“cannot be evaluated where sessions load it”

​「No eval cases found」

​ベースラインアームにプラグインが表示されない、またはデルタがゼロ

​プラグインのエージェントの 1 つに対して「Agent type ’…’ not found」

​正しいファイルが生成されたにもかかわらず、すべてがゼロスコアになる

​トレース上の正規表現が表示されるテキストと一致しない

​ツールが拒否される、MCP ツールが見つからない、または Bash が実行されない

​実行が 1 で終了するが、結果は問題ないように見える

​--json output path must end in .json

​グレーダーが 1.0 のスコアを取得した実行の下で passed: false を表示する

​“ended on an API error and scored 0 without grading”

​実行がスイートの途中で使用制限またはレート制限エラーで失敗する

​“mock call budget exceeded”

​実行がタイムアウトするか、ターンキャップに達する

​関連項目も参照

要件

eval 実行の仕組み

実行中に何が起こるか

ケースのスコア化方法

プラグインなしベースライン

最初の eval スイートを作成する

ケースを作成して改善する

ケースを手動で作成する

prompt.md で実行制限とツールを設定する

グレーダーを選択して重み付けする

安定した信号を与えるグレーダーを選択する

プラグインなしベースラインに対してスコア化する

別の eval ディレクトリを使用する

フィクスチャとモックをセットアップする

ワークスペースまたは会話をシードする

MCP サーバーをモックする

エージェントモック回答を再生する

evals を実行する

評価対象を選択する

ツールを付与する

コマンドオプション

CI で evals を実行する

結果を読む

HTML レポート

JSON 結果

実行がアクセスできるもの

プラグインディレクトリを信頼する

実行がどのように分離されるか

Eval スイートリファレンス

prompt.md フロントマター

case.yaml フィールド

グレーダーフロントマター

グレーダーが見ることができるもの

グレーダータイプ

モックファイル

expect での正規表現パターン

トラブルシューティング

「plugin eval is currently in early access」

「plugin eval is currently unavailable」

「is not a trusted plugin directory, and this run cannot stop to ask you about it」

「is too old for claude plugin eval」

“cannot be evaluated where sessions load it”

「No eval cases found」

ベースラインアームにプラグインが表示されない、またはデルタがゼロ

プラグインのエージェントの 1 つに対して「Agent type ’…’ not found」

正しいファイルが生成されたにもかかわらず、すべてがゼロスコアになる

トレース上の正規表現が表示されるテキストと一致しない

ツールが拒否される、MCP ツールが見つからない、または Bash が実行されない

実行が 1 で終了するが、結果は問題ないように見える

`--json output path must end in .json`

グレーダーが 1.0 のスコアを取得した実行の下で passed: false を表示する

“ended on an API error and scored 0 without grading”

実行がスイートの途中で使用制限またはレート制限エラーで失敗する

“mock call budget exceeded”

実行がタイムアウトするか、ターンキャップに達する

関連項目も参照