claude plugin eval は プラグイン をテストケースのスイートに対して実行し、結果をスコア化します。各ケースは現実的なプロンプトと 1 つ以上のグレーダーで構成されます。グレーダーは Claude が生成したものに対する合格/不合格チェックで、返信に対する正規表現、特定のツールが呼び出されたかどうか、または第 2 のモデルが返信を判定するルーブリックなどです。
スイートを手動で作成する必要はありません。claude plugin eval init はプラグインについて質問し、ケースとグレーダーを提案し、それらを試し、ファイルを作成します。既に開いているセッションから Claude に同じことを行うよう依頼することもできます。
evals を使用して、プラグインがどの程度確実に Claude を正しい結果に導くかを測定し、プラグインを変更したり新しいモデルがリリースされたりしたときの回帰を検出し、プラグインなしの場合と比較してプラグインが何を貢献しているかを確認します。
このページはプラグインとスキル作成者向けで、動作するプラグインがあり、その動作をテストしたい場合、および CI でプラグイン変更をゲートするチーム向けです。そのケース形式は skill-creator プラグイン が使用する evals/evals.json ファイルとは別です。プラグインを作成するには プラグインを作成する を参照してください。プラグインの動作ではなく構文とスキーマエラーをチェックするには、claude plugin validate を使用します。
すべての eval 実行とすべてのジャッジグレーダーは、アカウント上の実際のモデル呼び出しで、プランの使用量または API 請求に対してカウントされます。そのため、最初に 要件 を確認してください。その後、最初の eval スイートを作成 するか、既にスイートがある場合は CI で evals を実行 に進んでください。
要件
プラグイン 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 つのスキルと、ユーザーが入力すべきリクエスト（それがスキルをトリガーすべき）
1
ケースを作成する
プラグインルートから、以下を実行します。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 はコマンドを実行し、その会話で同じ質問をします。ケースを自分で作成して、ファイルが正確に何を含むかを確認したい場合は、ケースを手動で作成する に従い、ここに戻ってそれを実行します。2
スイートを実行する
プラグインルートのシェルに戻り、ステップ 1 でこのディレクトリを既に信頼しているため、実行はすぐに開始されます。代わりにケースを手動で作成した場合、実行は最初に
evals/ の下のすべてのケースを実行します。Trust this plugin directory? [y/N] と尋ねます。y で答えてください。実行がアクセスできるもの は、同意していることを説明します。各ケースはプラグイン付きで 3 回、プラグインなしで 3 回実行されるため、1 つのケースは 6 回の実行です。各実行が完了すると、その実行のスコアと各グレーダーの判定を含む進捗行が出力されます。3
サマリーを読む
スイートが完了すると、サマリーテーブルが表示され、その後にレポートの場所が表示されます。
WITH はプラグインをロードしたケースのスコア、W/OUT はロードしないでのスコア、正の Δ はプラグインがスコアを上げたことを意味します。COST はモデル呼び出しの定価見積もりで、NOTES は最も高い重みの失敗したグレーダーの説明、または with-arm の実行エラーを示します。4
レポートを開いて反復する
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% の列を表示します。<case-name> を evals/ の下のディレクトリ名の 1 つに置き換えます。ケースを作成して改善する
claude plugin eval init が作成するケースは、開いて変更し、追加できるプレーンファイルです。ケースはプラグインの eval ディレクトリの下のディレクトリで、prompt.md、case.yaml、またはその両方を含みます。ケースをグループ化するには、それ自体がケースではないディレクトリの下にネストします。graders/ やフィクスチャファイルなど、ケースディレクトリ内のすべてはそのケースに属します。
これは claude plugin eval init が作成するレイアウトで、新しいスイートに使用するレイアウトです。eval スイートリファレンス には、モックと結果を含む完全なツリーがあります。
ケースを手動で作成する
Claude にケースをclaude plugin eval init で作成させることが推奨パスです。代わりに自分で作成するには、空のテンプレートから開始します。次のコマンドは、プレースホルダー prompt.md と 1 つのプレースホルダーグレーダーを含む first-case という名前のケースを作成し、何も実行しません。
prompt.md では、各実行で Claude が受け取るメッセージを作成し、frontmatter で実行の制限とケースが使用できるツールを設定します。evals/first-case/prompt.md を開き、プレースホルダー本文をスキルの 1 つが処理すべきリクエストに置き換えます。ユーザーが入力するであろう方法で表現されます。この例はコミットメッセージを作成するスキル用です。独自のリクエストを使用してください。
graders/ の下の各ファイルは、実行後に適用される 1 つのチェックです。evals/first-case/graders/criteria.md を開き、プレースホルダーをジャッジモデル用のルーブリックに置き換えます。具体的な PASS および FAIL 条件として作成されます。
evals/first-case/graders/skill-fired.md を作成し、your-skill-name をスキルの SKILL.md の name に置き換えます。
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でマークするグレーダー
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/ ディレクトリからフィクスチャを読むことができるようにします。
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 として保存します。
{{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、TaskOutput から）と、--allow-tools で付与するもの（スイート内のすべてのケースに適用）です。ケースが Bash、Write、Edit、WebFetch、WebSearch を使用できるようにするには、自分で付与します。
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 を渡し、スコアが時間とともに比較可能になるように両方のモデルを固定し、レポートをローカルに保持し、コスト上限を上限として設定します。
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バッジを持ちます。 - プロンプトとグレーダー はケースの下に表示され、各グレーダーのルーブリックまたはパターンを表示するため、スイートなしでレポートを読む人は何が尋ねられたか、何が良いとしてカウントされたかを見ることができます。
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 のいずれかが必須です。
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 レベルサンドボックス
- プラグインマーケットプレイスを作成して配布する: スイートが合格したら、プラグインを公開します。