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

Claude Code プラグイン用の eval ケースを作成し、claude plugin eval で実行し、結果をグレード化し、プラグインなしのベースラインと比較し、CI でスコアをゲートする。

claude plugin eval は プラグイン をテストケースのスイートに対して実行し、結果をスコア化します。各ケースは現実的なプロンプトと 1 つ以上のグレーダーで構成されます。グレーダーは Claude が生成したものに対する合格/不合格チェックで、返信に対する正規表現、特定のツールが呼び出されたかどうか、または第 2 のモデルが返信を判定するルーブリックなどです。

スイートを手動で作成する必要はありません。claude plugin eval init はプラグインについて質問し、ケースとグレーダーを提案し、それらを試し、ファイルを作成します。既に開いているセッションから Claude に同じことを行うよう依頼することもできます。

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

このページはプラグインとスキル作成者向けで、動作するプラグインがあり、その動作をテストしたい場合、および CI でプラグイン変更をゲートするチーム向けです。そのケース形式は skill-creator プラグイン が使用する evals/evals.json ファイルとは別です。プラグインを作成するには プラグインを作成する を参照してください。プラグインの動作ではなく構文とスキーマエラーをチェックするには、claude plugin validate を使用します。

要件

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

• Claude Code v2.1.269 以降。claude --version で確認し、claude update でアップグレードしてください。
• plugin.json または .claude-plugin/plugin.json マニフェストを含むプラグインディレクトリ、または skills-directory プラグイン。
• 通常の Claude Code セッションで使用するのと同じ認証とモデルプロバイダー。Eval 実行、judge-scored graders、および claude plugin eval init はあなたの認証情報でモデルを呼び出すため、プランの使用量制限または API 請求に対してカウントされます。コマンドがコストを報告する場合、その数値はそれらの呼び出しの 定価見積もり です。

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 と呼ばれます。プラグインなしベースラインと比較する では、グレーダーがそれらの間でどのようにスコア化されるか、およびベースラインをオフにする方法について説明します。

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

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

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

claude plugin eval init

claude plugin eval .

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

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

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

claude plugin eval init が作成するケースは、開いて変更し、追加できるプレーンファイルです。ケースはプラグインの eval ディレクトリの下のディレクトリで、prompt.md、case.yaml、またはその両方を含みます。ケースをグループ化するには、それ自体がケースではないディレクトリの下にネストします。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 が受け取るメッセージを作成し、frontmatter で実行の制限とケースが使用できるツールを設定します。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.

各実行は空の作業ディレクトリで開始されるため、タスクに必要なものをプロンプト自体に入れるか、ワークスペースまたは履歴をセットアップする 最初に。frontmatter フィールドの完全なリスト は、モデル、タイムアウト、タグ、および環境変数をカバーしています。

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 をスキルの SKILL.md の name に置き換えます。

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

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

グレーダーの frontmatter はその type を設定し、オプションで実行のスコアでより多くをカウントする weight と、ベースラインに対してどのようにスコア化されるかを制御する arm を設定します。6 つのタイプのうち、regex、tool_used、tool_order、file_exists はトランスクリプトとファイルから計算され、コストはかかりませんが、llm と baseline はジャッジモデルを呼び出し、実行のコストに追加されます。

カスタムコードグレーダーはありません。グレーダータイプ は各タイプのオプションと合格条件をリストし、グレーダーが見ることができるもの は target と focus が受け入れる値をリストします。

llm および baseline グレーダーのジャッジはデフォルトで小さく高速なモデルです。ニュアンスのあるルーブリックに対してより強力なものを使用するには、--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 スコアを引いたもの）を表示します。比較が不要な場合（グレーダーを反復するなど）、--ablation none を渡してコストを半減させ、with-arm のみを実行します。

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

• tool が Skill である各 tool_used グレーダー
• arm: with-only でマークするグレーダー

ケース内のすべてのグレーダーがこれらの 1 つである場合、スコア化するものが何も残らないため、代わりに通常スコア化されます。「スキルを呼び出してはいけない」チェックに min: 0 と max: 0 を使用する場合は、グレーダーに arm: both を設定して、それに関わらず両方の arm でスコア化します。--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]

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: ブロックは入力を保護します。呼び出しがそれに違反する場合、実行はスコア 0 で中止され、理由が記録されます。そのため、ケースはプラグインがサーバーに何を求めたかを主張できます。error: true を設定して本文をツールエラーとして返すか、type: agent を設定して小さいモデルが本文の指示からサーバーとして答えるようにします。モックファイルリファレンス はすべてのキーと _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 . を実行します。これはスイート内のすべてのケースをロードされたプラグインで実行します。単一のケースファイルを実行するか、開発中のプラグインではなくインストール済みのプラグインを評価するには、別のターゲットを渡します。

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

ツールを付与する

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

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

ケースが付与しなかったツールを要求した場合、実行は stderr に 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 も含まれます。

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

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

HTML レポートの書き込みまたは公開の問題は終了コードを変更しません。ケースがなぜ低くスコア化されたかを確認するには、ローカルで --json なしで実行して、実行ごとの進捗とグレーダー行が出力されるようにします。

