Claude CodeにDeepEvalプラグインを入れてLLMアプリの評価ループを回す

LLMアプリの改善は、プロンプトを直して目で出力を見る作業になりがちです。DeepEvalプラグインを入れると、この「直して確かめる」をpytest形式の評価スイートに置き換え、実行から失敗の読み取り、修正、再実行までをClaude Codeに回させられます。

DeepEvalは、LLMアプリのユニットテスト向けに作られたオープンソースの評価フレームワークです。READMEはPytestに似た位置づけだと説明しています。この記事では、プラグインの中身、導入、1ラウンドの流れ、Claude Code側に置いておくと安定する設定を順に説明します。

DeepEvalプラグインの中身と、できること

マーケットプレイスの紹介ページには、評価、トレース、データセット、Confident AIのレポート、改善ループを扱うスキル群と書かれています。提供元はConfident AIです。

プラグインの定義ファイルは skills/ ディレクトリを指しており、リポジトリの skills には次の3つが入っています。

スキルの説明文には、評価の依頼とそうでない依頼の線引きが書かれています。たとえば汎用のpytestの設定や、DeepEvalと無関係な可観測性の作業では起動しません。評価を頼んだときだけ働くので、普段のテスト作業を邪魔しない設計です。

評価の対象は、AIエージェント、マルチターンのチャットボット、音声エージェント、RAGなどです。ツールの呼び出しが正しいかを見るToolCorrectnessや、目的を達成したかを見るTaskCompletionのように、エージェント向けの指標が揃っています。判定にはLLM-as-a-judgeが使われ、各指標は0〜1のスコアと理由の文章を返します。

導入:プラグインとPython側の準備

導入は2段階です。Claude Code側にプラグインを入れ、評価を走らせるプロジェクトにPythonのパッケージを入れます。

プラグインを入れる

マーケットプレイスの紹介ページに「Claude Codeで入れる」ボタンがあり、押すとインストールコマンドが得られます。手で入れるなら、リポジトリ自身がマーケットプレイスの定義(名前は deepeval-plugins、中のプラグイン名は deepeval)を持っているので、次の形になります。

/plugin marketplace add confident-ai/deepeval
/plugin install deepeval@deepeval-plugins

マーケットプレイスの追加は owner/repo 形式のGitHubリポジトリを渡す書き方で、Claude Codeのドキュメントにある /plugin marketplace add の形そのままです。インストール後に「packages are not installed」と出る場合の切り分けはpackages are not installedの対処にまとめています。

プラグインを使わず、スキルだけを入れる道もあります。クイックスタートには、Skills対応のインストーラーで入れる次のコマンドが載っています。

npx skills add confident-ai/deepeval --skill "deepeval"

この方法だと入るのは deepeval スキルだけです。トレース用の deepeval-tracing も使いたいなら、プラグイン経由のほうが揃います。

Pythonパッケージを入れる

DeepEval本体はPython 3.9以上で動きます。評価したいアプリのリポジトリで入れます。

pip install -U deepeval

LLM指標の判定にはモデルの認証情報が要ります。READMEの最小例ではOpenAIのAPIキーを環境変数に置いていますが、独自モデルを使う案内もあります。スキルは最初の質問で判定に使うモデルを尋ね、選択肢にはOpenAI、Anthropic、Gemini、ローカル・独自モデルが並びます。

セットアップウィザードという近道

pip install の直後に deepeval setup を実行すると、ウィザードがリポジトリとインストール状態を確認し、判定モデルを設定したうえで、評価作業をClaude Code、Codex、Cursor CLIのうち入っているものへ引き渡します。最後に評価を1回実行して結果を報告します。サポートはmacOSとLinuxで、キーは .env.local に保存され、エージェントへ渡すプロンプトには含まれません。コミットやプッシュもしません。

依頼は一言でよい:最初に聞かれる5つのこと

スキルが入っていれば、「このリポジトリにevalを足して」「リファンドのエージェントを評価して、劣化を直して」「faithfulnessが落ちているのはなぜか」といった依頼で自動的に起動します。クイックスタートによると、Use DeepEval to fix the refund agent — run 5 rounds of the iteration loop くらいの短さでも足ります。

