claude plugin evalのレポートを公開する — --publish-reportと--keep-temp

claude plugin eval のレポートは、ターミナルから実行するとprivate artifactとして公開されることがあります。Claude Codeのセッションに実行を任せると、同じコマンドでも公開されません。この差を埋めるのが --publish-report で、各runの作業ディレクトリを残して中身を調べるのが --keep-temp です。

セッションから起動した評価は、なぜ kept local になるのか

claude plugin eval の結果は report.html として評価ディレクトリの results/<timestamp>/ に書き出されます。サブスクリプションでログインしていて、アカウントでArtifactsが使えるなら、Claude Codeは同じレポートをprivate artifactとして公開し、Published: <url> を表示します。

Published: 行が出るようになったのはv2.1.269からです。ただし、Claude Codeのセッションが起動した実行は、既定でこの公開をしません。「評価スイートを回して」とClaudeに頼んだ場合がこれに当たり、Report: 行に kept local と出ます。

2つのフラグは向きが逆で、--no-publish は「公開しない」、--publish-report は「ローカル既定の実行でも公開する」です。CIの例で --no-publish を付けるのは前者の使い方で、CIの合否に使う手順に出てきます。

--publish-report で公開する

Claudeに評価を任せるときの指示に、フラグまで含めて書きます。

claude plugin eval . --case "first-*" --runs 1 \
  --publish-report

セッションの中でClaudeに実行させる場合も、コマンドにこのフラグが付いていれば公開されます。毎回口頭で頼むのが面倒なら、プロジェクトの CLAUDE.md に次のような一文を置く手もあります。

plugin eval をセッション内で実行するときは、
結果を共有するため --publish-report を付ける。
CI 用のコマンドには付けない。

これは一例です。Claudeが毎回従うかどうかは、実行結果の Published: 行で確かめられます。

公開されない条件を先に確認する

--publish-report は「ローカル既定でも公開する」という指定です。Artifactsが使えない環境では、公開そのものが成立しません。

APIキー認証の環境では、そもそも Published: 行が出ません。その場合は Report: に書かれたローカルのパスにある report.html がレポート本体です。また、レポートの書き出しや公開に失敗しても、コマンドの終了コードは変わりません。公開の失敗でCIが赤くなることはありません。

--keep-temp で各runの作業場所を残す

各runは、一時的なホームディレクトリ、作業ディレクトリ、Claude Codeの設定を持つ隔離環境で動きます。--keep-temp を付けると、全runのサンドボックスを残し、そのパスを出力します。

使いどころは、graderが落ちた理由をレポートの説明だけでは判断できないときです(graderの設計はclaude plugin evalの使い方にあります)。file を見るgraderなら、Claudeが実際にどんなファイルを作ったかを手元で開けます。

claude plugin eval . --case "report-*" --runs 1 \
  --ablation none --keep-temp

この例は、調べたい1caseを最小の費用で回す形です。各オプションの意味は次のとおりです。

• --case: 名前のglobで1caseに絞る
• --runs 1: 1caseあたりのrun数を1にする(既定は3)
• --ablation none: no-pluginベースラインを回さず、1つのarmだけにする
• --keep-temp: 回したrunのサンドボックスを残す

評価は1回ごとにモデル呼び出しの費用がかかります。デバッグで3回ずつ2つのarmを回すより、1caseを1runに絞るほうが、残るサンドボックスの数も費用も小さくなります。

残したサンドボックスで確かめること

サンドボックスを開く前に、評価がどう隔離されているかを知っておくと読み違えません。

• 個人・プロジェクトの設定は載らない。ユーザー設定、CLAUDE.md、他のプラグイン、メモリ、スキルは隔離環境にない
• scaffold_script が書いた .claude/ や .mcp.json も読み込まれない。スクリプトで用意できるのはファイルとgitの状態だけ
• ケース定義は隠される。runからはevalディレクトリを読めず、プロンプトやgraderはClaudeに見えない

確かめる順番は、まず出力されたパスを開き、一時ホームと作業ディレクトリのどちらにgraderが見るファイルがあるかを探します。次に、そのファイルの中身をレポートに載っているgraderの基準と並べます。期待と違う箇所が見つかれば、プラグインの指示が足りないのか、graderの基準が厳しすぎるのかを切り分けられます。

つまり、残ったディレクトリにあるのは「プラグインだけが読み込まれた環境でClaudeが作ったもの」です。手元のプロジェクトと結果が違って見えるときは、上の3点が原因になっていないかを先に疑います。scaffold_script の使い方はフィクスチャとモックの記事にあります。--scaffold を付けないとスクリプトは動きません。

2つのフラグを組み合わせる流れ

状況ごとに、どちらを使うかを分けるとこうなります。

公開されたレポートで見る場所

ローカルの report.html も公開されたartifactも、中身は同じ結果データから作られます。上から順に読みます。

• 先頭の判定行とタイルで、スイート全体としてプラグインが効いたかが分かる。スイートのスコア、ベースラインとの差(Δ)、しきい値を満たしたcase数、全graderが通ったrunの割合が並ぶ
• 各caseのカードにはそのcaseのΔとスコアが出て、しきい値の位置に目印がある。Δがマイナスのcaseは左端が赤くなる
• caseの中では、プラグインありのrunが先、ベースラインのrunが後に並ぶ。落ちたgraderは説明つきで最初から開いており、llm graderなら審査モデルの票と、審査に使われた根拠も見える
• 下部には、そのcaseのプロンプトとgraderの基準が載る。スイートを持たない人がレポートだけ読んでも、何を問い何を良しとしたかが分かる

このレポートは外部リクエストを一切しない1枚のファイルなので、ディスクから開く使い方や、CIジョブに添付する使い方もできます。公開が必要なのは、レポートをURLで渡したいときだけです。

レポートの置き場所と出力先の変更

レポートと aggregate-result.json は、評価ディレクトリの results/<timestamp>/ に書かれます。パスを指定して実行したときはプラグインの下、インストール済みのプラグインを名前で指定したときは、カレントディレクトリの ./evals/results/ です。別の場所に出したいときは --output-dir <dir> を使います。--json を付けると進捗行と要約表が出ない静かな実行になるため、Report: や Published: の行を見たい場面では付けずに回します。

公開と保持のあとに残る片付け

--keep-temp で残したディレクトリは、フラグの説明上「残す」ためのものです。作業を終えたら、出力されたパスを自分で削除します。ディレクトリには、Claudeが作った成果物やプロンプトの内容がそのまま残ります。共有マシンやCIの作業領域では、ジョブの最後に削除する前提で使います。

公開側も同様に、artifactは作った時点では自分だけが見られる状態です。Team/Enterpriseでは管理者がartifactの保持期間を設定でき、共有済みのものと非共有のものを別の期間で消せます。長く残したいレポートは、report.html をCIの成果物として別に保存しておくほうが確実です。

まとめ

Claude Codeのセッションに評価を任せると、レポートは既定でローカルに残ります。人に見せたいときは --publish-report、見せたくないときは --no-publish で明示します。公開が成立するには、claude.aiアカウントでの認証とAnthropic APIの利用が前提です。

失敗の原因がレポートから読み取れなければ、1caseを1runに絞って --keep-temp で回し、残ったサンドボックスを直接開きます。費用が1回ごとにかかるので、絞り込みを先にやってから保持を付ける順番が安上がりです。