CI ランナーは Claude Code インストールと 環境の認証情報（ANTHROPIC_API_KEY など）が必要です。--trust-plugin なしで、チェックアウトディレクトリを Claude Code がまだ信頼していないジョブは、ターミナルがない場合は終了 1 で拒否されるか、ランナーが 1 つを割り当てるときはプロンプトで待機します。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 ケーススイートのレポートの上部です。表示されるコストは定価見積もりで、モデルとケース数によって異なります。

上から下に読みます。

• 判定行とタイル は、プラグインがスイート全体で役に立ったかどうかに答えます。スイートスコアはケースごとのプラグイン付きスコアの平均、アブレーション Δ はそれがベースラインスコアの上または下にどの程度座っているか、ケースは何が閾値を満たしたかをカウントします。完全な実行はすべてのグレーダーが合格した 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 で、新しいフィールドは既存のフィールドを名前変更せずに追加されるため、認識しないフィールドを無視するようにスクリプトを作成します。

これらはゲートスクリプトが通常読むフィールドです。ドキュメントはスイート設定、すべてのグレーダー定義、および説明と証拠を持つ実行ごとのグレーダー結果も含みます。

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

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

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

プラグインに対して claude plugin eval を初めて実行するとき、Claude Code は Trust this plugin directory? と尋ねます。ただし、既に対話型 claude セッションでそこで信頼プロンプトを受け入れた場合を除きます。git リポジトリ内で、はいと答えるとリポジトリ全体を信頼し、対話型セッションも同様です。stdin または stdout がターミナルでない場合、または --json の下では、実行は尋ねることができず、終了 1 で拒否されます。--trust-plugin を渡して信頼を自分で主張します。これは自分のマシンで実行するプラグインの場合のみです。パスではなく名前を付けるターゲット（インストール済みプラグインまたは skills-directory プラグイン）はプロンプトをスキップします。

プラグインとスイートの一部は、その実行のフラグを渡すときのみ実行されます。ケースの scaffold_script は --scaffold で、読み取り専用セット以上のツール は --allow-tools で、プラグインの 実際の MCP サーバー は --allow-real-servers または --mocks off で。ケースの allowed_tools とスキル独自の allowed-tools frontmatter はそれらのいずれかも広げることはできません。プラグインが作成しなかったフックを出荷する場合、またはその実際の MCP サーバーを開始する場合、グレーダーが読むファイルに触れる可能性があるため、コンテナまたは CI ランナーなどの分離環境で実行しない限り、そのスコアを参考情報として扱います。フックとサーバーはエージェントのサンドボックスの外で実行されます。

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

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

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

Eval スイートリファレンス

eval スイートが含むすべてのコンテンツは、プラグインの eval ディレクトリ evals/ の下に存在します。ただし、別のディレクトリを設定している場合を除きます。このツリーは、claude plugin eval がそこで読み書きするすべてのファイルを示しています。ケースが存在するには、prompt.md または case.yaml のいずれかが必須です。

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 frontmatter

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

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 frontmatter は一致する case.yaml フィールドをオーバーライドし、prompt.md 本文がプロンプトになり、graders/*.md は case.yaml にリストされたグレーダーの後に追加されます。

これらのフィールドは case.yaml にのみ存在します。

グレーダー frontmatter

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

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

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

グレーダータイプ

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

モックファイル

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

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

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

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

トラブルシューティング

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

「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 を渡してください。実行がアクセスできるものを参照してください。

「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」で失敗する場合、ケースのプラグインが見つかりませんでした。plugins: ["../.."] をケースに追加し、ケースディレクトリからプラグインディレクトリへのパスを指定してください。

プラグインが読み込まれ、Δ が tool_used: Skill グレーダーが失敗している場合でもゼロに近い場合、これは通常、スキルの description がプロンプトの表現でトリガーされていないことを意味する実際の発見です。説明を調整して、同じスイートを再度実行してください。

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

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

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

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

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

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

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

デフォルトの --threshold は 1.0 であるため、ケースが完璧以下のスコアを取得するとコマンドは 1 で終了します。バーに一致するしきい値を設定してください。終了 1 は、読み込みに失敗したケースファイルもカバーしており、テーブルの上の stderr で報告されます。

「--json output path must end in .json」

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

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

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

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

アカウントがプランの使用量制限に達するか、スイート実行中に API レート制限に達した場合、その後の各実行はそのエラーで終了し、生成されたものに基づいてグレード化され、通常はスコア 0 になります。スイートはまだ完了し、partial としてマークされないため、結果は回帰のように見える可能性があります。スコアを信頼する前に NOTES 列または JSON の cases[].arms.with[].error で制限メッセージを確認してから、制限がリセットされた後に再度実行してください。--runs 1 または --case フィルターを使用して、制限内に留まる必要がある場合は使用してください。

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

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

関連項目も参照

• プラグインを作成する: テストしているプラグインを構築し、開発中に --plugin-dir でロードします。
• プラグインリファレンス: plugin eval および plugin eval init コマンドエントリとマニフェストの experimental.evals キー
• スキル: スキルの説明が Claude がそれを呼び出すときを決定する方法。これはスキルがトリガーされるかどうかをチェックするケースが測定しているものです。
• サンドボックス: 実行に Bash を付与するときに適用される OS レベルサンドボックス
• プラグインマーケットプレイスを作成して配布する: スイートが合格したら、プラグインを公開します。