アプリのコードを編集する前に、スキルは次の5点を確認します。

1. 判定に使う評価モデル(既存のDeepEval設定があればそれを使う)
2. データセットの有無と置き場所(ワークスペース内、Confident AI上、または生成してほしい)
3. トレースを組み込むか(スキルは強く勧めています)
4. 結果をConfident AIに送るか
5. 反復のラウンド数(勧められるのは5ラウンド)

これはスキル側の手順で、Claude Codeの質問に答えるだけで設計が決まります。アプリがRAGでありエージェントでもある場合は、スキルの優先順位でエージェントとして扱われ、チャットボットの性質があればマルチターン用の評価になります。

評価ループの1ラウンドで起きること

ループの流れは、データセットの用意、評価スイートの作成、実行、失敗箇所の特定、修正と再検証です。

データ生成と実行のコマンドは、ドキュメントとスキルに次の形で載っています。

deepeval generate \
  --method docs \
  --variation single-turn \
  --documents ./docs \
  --output-dir ./tests/evals \
  --file-name .dataset
 
deepeval test run tests/evals/test_<app>.py \
  --identifier "iterating-on-retrieval-round-1" \
  --num-processes 5 \
  --ignore-errors \
  --skip-on-missing-params

<app> の部分はアプリ名に置き換えます。--identifier にはラウンドごとの目的を入れる決まりで、あとで実行を見分けやすくなります。小さいデータセットや非力なマシンでは --num-processes を省いてかまいません。

ドキュメントの例では、実行結果にfaithfulnessが0.64と出たとき、エージェントが検索の範囲を有効な返金ポリシーに絞り、再実行で0.98に上がります。ただしこれは説明用の例で、実際の数値はアプリごとに違います。

Claude Code側に置いておくと安定する設定

スキルだけでもループは回ります。そこに、リポジトリのCLAUDE.mdと権限設定を足すと、毎ラウンドの確認が減り、評価の不正な書き換えを防げます。以下は筆者の設計例で、公式の設定そのものではありません。

CLAUDE.mdに評価の約束を書く

スキルにも「しきい値を下げない」「難しいゴールデンを消さない」というガードレールがあります。同じ内容をCLAUDE.mdにも書いておくと、スキルが起動しない普通の編集の場面でも守られます。

## LLM評価(DeepEval)
- 評価は `deepeval test run tests/evals/` で実行する。素のpytestは使わない
- 失敗を直すときは、指標・しきい値・ゴールデンを変えない。アプリ側を直す
- モデルやフレームワークの提供元は、確認なしに切り替えない
- 1ラウンドごとに、実行したコマンド、最も低い指標、変更内容、スコアの動きを報告する

最後の項目は、スキルが1ラウンドごとに報告させる内容と揃えてあります。

deepeval test runを許可しておく

評価は何ラウンドも同じコマンドを叩くので、毎回の許可確認が重くなります。実行系のコマンドだけを許可し、既定の挙動は変えない構成が扱いやすいです。許可ルールの書き方はMakefileの検証ループの記事でも同じ型を使っています。

{
  "permissions": {
    "allow": [
      "Bash(deepeval test run:*)",
      "Bash(deepeval view)"
    ]
  }
}

deepeval generate はモデルを呼んで費用が出ることがあるため、許可に入れずに都度確認する構成にしてあります。

評価コストの見積もり

LLM指標は、指標ごと、テストごとに判定モデルを呼びます。ゴールデンの件数、指標の数、ラウンド数が増えるほど、判定の呼び出し回数と費用も増えます。最初は1ラウンドと少ない件数で動作を確かめ、それからラウンドを増やす順が安全です。

トレースを入れると、失敗の場所が分かる

トレースは、アプリの1回の実行を、モデル呼び出し、ツール、検索などのスパンに分けて記録します。評価がスパンごとの指標を持てるので、「アプリが悪い」ではなく「検索のスパンが古いポリシーを引いた」まで絞れます。

