Claude Codeのplugin evalで評価を再現する

結論：plugin evalはプラグインを同じ条件で採点するために使う

公式のClaude Code changelogは2.1.269の更新として、再現可能な結果とJSON・HTMLレポートを挙げています。プラグインの構成や検証コマンドはPlugins reference、導入・配布の考え方はPlugins公式ガイドで確認できます。これらを根拠に、実行環境とpluginの版を記録します。

誰が何を困っているか：便利さと安全性を分ける

チームでpluginを共有すると、同じ名前のskillでも、更新前後で指示、agent、hook、MCP接続が変わります。レビュー担当が手元で一度試しただけでは、別のモデル、別の作業ディレクトリ、別の権限で同じ結果になるか分かりません。導入担当者の課題は「高得点を取ること」ではなく、変更の影響を説明できることです。

確認軸	evalで見るもの	人間が別に判断するもの
再現性	同じsuiteを同じ条件で実行できるか	実行環境を誰が固定するか
仕事の正確さ	期待する出力・手順・拒否の点数	業務上の許容誤りと影響
安全性	禁止入力や境界逸脱のケース	権限、データ、承認、停止責任
保守性	版を変えた時の差分	継続運用の工数とrollback

既存のpluginをZIPで配布する手順は出所とハッシュを扱い、Skillsの出所確認は優先順位と同期を扱います。plugin evalはその前段で、候補を評価して採用可否を決める記事です。評価と配布を同じ承認にしないことが、変更の見落としを減らします。

実行手順：8ステップで比較可能なレポートを作る

1. claude --versionで2.1.269以降かを記録し、評価担当者、実行日時、OS、対象モデルを台帳へ書きます。
2. 対象pluginのディレクトリとcommitを固定します。作業中の未commit変更を混ぜず、評価対象のmanifest、skills、agents、hooksを一覧化します。
3. 成功条件を自然文ではなく、入力、期待結果、許容差、拒否条件の4項目に分解します。実際の機密データは使わず、匿名化したfixtureを用意します。
4. 通常業務の代表ケースを複数、境界ケースを複数、禁止・エラーケースを複数用意し、ケースごとに合格・不合格の理由を書けるようにします。
5. claude plugin eval --helpで利用可能な引数を確認し、suiteの指定方法と出力先を、実行環境のREADMEへ固定します。
6. 初回実行ではJSONとHTMLの両方を保存し、pluginのcommit、Claude Code version、model、suite、設定scopeを同じメタデータへ結びます。
7. 候補版と現行版を同じfixtureで実行し、総合点だけでなくケース別の失敗、変化した出力、処理時間、レビューコメントを比較します。
8. 採用・修正・保留を決め、採用なら配布経路とrollbackを承認します。不合格ならテストを削除して点数を上げず、失敗理由を次の変更の課題として残します。

同じsuiteでも、モデル、権限、外部MCP、ネットワーク、時刻が変われば結果は変わります。そのため「評価結果」と「本番の実績」を混同しません。HTMLは読みやすいレビュー用、JSONは自動比較用と役割を分け、保存先にはpluginの機密情報や入力原文を必要以上に含めないようにします。

再現性を保つには、レポートのファイル名にも日付だけでなくpluginのversion、suiteの版、実行環境を含めます。失敗した実行も消さず、原因がfixture、設定、モデル、外部依存のどれかを分類してください。採用後にsuiteを更新した時は、過去の合格結果と単純比較せず、変更理由と期待する差分を先にレビューします。

採点結果を導入判断へ変換する

採点表には最低限、ケースID、期待条件、結果、重大度、再現回数、レビュー担当、対応期限を持たせます。総合点が上がっていても、経理処理のような重要ケースが一つ落ちたなら無条件採用にはしません。反対に、低リスクな文章整形の改善だけで全体点が少し下がった場合は、業務ごとの重み付けで判断できます。

判断は三段階にすると運用しやすくなります。全重要ケース合格かつ再現できれば「限定採用」、軽微な差分だけなら「修正期限付き採用」、重要ケースの失敗や権限境界の不明確さがあれば「保留」です。採用時も、対象team、適用scope、承認者、監視指標、停止条件を一緒に記録します。

評価が扱うのはpluginの振る舞いです。会社の個人情報、顧客契約、秘密情報をsuiteへ直接入れる必要はありません。匿名化、最小権限、外部送信先の確認、失敗時の停止を別チェックにし、問題がtelemetryならApps GatewayのOTLP設計、認証ならGateway認証の切り分けへ分けます。

チェックリスト：採用前に残す証跡

□Claude Code versionを固定したか　□pluginのcommitとmanifestを保存したか　□匿名fixtureを使ったか　□成功・境界・拒否ケースがあるか　□suiteを変更して点数を操作していないか　□JSONとHTMLの両方を保存したか　□モデル・権限・設定scopeを記録したか　□ケース別の失敗理由を読んだか　□重要ケースの合格を確認したか　□配布scopeとrollback担当を決めたか　□レポートの閲覧権限を絞ったか　□再評価日を設定したか。

よくある質問

plugin evalは本番品質を保証しますか？

保証しません。決めたケースを同じ条件で実行し、変更前後を比較しやすくする機能です。本番データでの影響、人間のレビュー、権限と停止条件は別に確認します。

点数が高ければ採用してよいですか？

点数だけでは判断しません。重要度の高いケース、禁止操作、再現回数、レビュー工数、データ境界を合わせて、限定採用・修正・保留を決めます。

評価データに実際の顧客情報を入れてよいですか？

原則として匿名fixtureを使います。どうしても必要なら目的、契約、保持、閲覧権限、削除、外部送信先を先に確認し、機密情報をログへ残さない設計にします。

公式情報と無料診断

機能の追加はClaude Code公式changelog、pluginの構造はPlugins reference、運用の前提は公式Pluginsガイドを公開直前にreadbackしました。Miraigentの無料診断では、評価ケース、承認、配布、rollbackを業務に合わせて整理できます。