deepeval-tracing スキルは、アプリが使っているフレームワークを見て連携を選びます。クイックスタートの検出表では、anthropic を使っていればAnthropic SDKの連携、langgraph ならLangGraphの連携です。READMEの一覧にも、クライアントのラッパーでClaudeアプリを評価・トレースできるとあります。連携がある場合は、同じ処理に @observe を重ねないのが決まりです。

連携が無い、またはフレームワークを使わない素のPythonなら、手動で @observe を付けます。

from deepeval.tracing import observe
 
@observe()
def retrieve_policy_docs(query: str):
    ...
 
@observe()
def app(input: str):
    docs = retrieve_policy_docs(input)
    ...

評価の実行側は、READMEにあるとおり dataset.evals_iterator(metrics=[...]) でゴールデンを回します。実行後は deepeval inspect で、ターミナルのTUIに最新の実行をトレースの木として開けます。入出力、ツール呼び出し、検索の文脈まで見られます。ただし計装されたアプリで取ったトレースを持つ実行だけが対象です。

トレースにはシークレットや機微なデータを載せないのが、スキルの方針です。失敗の理由が見えないときも、まず必要最小限のトレースを足してから、広い修正に進みます。

Confident AIにつなぐと何が増えるか

DeepEvalはローカルだけで完結します。deepeval login でConfident AIにつなぐと、deepeval test run の実行がクラウドにも記録され、deepeval view で最新の実行を開けます。アカウント作成は無料と書かれています。

READMEによると、本番に出たあとは、失敗したトレースをConfident AIが拾ってまとまりにし、次の評価のゴールデンに変える流れが取れます。コード編集の画面から離れたくない場合は、ConfidentのMCPサーバー経由でClaude Codeから失敗トレースとデータセットを引けるとも書かれています。

反復が進まない場合の注意が、スキルの手順にあります。数ラウンド回してもスコアが動かないときは、指標が人の判断と合っていない可能性があります。その場合はレポートをConfident AIに保存し、人手の注釈で合否のずれを見積もる流れを案内します。しきい値を下げて通すのは、指標が明らかにずれていて、利用者が同意した場合に限られます。

つまずきやすい点

• 判定モデルの認証が無い: 指標を動かすには、判定に使うモデルの認証情報が要ります。ウィザードかスキルの質問で選びます
• ウィザードが使えない: deepeval setup はmacOSとLinuxだけが対象です。Windowsなどでは、pip install のあとスキルに依頼する手順で進めます
• スキルが起動しない: DeepEvalと無関係な汎用のpytest作業には反応しません。依頼文に「DeepEval」や「eval」を入れると確実です
• 環境変数の読み込み: DeepEvalはカレントディレクトリの .env.local、次に .env を読みます。優先順位は、プロセスの環境変数、.env.local、.env の順です。DEEPEVAL_DISABLE_DOTENV=1 で止められます
• 反復の途中でモデルが変わる: スキルは、提供元をまたぐ切り替え(OpenAIからAnthropicなど)を確認なしでやらない決まりです。同じ提供元の中でモデル名を上げるのは許されています

他の評価基盤との使い分け

トレースの保管場所が既にMLflowなら、MLflow側のMCPとプラグインで同じ型のループを回せます。手順はMLflow MCPでトレース調査と評価ループを回す記事にあります。DeepEvalの強みは、pytestの形でリポジトリにコミットでき、エージェントなしで再実行できる点です。CI/CDにも組み込めるとREADMEにあります。

PythonのWebアプリ側のテストの型は、Flaskのtest_clientでpytestを使う記事と同じ発想です。そこでの「テストが通ったら完了」を、「評価のスコアが上がったら完了」に置き換えたものがDeepEvalのループになります。

まとめ

DeepEvalプラグインの価値は、評価を「pytestで再実行できる形で残す」ことと、失敗の理由を文章とスパンで読めることにあります。Claude Codeはその出力を読み、アプリの小さな箇所だけを直して、同じコマンドで結果を確かめます。

最初の一歩は、1ラウンドだけ回すことです。CLAUDE.mdに「指標としきい値は触らない」と書き、deepeval test run を許可して、スコアが動く様子を確かめてから、ラウンド数を増やすのが無理のない進め方です。