Plugins mit Evals testen - Claude Code Docs

claude plugin eval führt Ihr Plugin gegen eine Suite von Testfällen aus und bewertet die Ergebnisse. Jeder Fall ist eine realistische Eingabeaufforderung plus ein oder mehrere Grader. Ein Grader ist eine Bestanden/Nicht-Bestanden-Prüfung auf das, was Claude produziert hat, wie z. B. ein Regex über die Antwort, ob ein bestimmtes Tool aufgerufen wurde, oder eine Rubrik, die ein zweites Modell über die Antwort beurteilt. Sie müssen die Suite nicht von Hand schreiben; claude plugin eval init fragt Sie nach Ihrem Plugin, schlägt die Fälle und Grader vor, probiert sie aus und schreibt die Dateien, und Sie können Claude bitten, dasselbe aus einer bereits offenen Sitzung zu tun. Verwenden Sie Evals, um zu messen, wie zuverlässig Ihr Plugin Claude zum richtigen Ergebnis lenkt, um Regressionen zu erkennen, wenn Sie das Plugin ändern oder ein neues Modell ausgeliefert wird, und um zu sehen, was das Plugin im Vergleich zu keinem Plugin beiträgt. Diese Seite ist für Plugin- und Skill-Autoren, die ein funktionierendes Plugin haben und sein Verhalten testen möchten, sowie für Teams, die Plugin-Änderungen in CI gaten. Das Fallformat unterscheidet sich von der Datei evals/evals.json, die das skill-creator Plugin verwendet. Um ein Plugin zu erstellen, siehe Plugins erstellen; um die Dateien eines Plugins auf Syntax- und Schemafehler zu überprüfen, anstatt sein Verhalten zu überprüfen, verwenden Sie claude plugin validate.

Jeder Eval-Durchlauf und jeder Judge-Grader ist ein echter Modellaufruf auf Ihrem Konto, der gegen die Nutzung Ihres Plans oder Ihre API-Rechnung angerechnet wird. Überprüfen Sie daher zunächst die Anforderungen. Erstellen Sie dann Ihre erste Eval-Suite, oder gehen Sie zu Evals in CI ausführen, wenn Sie bereits eine haben.

Anforderungen

Um Plugin-Evals auszuführen, benötigen Sie:

Claude Code v2.1.269 oder später. Führen Sie claude --version aus, um zu überprüfen, und claude update, um zu aktualisieren.
Ein Plugin-Verzeichnis mit einem plugin.json oder .claude-plugin/plugin.json Manifest, oder ein Skills-Directory-Plugin.
Die gleiche Authentifizierung und den gleichen Modell-Provider, den Ihre normalen Claude Code Sitzungen verwenden. Eval-Durchläufe, Judge-bewertete Grader und claude plugin eval init rufen das Modell mit Ihren Anmeldedaten auf, daher werden sie gegen Ihre Plan-Nutzungslimits oder Ihre API-Rechnung angerechnet. Wenn der Befehl Kosten meldet, ist die Zahl eine Listenpreis-Schätzung dieser Aufrufe.

Wie ein Eval-Durchlauf funktioniert

Eine Eval-Suite befindet sich in einem Verzeichnis namens evals/ innerhalb Ihres Plugins, angeordnet wie Fälle schreiben und verfeinern zeigt. Jeder Fall ist sein eigenes Unterverzeichnis mit einer Eingabeaufforderung und einem oder mehreren Gradern. Die Eingabeaufforderung ist etwas, das eine Person, die Ihr Plugin verwendet, eingeben könnte, wie z. B. eine Anfrage, die einer seiner Skills verarbeiten sollte.

Was in einem Durchlauf passiert

Für jeden Durchlauf eines Falls startet Claude Code eine frische, isolierte nicht-interaktive Sitzung mit nur Ihrem Plugin geladen, sendet die Eingabeaufforderung und lässt Claude arbeiten, bis es fertig ist oder das Limit des Falls für Züge oder Zeit erreicht. Jeder Grader überprüft dann die endgültige Antwort, das Transkript oder eine Datei, die Claude erstellt hat, und bestätigt oder lehnt ab.

Wie ein Fall bewertet wird

Ein Durchlauf eines nicht-deterministischen Agenten sagt Ihnen wenig, daher wird jeder Fall standardmäßig dreimal ausgeführt. Der Score eines Durchlaufs ist der Anteil seiner bestandenen Grader, gewichtet, wenn Sie Gewichte festlegen, und der Score des Falls ist der Durchschnitt über seine Durchläufe. Ein Fall wird bestanden, wenn sein Score den --threshold erfüllt, standardmäßig 1,0. Bei Modellaufrufen führt eine Suite ungefähr Fälle × Durchläufe Agent-Durchläufe mit dem Plugin durch und ebenso viele für die Baseline ohne Plugin, plus drei kurze Judge-Aufrufe pro llm oder baseline Grader pro Durchlauf.

Die Baseline ohne Plugin

Ein hoher Score allein sagt Ihnen nicht, dass das Plugin geholfen hat, da Claude auch ohne es gleich gut abschneiden könnte. Um die beiden zu trennen, werden die Durchläufe jedes Falls standardmäßig mit keinem Plugin geladen wiederholt, und Sie erhalten zwei Scores, WITH und W/OUT. Ihr Unterschied, Δ, ist das, was das Plugin beigetragen hat. Wenn ein Fall sowohl mit als auch ohne Plugin 1,0 bewertet wird, ist das Plugin nicht das, was ihn bestanden hat. Die beiden Sätze von Durchläufen werden als With-Arm und Without-Arm bezeichnet; Vergleich mit einer Baseline ohne Plugin behandelt, wie Grader über sie hinweg bewertet werden und wie man die Baseline ausschaltet.

Erstellen Sie Ihre erste Eval-Suite

Diese Anleitung schreibt einen Fall für Ihr eigenes Plugin, führt ihn aus und liest das Ergebnis. Bevor Sie beginnen, stellen Sie sicher, dass Sie haben:

Claude Code v2.1.269 oder später und die anderen Anforderungen
Ein Terminal, das in Ihrem Plugin-Stammverzeichnis geöffnet ist, dem Verzeichnis, das plugin.json oder .claude-plugin/plugin.json enthält
Einen Skill im Plugin, den Sie testen möchten, und eine Anfrage, die ein Benutzer eingeben würde, die ihn auslösen sollte

Erstellen Sie die Fälle

Führen Sie vom Plugin-Stammverzeichnis aus aus:

claude plugin eval init

Wenn Claude Code diesem Verzeichnis noch nicht vertraut, fragt es zunächst Trust this plugin directory?; antworten Sie mit y. Eine interaktive Claude Code Sitzung wird dann geöffnet. Claude liest Ihr Plugin und fragt Sie, wie ein gutes Ergebnis aussieht, schlägt Eingabeaufforderungen vor, die das Plugin auslösen sollten und nicht sollten, entwirft Grader für jeden, probiert sie einmal aus, um zu überprüfen, ob sie sich verhalten, und schreibt ein Fallverzeichnis pro Eingabeaufforderung unter evals/, jeweils nach seiner Eingabeaufforderung benannt. Wenn Claude Ihnen sagt, dass die Suite bereit ist, beenden Sie diese Sitzung mit /exit oder Ctrl+D, um zu Ihrer Shell zurückzukehren.Wenn Sie bereits eine Claude Code Sitzung am Plugin-Stammverzeichnis geöffnet haben, können Sie stattdessen Claude dort bitten, claude plugin eval init auszuführen. Claude führt den Befehl aus und stellt Ihnen dann die gleichen Fragen in dieser Konversation.Wenn Sie einen Fall lieber selbst schreiben möchten, um genau zu sehen, welche Dateien enthalten sind, folgen Sie Schreiben Sie einen Fall von Hand und kommen Sie hierher zurück, um ihn auszuführen.

Führen Sie die Suite aus

Zurück an Ihrer Shell im Plugin-Stammverzeichnis führen Sie jeden Fall unter evals/ aus:

claude plugin eval .

Sie haben diesem Verzeichnis bereits in Schritt 1 vertraut, daher startet der Durchlauf sofort. Wenn Sie den Fall stattdessen von Hand geschrieben haben, fragt der Durchlauf zunächst Trust this plugin directory? [y/N]; antworten Sie mit y. Was ein Durchlauf zugreifen kann erklärt, wofür Sie zustimmen.Jeder Fall wird dreimal mit Ihrem Plugin und dreimal ohne es ausgeführt, daher ist ein Fall sechs Durchläufe. Eine Fortschrittszeile wird gedruckt, wenn jeder Durchlauf fertig ist, mit dem Score dieses Durchlaufs und dem Urteil jedes Graders.

Lesen Sie die Zusammenfassung

Wenn die Suite fertig ist, sehen Sie eine Zusammenfassungstabelle, gefolgt von dem Ort, an den der Bericht ging:

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

WITH ist der Score des Falls mit Ihrem Plugin geladen, W/OUT ist der Score ohne es, und ein positives Δ bedeutet, dass das Plugin den Score erhöht hat. COST ist eine Listenpreis-Schätzung der Modellaufrufe, und NOTES zeigt die Erklärung des höchstgewichteten fehlgeschlagenen Graders oder den Fehler des Durchlaufs aus dem With-Arm.

Öffnen Sie den Bericht und iterieren Sie

Öffnen Sie die Published: URL oder den Report: Pfad, wenn keine Published: Zeile angezeigt wird, um das Urteil jedes Graders und die Erklärung für jeden Durchlauf zu sehen, und für llm Grader die Stimmen des Judges und den Auszug, den er bewertet hat. Die Published: Zeile wird nur angezeigt, wenn Ihr Konto Berichte veröffentlichen kann.Der häufigste erste Fund ist ein Δ nahe Null mit dem fehlgeschlagenen tool_used: Skill Grader des Falls, was bedeutet, dass Claude Ihren Skill bei natürlicher Formulierung nicht auswählt. Passen Sie die description des Skills an, führen Sie claude plugin eval . erneut aus und vergleichen Sie.Um einen Fall kostengünstig zu iterieren, führen Sie einen einzelnen Arm einmal aus. Ein einzelner Durchlauf ist verrauscht, daher bestätigen Sie jede Änderung bei den standardmäßigen drei Durchläufen, bevor Sie ihr vertrauen. Mit einem Arm zeigt die Tabelle SCORE und PASS% Spalten statt WITH, W/OUT und Δ:

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

Ersetzen Sie <case-name> durch einen der Verzeichnisnamen unter evals/.

Fälle schreiben und verfeinern

Die Fälle, die claude plugin eval init schreibt, sind einfache Dateien, die Sie öffnen, ändern und hinzufügen können. Ein Fall ist ein Verzeichnis unter dem Eval-Verzeichnis des Plugins, das eine prompt.md, eine case.yaml oder beide enthält. Um Fälle zu gruppieren, verschachteln Sie sie unter einem Verzeichnis, das selbst kein Fall ist; alles innerhalb eines Fallverzeichnisses, wie graders/ und Fixture-Dateien, gehört zu diesem Fall. Dies ist das Layout, das claude plugin eval init schreibt und das für neue Suites verwendet werden sollte. Die Eval-Suite-Referenz hat den vollständigen Baum, einschließlich Mocks und Ergebnisse:

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

Schreiben Sie einen Fall von Hand

Der empfohlene Weg ist, Claude die Fälle mit claude plugin eval init schreiben zu lassen. Um stattdessen einen selbst zu schreiben, beginnen Sie mit einer leeren Vorlage. Der folgende Befehl schreibt einen Fall namens first-case mit einer Platzhalter-prompt.md und einem Platzhalter-Grader und führt nichts aus:

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

In prompt.md schreiben Sie die Nachricht, die Claude in jedem Durchlauf erhält, und legen die Limits und Tools des Durchlaufs in seinem Frontmatter fest. Öffnen Sie evals/first-case/prompt.md und ersetzen Sie den Platzhalter-Body durch eine Anfrage, die einer Ihrer Skills verarbeiten sollte, formuliert wie ein Benutzer sie eingeben würde, anstatt den Skill zu benennen. Dieses Beispiel ist für einen Skill, der Commit-Nachrichten entwirft; verwenden Sie Ihre eigene Anfrage:

---
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.

Jeder Durchlauf startet in einem leeren Arbeitsverzeichnis, daher legen Sie alles, was die Aufgabe benötigt, in die Eingabeaufforderung selbst, oder richten Sie den Arbeitsbereich zuerst ein. Die vollständige Liste der Frontmatter-Felder behandelt das Modell, Timeout, Tags und Umgebungsvariablen. Jede Datei unter graders/ ist eine Prüfung, die nach dem Durchlauf angewendet wird. Öffnen Sie evals/first-case/graders/criteria.md und ersetzen Sie den Platzhalter durch eine Rubrik für das Judge-Modell, geschrieben als konkrete PASS- und FAIL-Bedingungen:

---
type: llm
---

PASS if <what a correct response contains>.
FAIL if <what a wrong or missing response looks like>.

Fügen Sie dann einen zweiten Grader hinzu, der überprüft, ob Ihr Skill das ist, was die Antwort produziert hat. Erstellen Sie evals/first-case/graders/skill-fired.md, ersetzen Sie your-skill-name durch den name aus Ihrem Skill’s SKILL.md:

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'
---

Dies wird bestanden, wenn Claude diesen Skill mindestens einmal während des Durchlaufs aufgerufen hat, einschließlich seiner namensraum-qualifizierten Form plugin-name:skill-name. Grader-Typen listet die anderen verfügbaren Prüfungen auf, wie z. B. das Abgleichen eines Regex oder das Bestätigen, dass eine Datei erstellt wurde. Wenn beide Dateien gespeichert sind, führen Sie den Fall wie die Schnellstart mit claude plugin eval . vom Plugin-Stammverzeichnis aus.

Legen Sie Durchlauf-Limits und Tools in prompt.md fest

Legen Sie max_turns, timeout_seconds, model, tags und die allowed_tools eines Falls in der Frontmatter von prompt.md fest; die prompt.md Frontmatter Referenz listet jedes Feld und seinen Standard auf. Claude erhält den Body genau wie Sie ihn geschrieben haben. @path Erwähnungen darin werden nicht in Datei-Anhänge erweitert, daher müssen Sie, wenn Claude eine Datei lesen muss, ein Tool dafür in allowed_tools gewähren.

Wählen Sie Grader und gewichten Sie sie

Die Frontmatter eines Graders legt seinen type fest und optional ein weight, das ihn für mehr des Scores des Durchlaufs zählen lässt, und einen arm, der steuert, wie er gegen die Baseline bewertet wird. Von den sechs Typen werden regex, tool_used, tool_order und file_exists aus dem Transkript und den Dateien berechnet und kosten nichts, während llm und baseline ein Judge-Modell aufrufen und zu den Kosten des Durchlaufs beitragen. Es gibt keine benutzerdefinierten Code-Grader. Grader-Typen listet die Optionen und Bestanden-Bedingungen jedes Typs auf, und was ein Grader ansehen kann listet die Werte auf, die target und focus akzeptieren. Der Judge für llm und baseline Grader ist standardmäßig ein kleines schnelles Modell. Übergeben Sie --judge-model sonnet oder eine vollständige Modell-ID, um ein stärkeres für nuancierte Rubriken zu verwenden.

Wählen Sie Grader, die ein stabiles Signal geben

Ein llm Grader fragt ein Modell nach einem Urteil, daher kann seine Antwort zwischen Durchläufen unterschiedlich sein, und sie unterscheidet sich mehr, je länger der Text ist, den es lesen muss. Diese Gewohnheiten halten die Scores einer Suite stabil genug, um ihnen zu vertrauen:

Für lange Ausgaben wie eine generierte Datei bewerten Sie sie mit einem regex Grader über den Inhalt der Datei, der die ganze Datei jedes Mal gleich überprüft. Behalten Sie llm Grader für kurze Ausgaben, mit Rubriken, die als konkrete PASS- und FAIL-Bedingungen geschrieben sind.
Geben Sie jedem Fall einen Grader auf das Ergebnis, wie die endgültige Nachricht oder eine produzierte Datei, und einen auf wie Claude dorthin kam, wie tool_used oder tool_order. Zusammen sagen sie Ihnen sowohl, ob die Antwort richtig war, als auch ob Ihr Plugin sie produziert hat.
Wenn ein tool_used: Skill Grader eines Falls bestanden wird, aber Δ negativ ist, verdächtigen Sie den Judge vor dem Plugin. Ein kleines Judge-Modell kann eine korrekte Antwort als falsch markieren, weil sie anders formatiert ist als das, was die Rubrik beschreibt. Führen Sie erneut mit --judge-model sonnet aus und straffen Sie die Rubrik, damit die Formatierung das Urteil nicht entscheidet.
Um zu überprüfen, dass ein Build oder Test innerhalb des Durchlaufs bestanden wurde, bitten Sie die Eingabeaufforderung Claude, ihn auszuführen und das Ergebnis in eine Datei zu schreiben, bewerten Sie diese Datei und bestätigen Sie, dass der Befehl mit einem tool_used Grader ausgeführt wurde, dessen input_match den Befehl benennt.

Bewerten Sie gegen die Baseline ohne Plugin

Wenn ein Plugin unter Test steht, wird jeder Fall standardmäßig in zwei Arms ausgeführt. Der With-Arm ist seine Durchläufe mit dem Plugin geladen, und der Without-Arm ist die gleiche Anzahl von Durchläufen ohne Plugin. Die Zusammenfassung und der Bericht zeigen beide Scores und Δ, den With-Arm Score minus den Without-Arm Score. Übergeben Sie --ablation none, um nur den With-Arm auszuführen, was die Kosten halbiert, wenn Sie den Vergleich nicht benötigen, wie z. B. beim Iterieren über Grader. In einem Zwei-Arm-Durchlauf werden einige Grader mit scored: false gemeldet. Eine Prüfung wie „der Skill wurde aufgerufen” kann ohne das Plugin nie bestanden werden, daher würde das Zählen den Without-Arm gegen Null drücken und Δ aufblasen. Um die beiden Arms vergleichbar zu halten, schließt Claude Code solche Grader aus der Bewertung in beiden Arms aus und meldet sie im With-Arm nur als Bestanden/Nicht-Bestanden-Indikatoren. Das umfasst:

Jeden tool_used Grader, dessen tool Skill ist
Jeden Grader, den Sie mit arm: with-only markieren

Wenn jeder Grader in einem Fall einer dieser ist, werden sie stattdessen normal bewertet, da es nichts mehr zu bewerten gäbe. Setzen Sie arm: both auf einen Grader, um ihn in beiden Arms unabhängig zu bewerten, was Sie für eine „darf den Skill nicht aufrufen” Prüfung mit min: 0 und max: 0 wollen. Unter --ablation none wird nichts ausgeschlossen, daher kann die gleiche Suite in den beiden Modi einen anderen absoluten Score produzieren.

Verwenden Sie ein anderes Eval-Verzeichnis

Wenn evals/ bereits von einem anderen Tool verwendet wird, behalten Sie die Suite in einem anderen Verzeichnis. Sie können dieses Verzeichnis in der plugin.json des Plugins aufzeichnen, damit jeder Durchlauf und jeder Mitarbeiter es verwendet, oder übergeben Sie es in der Befehlszeile für einen einzelnen Durchlauf:

In plugin.json: fügen Sie "experimental": { "evals": "quality/evals" } hinzu.
In der Befehlszeile: übergeben Sie --eval-dir quality/evals an sowohl claude plugin eval als auch claude plugin eval init.

Wenn Sie beide setzen, wird das Verzeichnis der Flag verwendet. Geben Sie einen relativen Pfad aus einfachen Verzeichnisnamen wie qa oder quality/evals an; ein absoluter Pfad oder einer mit .. wird abgelehnt: als Flag-Wert ist es ein Fehler, während ein nicht verwendbarer Manifest-Wert eine Warning: Zeile druckt und der Durchlauf stattdessen evals/ verwendet. Fälle, Ergebnisse und init Ausgabe verschieben sich alle in dieses Verzeichnis.

Richten Sie Fixtures und Mocks ein

Ein Fall kann mehr als eine Eingabeaufforderung benötigen: Dateien oder ein Git-Repository im Arbeitsbereich, eine frühere Konversation zum Fortsetzen oder Antworten von den MCP-Servern, mit denen Ihr Plugin spricht. Jede davon wird neben dem Fall eingerichtet, damit Durchläufe wiederholbar bleiben.

Säen Sie den Arbeitsbereich oder die Konversation

Jeder Durchlauf startet in einem leeren Arbeitsbereich. Wenn ein Fall mehr als die Eingabeaufforderung benötigt, fügen Sie neben prompt.md eine case.yaml mit einem context Block hinzu. Um zuerst Fixture-Dateien oder ein Git-Repository zu erstellen, schreiben Sie ein Bash-Skript im Fallverzeichnis und benennen Sie es in context.scaffold_script. Das Skript wird als Sie ausgeführt, außerhalb der Sandbox des Agenten, und nur wenn Sie --scaffold übergeben, daher übergeben Sie dieses Flag nur für Suites, die Sie oder Ihre Organisation geschrieben haben. Um eine frühere Konversation fortzusetzen, speichern Sie das Transkript als .jsonl Datei und benennen Sie es in context.history_file, und die Eingabeaufforderung des Falls wird zum nächsten Benutzer-Turn. Um Claude Fixture-Verzeichnisse im Fall während des Durchlaufs lesen zu lassen, listen Sie sie in context.add_dirs auf. Eine case.yaml benötigt auch schema_version: "1.1" und name; die case.yaml Felder Referenz hat die vollständige Liste. Diese case.yaml säet einen Arbeitsbereich aus einem Skript und lässt Claude Fixtures aus einem resources/ Verzeichnis lesen:

schema_version: "1.1"
name: changelog-from-diff
tags: [smoke]
context:
  scaffold_script: fixture.sh
  add_dirs: [resources]

Mock MCP Server

Sie können ein Plugin evaluieren, dessen Skills MCP-Tools aufrufen, ohne den echten Service dahinter. Legen Sie eine Markdown-Datei pro Tool unter evals/mocks/<server>/<tool>.md für die ganze Suite oder unter einem eigenen mocks/ Verzeichnis eines Falls für einen Fall, wobei <server> der Name des Servers in der MCP-Konfiguration Ihres Plugins ist. Ein Durchlauf startet niemals die echten MCP-Server Ihres Plugins, es sei denn, Sie fragen danach. Claude Code registriert einen Stand-In unter jedem Server-Namen. Tools mit einer Mock-Datei antworten daraus und sind ohne einen --allow-tools Grant erlaubt, und ein Tool ohne Mock-Datei ist für Claude nicht verfügbar. Ein Server ohne Mocks überhaupt erscheint in der mocked: Fortschrittszeile des Falls als plugin_<plugin>_<server>[not started: no mock]. Der Body der Datei ist das, was das Tool an Claude zurückgibt. Dieser Mock steht für ein create_issue Tool auf einem Server namens tracker ein, überprüft die Eingabe, die Claude sendet, und gibt den Titel zurück. Speichern Sie es als evals/mocks/tracker/create_issue.md:

---
expect:
  title: string
  priority: [low, medium, high]
---

Created issue #4821: {{input.title}}

Fügen Sie Felder aus der Eingabe des Aufrufs mit {{input.<field>}} ein, und den Inhalt einer Fixture-Datei neben dem Mock mit {{file:fixtures/{input.<field>}.json}}. Der expect: Block schützt die Eingabe. Wenn ein Aufruf ihn verletzt, bricht der Durchlauf mit Score 0 ab und zeichnet auf, warum, daher kann ein Fall bestätigen, was Ihr Plugin den Server zu tun bat. Setzen Sie error: true, um den Body stattdessen als Tool-Fehler zurückzugeben, oder type: agent, um ein kleines Modell als Server aus Anweisungen im Body antworten zu lassen. Die Mock-Datei-Referenz listet jeden Schlüssel und die _server.md und _tools.json Dateien auf. Um die Aufrufe selbst zu bewerten, zeigen Sie einen Grader auf target: mock_calls. Um stattdessen gegen die echten MCP-Server des Plugins auszuführen, übergeben Sie eines dieser Flags. Entweder Weg laufen diese Prozesse als Sie, außerhalb der Sandbox des Durchlaufs, und ihre Tools benötigen einen --allow-tools Grant:

--allow-real-servers: starten Sie den echten Prozess für jeden Server, den Sie nicht gemockt haben, und beantworten Sie weiterhin gemockte Tools aus ihren Dateien
--mocks off: ignorieren Sie mocks/ vollständig und starten Sie jeden Server, den das Plugin deklariert

Wiedergeben Sie Agent-Mock-Antworten

Ein type: agent Mock antwortet mit einem Aufruf an das --judge-model, daher variiert seine Ausgabe zwischen Durchläufen und ändert sich, wenn Sie den Judge ändern. Wenn ein Durchlauf ohne Fehler oder Abbruch abgeschlossen wird, speichert Claude Code jede Antwort, die ein Agent-Mock gab, unter dem Ergebnisverzeichnis in mock-recordings/. Öffnen Sie ADOPT.txt dort, um jede Aufzeichnung und das .replay/<server>/ Verzeichnis zu sehen, um es neben den Mock zu kopieren, der es produziert hat. Nachdem Sie eine Aufzeichnung dort kopiert haben, beantworten spätere Durchläufe den identischen Aufruf daraus ohne Modellaufruf. Committen Sie mocks/.replay/ mit dem Rest von mocks/, damit CI-Durchläufe wiederholbar sind.

Führen Sie Evals aus

Sobald eine Suite existiert, führt claude plugin eval sie aus. Sie wählen, welches Plugin und welche Fälle mit dem Zielargument ausgeführt werden, gewähren alle Tools, die die Fälle über die schreibgeschützte Menge hinaus benötigen, mit --allow-tools, und steuern Durchlauf-Anzahl, Modelle, Kosten und Ausgabe mit den anderen Optionen.

Wählen Sie aus, was zu evaluieren ist

Meistens führen Sie claude plugin eval . vom Plugin-Stammverzeichnis aus, was jeden Fall in der Suite mit dem Plugin ausführt, in dem Sie stehen, geladen. Um eine einzelne prompt.md oder case.yaml Datei auszuführen oder um ein Plugin zu evaluieren, das Sie installiert haben, anstatt eines, das Sie entwickeln, übergeben Sie ein anderes Ziel:

Ziel	Was wird ausgeführt
Ein Plugin-Stammverzeichnis, wie `.`	Jeder Fall unter seinem Eval-Verzeichnis, mit diesem Plugin geladen
Eine einzelne `prompt.md` oder `case.yaml` Datei	Dieser Fall, mit seinem einschließenden Plugin geladen
Ein installiertes Plugin nach Name, `name` oder `name@marketplace`	Die Fälle im Eval-Verzeichnis der installierten Kopie, mit der installierten Kopie geladen. Ergebnisse werden unter `./evals/results/` in Ihrem aktuellen Verzeichnis geschrieben, oder `./<dir>/results/` mit `--eval-dir`
`name@skills-dir`	Das gleiche, für ein Skills-Directory-Plugin
Weggelassen	Das aktuelle Verzeichnis als Pfad

Fügen Sie --case <glob> hinzu, um nach Fallname zu filtern, und --tag <tag>, um Fälle mit beliebigen der angegebenen Tags zu behalten. Legen Sie das Ziel vor --tag, --allow-tools und --json. Die ersten beiden nehmen eine Liste und --json nimmt einen optionalen Pfad, daher liest jede von ihnen ein Ziel, das folgt, als ihren eigenen Wert.

Gewähren Sie Tools

Durchläufe halten niemals an, um um Erlaubnis zu fragen. Eingebaute Tools, die einen Grant benötigen, den Sie nicht gegeben haben, wie Bash, Write, Edit, WebFetch und WebSearch, werden aus der Sitzung entfernt, daher kann Claude sie überhaupt nicht aufrufen. Die Allowlist ist die schreibgeschützten Tools, die der Fall in allowed_tools auflistet, aus Read, Glob, Grep, NotebookRead, Skill, Agent, TodoWrite und die Task-Tools TaskCreate, TaskGet, TaskList, TaskUpdate, TaskStop und TaskOutput, plus alles, was Sie mit --allow-tools gewähren, was auf jeden Fall in dem Durchlauf angewendet wird. Um Fällen die Verwendung von Bash, Write, Edit, WebFetch oder WebSearch zu ermöglichen, gewähren Sie sie selbst:

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

Wenn ein Fall ein Tool fragte, das Sie nicht gewährt haben, listet der Durchlauf es auf stderr als not granted auf. Tools auf einem gemockten MCP-Server benötigen keinen Grant. Tools auf einem echten Plugin-MCP-Server benötigen sowohl den Server gestartet, mit --allow-real-servers oder --mocks off, als auch einen Grant nach Name, wie --allow-tools "mcp__plugin_my-plugin_github__*"; Plugin-MCP-Tools werden mcp__plugin_<plugin>_<server>__<tool> benannt. Wenn Sie Bash in irgendeiner Form gewähren, wird jeder Befehl unter Claude Code’s OS-Level Sandbox ausgeführt. Schreibvorgänge sind auf den Arbeitsbereich des Durchlaufs beschränkt, Ihr Home-Verzeichnis und die Claude Code Konfiguration sind nicht lesbar, und der Netzwerkzugriff ist auf Domains beschränkt, die Sie mit --allow-tools "WebFetch(domain:example.com)" gewähren. Wenn Sie Bash oder PowerShell auf einer Maschine ohne Sandbox-Backend gewähren, weigert sich Claude Code jeden Durchlauf, anstatt ihn uneingeschränkt auszuführen, und der Fall zeigt einen Durchlauf-Fehler und normalerweise Score 0. Natives Windows hat kein Backend, daher führen Sie Shell-gewährende Suites unter WSL2 aus; unter Linux installieren Sie zuerst bubblewrap und socat. Siehe die Sandboxing-Voraussetzungen.

Befehlsoptionen

Diese Tabelle behandelt die Optionen für Durchlauf-Anzahl, Modelle, Bewertung, Kosten, Tool-Grants, Mocks und Ausgabe. Führen Sie claude plugin eval --help für die vollständige Liste aus, die auch --case, --tag, --eval-dir, --no-scaffold, --report und --verbose umfasst.

Option	Standard	Effekt
`--runs <n>`	Jedes Falls `runs`, sonst 3	Durchläufe pro Fall pro Arm
`-j`, `--concurrency <n>`	`1`	Führen Sie bis zu dieser vielen Agent-Durchläufen gleichzeitig aus, von 1 bis 8. Sie teilen sich das Rate-Limit Ihres Kontos, daher verkürzt dies die Wall-Clock-Zeit, anstatt den Durchsatz über dieses Limit hinaus zu erhöhen. Ergebnisse behalten Fallreihenfolge
`--model <model>`	Jedes Falls `model`, sonst `ANTHROPIC_MODEL`, wenn gesetzt, sonst Claude Code’s Standard	Modell für den Agent unter Test. Heften Sie es in CI fest, damit ein Modell-Rollout nicht mit einer Plugin-Regression verwechselt wird
`--judge-model <model>`	Ein kleines schnelles Modell	Modell für `llm` und `baseline` Grader
`--ablation <mode>`	`with-without`, wenn ein Plugin aufgelöst wird, sonst `none`	Ob auch jeden Fall ohne das Plugin auszuführen, um zu messen, was es hinzufügt. `none` führt einen Arm aus; `with-without` fügt die Baseline ohne Plugin hinzu
`--threshold <0..1>`	`1.0`	Ein Fall wird bestanden, wenn sein With-Arm Score mindestens dies ist. Jeder Fall darunter lässt den Befehl mit 1 beenden
`--max-cost-usd <usd>`	Keine Obergrenze	Eine Obergrenze auf die Listenpreis-Kostenschätzung des Durchlaufs, nicht auf die Plan-Nutzung. Überprüft, bevor jeder Durchlauf startet. Einmal ausgegeben, startet nichts Weiteres; Durchläufe, die bereits in Flug sind, beenden sich, daher kann die Ausgabe die Obergrenze um diese Durchläufe überschreiten. Wenn ein Durchlauf nicht gestartet wird, beendet sich der Befehl mit 2 mit Teilergebnissen
`--allow-tools <tools...>`	Keine	Gewähren Sie Tools über die schreibgeschützte Menge. Siehe Gewähren Sie Tools
`--scaffold`	Aus	Führen Sie das `scaffold_script` jedes Falls aus
`--trust-plugin`	Aus	Überspringen Sie die erste Vertrauens-Eingabeaufforderung für ein Plugin, dessen Code und Suite Sie selbst ausführen würden. Übergeben Sie es in CI, damit der Job niemals durch die Eingabeaufforderung verweigert oder daran warten gelassen wird. Siehe Was ein Durchlauf zugreifen kann
`--mocks <mode>`	`record`	`record` beantwortet MCP-Tool-Aufrufe aus Mocks, startet nicht die echten Server des Plugins und speichert Agent-Mock-Antworten zur Wiedergabe. `off` ignoriert Mocks und startet die echten MCP-Server des Plugins
`--allow-real-servers`	Aus	Mit `--mocks record`, starten Sie auch die echten MCP-Server des Plugins für Server, die kein Mock haben
`--json [path]`	Aus	Drucken Sie das Ergebnis-Dokument auf stdout, oder schreiben Sie es in einen Pfad, der auf `.json` endet. Der Durchlauf ist ruhig: keine Fortschrittszeilen oder Zusammenfassungstabelle
`--output-dir <dir>`	`<eval dir>/results/<timestamp>/`	Wo `aggregate-result.json` und `report.html` hingehen
`--no-publish`		Behalten Sie den HTML-Bericht lokal. Siehe HTML-Bericht
`--publish-report`		Veröffentlichen Sie den Bericht auch dort, wo er standardmäßig lokal bleiben würde, wie ein Durchlauf, den eine Claude Code Sitzung gestartet hat
`--keep-temp`	Aus	Behalten Sie das Sandbox-Verzeichnis jedes Durchlaufs und drucken Sie seinen Pfad zum Debuggen, was Claude produziert hat

Führen Sie Evals in CI aus

Führen Sie in Ihrem CI-Job die Suite mit --json aus, um das Ergebnis zum Archivieren zu schreiben, und lassen Sie den Build beim Exit-Code fehlschlagen. Übergeben Sie --trust-plugin, damit der Job niemals bei der ersten Vertrauens-Eingabeaufforderung wartet, heften Sie beide Modelle fest, damit Scores über die Zeit vergleichbar sind, behalten Sie den Bericht lokal und setzen Sie eine Kostendecke als Obergrenze:

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

Der Exit-Code des Jobs sagt Ihnen, was passiert ist:

Exit-Code	Bedeutung
0	Jeder Fall hat bei oder über `--threshold` bewertet und jede Falldatei geladen
1	Ein Fall hat unter dem Threshold bewertet, eine Falldatei konnte nicht geladen werden, keine Fälle wurden gefunden, ein Durchlauf konnte nicht gestartet werden, das Plugin-Verzeichnis ist nicht vertraut und `--trust-plugin` wurde nicht übergeben, oder eine Option war ungültig
2	Teilweiser Durchlauf: die `--max-cost-usd` Obergrenze wurde erreicht, oder Ihre Anmeldedaten wurden vor oder beim ersten Durchlauf abgelehnt. `results.json` wird immer noch mit `partial: true` und dem Grund geschrieben
130	Unterbrochen. Teilergebnisse werden geschrieben
143	Beendet, wie durch ein CI-Timeout

Probleme beim Schreiben oder Veröffentlichen des HTML-Berichts ändern niemals den Exit-Code. Um zu sehen, warum ein Fall niedrig bewertet wurde, führen Sie ihn lokal ohne --json aus, damit die Pro-Durchlauf-Fortschritts- und Grader-Zeilen drucken. Ein CI-Runner benötigt eine Claude Code Installation und Anmeldedaten in der Umgebung wie ANTHROPIC_API_KEY. Ohne --trust-plugin wird ein Job, dessen Checkout-Verzeichnis Claude Code noch nicht vertraut, mit Exit 1 verweigert, wenn es kein Terminal hat, oder wartet bei der Eingabeaufforderung, wenn der Runner eines zuweist. claude plugin eval init benötigt ein Terminal, um Ihnen seine Fragen zu stellen; führen Sie in CI claude plugin eval init --bare <name> aus, um die leere Vorlage zu erhalten. Um Kosten vorhersehbar zu halten, geben Sie schnelle Every-Change-Suites nur Grader, die keinen Judge aufrufen, verwenden Sie --ablation none, wo Sie Δ nicht benötigen, und lassen Sie partial: true Dokumente und Durchläufe mit skippedPaidGraders aus jedem Trend, den Sie kartieren.

Lesen Sie die Ergebnisse

Jeder Durchlauf mit mindestens einem Fall schreibt ein results/<timestamp>/ Verzeichnis innerhalb des Eval-Verzeichnisses, das aggregate-result.json und report.html enthält. Für ein Pfad-Ziel, das unter dem Plugin liegt; für ein Plugin, das Sie benannt haben, liegt es unter Ihrem aktuellen Verzeichnis, wie die Ziel-Tabelle zeigt. Die Zusammenfassungstabelle, das JSON und der Bericht rendern alle die gleichen Ergebnisdaten.

HTML-Bericht

report.html ist eine einzelne in sich geschlossene Datei, die keine externen Anfragen stellt, daher können Sie sie an einen CI-Job anhängen oder von der Festplatte öffnen. Dieses Beispiel ist die Oberseite eines Berichts für einen Drei-Fall-Suite-Durchlauf mit --threshold 0.8; die angezeigten Kosten sind eine Listenpreis-Schätzung und variieren je nach Modell und Anzahl der Fälle:

Oberseite eines Eval-Berichts: eine Urteilszeile mit dem Text „Plugin-Effekt: +33,3 Punkte gegenüber Baseline, 2 verbessert, 1 gleich, 0 von 3 Fällen verschlechtert", fünf Zusammenfassungs-Kacheln für Suite-Score, Ablations-Delta, Baseline-Score, Fälle, die den Schwellenwert erfüllen, und perfekte Durchläufe, dann der erste Fall mit seinem Delta, Score-Balken und einem Durchlauf, dessen zwei Grader beide „bestanden" anzeigen

Lesen Sie es von oben nach unten:

Die Urteilszeile und Kacheln beantworten die Frage, ob das Plugin über die gesamte Suite hinweg geholfen hat. Suite-Score ist der Durchschnitt der Pro-Fall-Scores mit Plugin, Ablations-Δ ist, wie weit dieser über oder unter dem Baseline-Score liegt, und Fälle zählt, wie viele den Schwellenwert erfüllt haben. Perfekte Durchläufe ist der Anteil der Mit-Plugin-Durchläufe, bei denen jeder Grader bestanden hat.
Jede Fall-Karte zeigt das Δ des Falls und den Score mit Plugin, mit einem Häkchen auf dem Balken beim Schwellenwert. Ein Fall, dessen Δ negativ ist, erhält eine rote linke Kante, daher heben sich Verschlechterungen beim Scrollen ab.
Innerhalb eines Falls kommen die Mit-Plugin-Durchläufe zuerst und die Baseline-Durchläufe danach. Jeder Durchlauf listet seine Grader mit einem Bestanden- oder Nicht-Bestanden-Chip auf. Ein fehlgeschlagener Grader ist bereits erweitert mit seiner Erklärung, und ein llm Grader zeigt auch die Stimmen des Richters und die Beweise, die ihm gezeigt wurden, was ist, wo Sie herausfinden, warum ein Durchlauf niedrig bewertet wurde. Grader, die nicht zur Bewertung zählen, wie tool_used: Skill, tragen ein plugin-fired indicator Badge.
Eingabeaufforderung und Grader, unter den Durchläufen, zeigen die Eingabeaufforderung des Falls und die Rubrik oder das Muster jedes Graders, damit jemand, der den Bericht ohne die Suite liest, sehen kann, was gefragt wurde und was als gut zählte.

Wenn Sie mit einem claude.ai Abonnement angemeldet sind und Artifacts für Ihr Konto verfügbar sind, veröffentlicht Claude Code den Bericht auch als privates Artifact und druckt Published: <url>. Übergeben Sie --no-publish, um ihn lokal zu behalten. Wenn keine Published: Zeile angezeigt wird, wie bei API-Schlüssel-Authentifizierung, ist die lokale Datei der Bericht. Ein Durchlauf, den eine Claude Code Sitzung gestartet hat, wie wenn Sie Claude bitten, die Suite für Sie auszuführen, bleibt auch lokal, und seine Report: Zeile sagt kept local. Fügen Sie --publish-report zu diesem Befehl hinzu, um ihn zu veröffentlichen.

JSON-Ergebnis

aggregate-result.json und --json Ausgabe ist ein versioniertes Dokument mit schemaVersion: 1 für CI-Skripte zum Parsen. Feldnamen sind camelCase und neue Felder werden hinzugefügt, ohne bestehende umzubenennen, daher schreiben Sie Ihr Skript, um Felder zu ignorieren, die es nicht erkennt. Dies sind die Felder, die ein Gating-Skript normalerweise liest. Das Dokument trägt auch die Suite-Konfiguration, jede Grader-Definition und Pro-Durchlauf-Grader-Ergebnisse mit Erklärungen und Beweisen:

Feld	Bedeutung
`partial`, `partialReason`	`true` mit `cost_ceiling`, `interrupted` oder `auth_failed`, wenn die Suite nicht fertig wurde. Lassen Sie Teilergebnisse aus Trend-Diagrammen
`aggregates.overallScore`	Mittlerer Fall-Score über die Suite
`aggregates.casesPassed`, `aggregates.casesTotal`	Fälle bei oder über `--threshold` und die Gesamtzahl
`aggregates.meanDelta`	Mittleres `Δ` über Fälle, unter dem Zwei-Arm-Modus
`cases[].name`	Fallname
`cases[].aggregates.score`	Mittlerer With-Arm-Durchlauf-Score für den Fall
`cases[].aggregates.delta`	With-Arm Score minus Without-Arm Score. Weggelassen, wenn die Arms nicht vergleichbar sind
`cases[].arms.with[].error`	`null`, oder warum ein Durchlauf abnormal endete, wie `timed out after 300s`. Ein Durchlauf, der gestartet, aber schlecht endete, wird immer noch auf das bewertet, was er produziert, daher impliziert ein nicht-null Fehler nicht Score 0
`cases[].arms.with[].aborted`	Vorhanden, wenn ein Mock’s `expect:` oder `abort_when` den Durchlauf stoppte, mit `server`, `tool` und `reason`. Der Durchlauf bewertet 0 und `error` bleibt `null`
`cases[].arms.with[].skippedPaidGraders`	`true`, wenn die Kostendecke dieses Durchlaufs Judge-Grader übersprungen hat, daher ist sein Score nicht vergleichbar
`costUsd`, `durationSeconds`, `claudeVersion`	Geschätzte Kosten zum Listenpreis einschließlich Judge-Aufrufe, Wall-Clock-Sekunden und die Claude Code Version, die die Suite ausgeführt hat

Was ein Durchlauf zugreifen kann

claude plugin eval lädt die Skills und Hooks des Ziel-Plugins und führt seine Eval-Suite auf Ihrem Computer als Sie aus. Es auf ein Plugin zu zeigen ist die gleiche Vertrauensentscheidung wie claude --plugin-dir, daher evaluieren Sie nur Plugins, denen Sie vertrauen. Die in diesem Abschnitt beschriebene Isolation begrenzt, was der Agent unter Test erreichen kann; es ist keine Grenze gegen den Code des Plugins selbst, und eine Suite, die bestanden wird, sagt nichts darüber aus, ob das Plugin sicher ist.

Vertrauen Sie dem Plugin-Verzeichnis

Das erste Mal, wenn Sie claude plugin eval gegen ein Verzeichnis ausführen, fragt Claude Code Trust this plugin directory?, bevor es etwas daraus lädt, es sei denn, Sie haben die Vertrauens-Eingabeaufforderung dort bereits in einer interaktiven claude Sitzung akzeptiert. Innerhalb eines Git-Repositorys vertraut das Beantworten mit Ja dem ganzen Repository, auch für interaktive Sitzungen. Wenn stdin oder stdout kein Terminal ist, oder unter --json, kann der Durchlauf nicht fragen und wird mit Exit 1 verweigert; übergeben Sie --trust-plugin, um das Vertrauen selbst zu bestätigen, nur für ein Plugin, das Sie auf Ihrem eigenen Computer ausführen würden. Ein Ziel, das Sie benennen, anstatt als Pfad zu geben, bedeutet ein installiertes Plugin oder ein Skills-Directory-Plugin, überspringt die Eingabeaufforderung. Einige Teile des Plugins und der Suite werden nur ausgeführt, wenn Sie ihr Flag für diesen Durchlauf übergeben: ein Falls scaffold_script mit --scaffold, Tools über die schreibgeschützte Menge mit --allow-tools und die echten MCP-Server des Plugins mit --allow-real-servers oder --mocks off. Ein Falls allowed_tools und ein Skill’s eigenes allowed-tools Frontmatter können keines von ihnen erweitern. Wenn das Plugin Hooks ausliefert, die Sie nicht geschrieben haben, oder Sie seine echten MCP-Server starten, behandeln Sie seine Scores als beratend, es sei denn, Sie führen es in einer isolierten Umgebung wie einem Container oder CI-Runner aus, da Hooks und Server außerhalb der Sandbox des Agenten laufen und die Dateien berühren könnten, die die Grader lesen.

Wie Durchläufe isoliert sind

Jeder Durchlauf bekommt ein Wegwerf-Home-Verzeichnis, Arbeitsverzeichnis und Claude Code Konfiguration, und der Agent unter Test wird dort als claude -p Kind-Prozess mit nur Ihrem Plugin geladen ausgeführt. Behalten Sie diese Konsequenzen im Auge, wenn Sie Fälle schreiben:

Nichts Persönliches oder Projekt-Ebene lädt. Ihre Benutzereinstellungen, Hooks, CLAUDE.md Dateien, MCP-Server, andere installierte Plugins, Memory und Skills sind abwesend, und kein Projekt-Scoped .claude/ oder .mcp.json über der Sandbox wird gelesen. Die meiste Ihrer Shell-Umgebung wird auch zurückgehalten; nur eine Allowlist und EVAL_* Variablen erreichen den Durchlauf. Wenn das Plugin Setup benötigt, versenden Sie es im Plugin, erstellen Sie es in einem scaffold_script oder übergeben Sie EVAL_* Variablen.
Verwaltete Richtlinie kann einen Durchlauf immer noch einschränken. Einschränkungen in verwalteten Einstellungen, die ein Administrator auf der Maschine bereitgestellt hat, gelten innerhalb eines Durchlaufs, daher können Ergebnisse auf einer verwalteten Maschine von einer nicht verwalteten durch diese Richtlinie unterschiedlich sein.
Das Artifact-Tool ist aus. Ein Skill, der ein Artifact veröffentlicht, kann nur auf das bewertet werden, was er vor diesem Schritt produziert.
Die Falldefinitionen sind vor dem Agenten verborgen. Ein Durchlauf kann das Eval-Verzeichnis nicht lesen, daher kann Claude die Eingabeaufforderung des Falls, seine Grader oder Nachbar-Fälle nicht sehen.
Keine Netzwerk-Sandbox außerhalb von Shell-Befehlen. Shell-Befehle, die Sie gewähren, werden unter den Sandbox-Regeln des Netzwerks ausgeführt. Ein WebFetch(domain:…) Grant erreicht diese Domain direkt, und die eigenen Hooks des Plugins und alle echten MCP-Server, die Sie starten, können jeden Host erreichen.

Eval-Suite-Referenz

Alles, was eine Eval-Suite enthalten kann, befindet sich unter dem Eval-Verzeichnis des Plugins, evals/, es sei denn, Sie haben ein anderes konfiguriert. Dieser Baum zeigt jede Datei, die claude plugin eval dort liest oder schreibt; nur prompt.md oder case.yaml ist erforderlich, damit ein Fall existiert:

evals/
├── <case>/                        # one directory per case; nest under a non-case directory to group
│   ├── prompt.md                  # frontmatter: case and run fields; body: the prompt
│   ├── case.yaml                  # optional: context.* fields, or the whole case in one file
│   ├── graders/
│   │   └── <name>.md              # one grader per file; frontmatter: type and options; body: rubric
│   ├── mocks/                     # optional: mocks for this case only, same layout as below
│   └── <fixtures, scripts, transcripts referenced by case.yaml>
├── mocks/                         # optional: suite-wide MCP mocks
│   ├── <server>/
│   │   ├── <tool>.md              # one mocked tool; body: the tool result
│   │   ├── _server.md             # optional: one agent that answers several tools
│   │   ├── _tools.json            # optional: saved tools/list response for real descriptions and schemas
│   │   └── fixtures/              # files inserted with {{file:fixtures/...}}
│   └── .replay/<server>/          # adopted agent-mock recordings, answered without a model call
└── results/<timestamp>/           # written by each run; add results/ to .gitignore
    ├── aggregate-result.json
    ├── report.html
    └── mock-recordings/           # agent-mock answers from clean runs, with ADOPT.txt

prompt.md Frontmatter

prompt.md Frontmatter akzeptiert diese Felder. Ein unbekannter Schlüssel ist ein Fehler:

Feld	Standard	Zweck
`schema_version`	`"1.1"`, für Sie gesetzt	Fallformat-Version. Fälle, die als `prompt.md` geschrieben sind, erhalten sie automatisch, daher setzen Sie sie selten
`name`	Der Verzeichnisname	Fallname. `--case` Globs passen ihn an und der Bericht schlüsselt ihn auf
`description`		Für Menschen. Nicht zur Laufzeit verwendet
`tags`	`[]`	Labels für `--tag` Filterung. Ein Fall wird ausgeführt, wenn einer seiner Tags passt
`plugins`	Das nächste einschließende Plugin	Plugin-Verzeichnisse unter Test, relativ zum Fallverzeichnis. Setzen Sie `plugins: ["../.."]`, wenn die Auto-Erkennung Ihr Plugin nicht findet; siehe Das Plugin wurde nicht geladen
`runs`	`3`	Durchläufe pro Arm, 1 bis 50. `--runs` überschreibt es
`expected_outcome`		Für Menschen. Nicht zur Laufzeit verwendet
`model`	Der Standard der Kind-Sitzung	Modell für den Agent unter Test. `--model` überschreibt es
`max_turns`	`10`	Zug-Obergrenze, bis zu 200. Sie zu treffen wird als Durchlauf-Fehler aufgezeichnet und senkt normalerweise den Score, daher setzen Sie ihn großzügig
`timeout_seconds`	`300`	Wall-Clock-Obergrenze pro Durchlauf, bis zu 3600
`allowed_tools`	`[]`	Tools, die der Fall möchte, wie `[Read, Glob, Grep, Skill]`. Schreibgeschützte Tools werden gewährt, wenn sie hier aufgelistet sind; für alles andere, siehe Gewähren Sie Tools
`append_system_prompt`		Text, der an die System-Eingabeaufforderung der Kind-Sitzung angehängt wird
`env`	`{}`	Zusätzliche Umgebungsvariablen für die Kind-Sitzung. Schlüssel müssen `EVAL_[A-Z0-9_]` entsprechen; jeder andere Schlüssel lässt den Durchlauf fehlschlagen. Der Durchlauf erbt nur eine Allowlist aus Ihrer Shell: Grundlagen wie `PATH` und Locale, Proxy- und Zertifikateinstellungen, die Variablen, die Ihren Modell-Provider auswählen und authentifizieren, die meisten `ANTHROPIC_` und `CLAUDE_CODE_` Konfiguration und `EVAL_`. Um dem Plugin etwas anderes zu geben, wie eine Toolchain-Einstellung, exportieren Sie es als `EVAL_*` Variable

case.yaml Felder

case.yaml beschreibt den gleichen Fall in YAML und fügt die Felder hinzu, die auf andere Dateien zeigen. Es benötigt schema_version: "1.1" und name. Die prompt.md Felder description, tags, plugins, runs und expected_outcome gehen auf die oberste Ebene; model, max_turns, timeout_seconds, allowed_tools, append_system_prompt und env gehen unter execution:. Wenn beide Dateien existieren, überschreibt prompt.md Frontmatter die passenden case.yaml Felder, der prompt.md Body ist die Eingabeaufforderung und graders/*.md werden nach allen in case.yaml aufgelisteten Gradern hinzugefügt. Diese Felder existieren nur in case.yaml:

Feld	Zweck
`context.scaffold_script`	Ein Bash-Skript im Fallverzeichnis, das im leeren Arbeitsbereich vor Claude startet, um Fixture-Dateien oder ein Git-Repository zu erstellen. Es wird nur ausgeführt, wenn Sie `--scaffold` übergeben
`context.history_file`	Ein `.jsonl` Transkript im Fallverzeichnis zum Fortsetzen. Die Eingabeaufforderung des Falls wird zum nächsten Benutzer-Turn
`context.add_dirs`	Verzeichnisse innerhalb des Fallverzeichnisses, die Claude während des Durchlaufs lesen darf, schreibgeschützt gewährt
`execution.prompt`	Die Eingabeaufforderung, wenn Sie den ganzen Fall in `case.yaml` behalten und `prompt.md` weglassen
`graders`	Eine Liste von Gradern, jeder mit einem `name` plus die gleichen Schlüssel, die eine `graders/*.md` Datei in Frontmatter nimmt. Für `llm` Grader, legen Sie die Rubrik in `criteria`

Grader Frontmatter

Jede Grader-Datei unter graders/ nimmt diese Schlüssel in Frontmatter, plus die Optionen für seinen Typ. Der Name des Graders ist der Dateiname ohne .md:

Schlüssel	Standard	Zweck
`type`	erforderlich	Einer der Grader-Typen
`weight`	`1`	Relatives Gewicht im Score des Durchlaufs. Jede positive Zahl
`arm`	nicht gesetzt	`with-only` schließt den Grader aus der Bewertung in einem Zwei-Arm-Durchlauf aus; `both` erzwingt, dass ein `tool_used: Skill` Grader in beiden Arms bewertet wird

Was ein Grader ansehen kann

regex Grader nehmen ein target und llm Grader nehmen einen focus. Beide akzeptieren die gleichen Werte:

Wert	Was der Grader sieht
`last_message`	Claude’s endgültige Antwort-Text. Dies ist der Standard
`trace`	Die ganze Sitzung als JSON, eine Nachricht pro Zeile. Ein `regex` Grader sieht jede Nachricht; ein `llm` Judge sieht die ersten 12 und die letzten 12. Anführungszeichen und Zeilenumbrüche darin sind JSON-escaped, daher passt ein Regex `\"` anstelle von `"`
`files`	Die Liste der Pfade, die Claude während des Durchlaufs erstellt hat, einer pro Zeile. Nicht ihre Inhalte, und nicht Dateien, die ein Scaffold erstellt hat oder die Claude nur modifiziert hat
`{ source: file, path: <path> }`	Der Inhalt einer Datei im Arbeitsbereich nach dem Durchlauf. Verwenden Sie dies, um zu bewerten, was das Plugin produziert hat. Eine PNG-, JPEG-, GIF- oder WebP-Datei wird einem `llm` Judge als Bild angezeigt. Ein `llm` Judge weigert sich, andere Binärdateien wie `.pptx` oder PDF zu lesen; rendern Sie sie zu einem Bild oder schreiben Sie sie als Text aus und bewerten Sie das
`mock_calls`	Jeder Aufruf, den Claude an ein gemocktes MCP-Tool machte, mit seiner Eingabe und der Antwort des Mocks

Grader-Typen

Jeder Grader-Typ unten listet seine Optionen und wann er bestanden wird:

Typ	Optionen	Wird bestanden, wenn
`regex`	`pattern`, `flags`, `match`, `target`	Das JavaScript Regex `pattern` wird im Ziel gefunden. Setzen Sie `match: not_contains`, um Abwesenheit zu erfordern, oder `match: "count:N"`, um genau N Treffer zu erfordern. Legen Sie Groß-/Kleinschreibung-Unempfindlichkeit in `flags: i`; Inline `(?i)` wird nicht unterstützt
`tool_used`	`tool`, `input_match`, `min`, `max`	Die Anzahl der Aufrufe an `tool`, deren JSON-kodierte Eingabe das optionale `input_match` Regex passt, liegt zwischen `min`, Standard 1, und `max`, Standard unbegrenzt. Um zu bestätigen, dass ein Tool nie aufgerufen wurde, setzen Sie beide `min: 0` und `max: 0`
`tool_order`	`before`, `after`	Beide Tools wurden aufgerufen und der erste passende `before` Aufruf geht dem ersten passenden `after` Aufruf voraus. Jeder ist ein Tool-Name oder `{ tool, input_match }`
`file_exists`	`path`, `exists`	Eine Datei, die Claude erstellt hat, passt zum `path` Glob, oder keine mit `exists: false`. Nur Dateien, die während des Durchlaufs erstellt wurden, zählen
`llm`	`criteria`, `focus`	Ein Judge-Modell stimmt PASS auf die Rubrik in mindestens zwei von drei Stimmen ab. Im `.md` Layout ist der Datei-Body die Kriterien
`baseline`	`baseline_file`, `criteria`	Ein Judge findet, dass der Durchlauf die Kriterien mindestens so gut erfüllt wie das Referenz-Transkript bei `baseline_file`, ein `.jsonl` im Fallverzeichnis

Mock-Dateien

Eine <tool>.md Datei unter mocks/<server>/ beantwortet ein Tool. Sein Body ist das Tool-Ergebnis, mit {{input.<field>}} und {{file:fixtures/<name>}} Substitutionen. Sein Frontmatter akzeptiert diese Schlüssel:

Schlüssel	Standard	Zweck
`type`	`fixed`	`fixed` gibt den Body wie geschrieben zurück. `agent` behandelt den Body als Anweisungen für ein kleines Modell, das den Server für den Durchlauf spielt und frühere Aufrufe als Geschichte sieht
`expect`	nicht gesetzt	Eine Karte von gepunkteten Eingabe-Pfaden zu einem Typ-Namen wie `string`, `number`, `boolean`, `array` oder `object`, ein `/regex/`, ein Literal oder eine Liste erlaubter Literale. Ein Aufruf, der ihn verletzt, bricht den Durchlauf mit Score 0 ab und wird als `aborted` mit Server, Tool und Grund gemeldet
`error`	`false`	`fixed` nur. Geben Sie den Body als Tool-Fehler zurück
`abort_when`	nicht gesetzt	`agent` nur. Prosa, die die einzigen Bedingungen auflistet, unter denen der Agent den Durchlauf abbrechen darf

Zwei optionale Dateien sitzen neben den Tool-Dateien in einem Server-Verzeichnis:

_server.md: ein einzelner type: agent Mock, der mehrere Tools beantwortet, aufgelistet in seinem tools: Frontmatter-Schlüssel. Ein <tool>.md für das gleiche Tool hat Vorrang. Legen Sie einen expect: Guard auf das einzelne <tool>.md, nicht hier |
_tools.json: eine gespeicherte tools/list Antwort vom echten Server, daher tragen gemockte Tools ihre echten Beschreibungen und Eingabe-Schemas anstelle eines permissiven Platzhalters |

Ein Falls eigenes mocks/ Verzeichnis verwendet das gleiche Layout und überschreibt die Suite’s Mock-Datei für Datei.

Fehlerbehebung

Dies sind die Probleme, auf die Autoren am häufigsten stoßen, sortiert nach dem, was Sie sehen.

„plugin eval is currently in early access”

Ihr Build ist älter als die allgemeine Verfügbarkeit des Befehls. Führen Sie claude update aus und führen Sie den Befehl dann erneut in einer neuen Sitzung aus.

„plugin eval is currently unavailable”

Anthropic hat den Befehl serverseitig deaktiviert. Nichts auf Ihrem Computer schaltet ihn wieder ein; führen Sie claude update aus und versuchen Sie es später in einer neuen Sitzung erneut.

„is not a trusted plugin directory, and this run cannot stop to ask you about it”

Dies ist der erste Durchlauf gegen ein Verzeichnis, dem Claude Code noch nicht vertraut, und es kann Sie nicht fragen, da stdin oder stdout kein Terminal ist oder Sie --json übergeben haben. Führen Sie claude plugin eval <dir> einmal in einem Terminal aus und beantworten Sie die Eingabeaufforderung, oder übergeben Sie --trust-plugin, wenn Sie dem Code und der Suite des Plugins vertrauen. Siehe What a run can access.

„No eval cases found”

Es existiert kein <case>/prompt.md oder <case>/case.yaml unter dem geltenden Eval-Verzeichnis, oder Ihre --case- und --tag-Filter haben keinen Fall gefunden. Führen Sie den Befehl aus dem Plugin-Root aus, oder führen Sie claude plugin eval init aus, um eine Suite zu erstellen.

Die Baseline-Arm zeigt kein Plugin, oder Delta ist null

Wenn die Zusammenfassung keine W/OUT-Spalte hat oder der Fall mit „ablation requested but no plugin resolved” fehlschlägt, wurde kein Plugin für den Fall gefunden. Fügen Sie plugins: ["../.."] zum Fall hinzu und geben Sie den Pfad vom Fall-Verzeichnis zum Plugin-Verzeichnis an. Wenn das Plugin geladen wurde und Δ immer noch nahe bei null liegt, während Ihr tool_used: Skill-Grader fehlschlägt, ist das normalerweise ein echtes Ergebnis, was bedeutet, dass die description des Skills nicht auf die Formulierung der Eingabeaufforderung anspricht. Passen Sie die Beschreibung an und führen Sie die gleiche Suite erneut aus.

Alles bewertet null, obwohl die richtigen Dateien erstellt wurden

Ihre Grader zielen auf files, die Liste der erstellten Pfade, wenn Sie die Inhalte der Datei gemeint haben. Verwenden Sie { source: file, path: <path> } als target oder focus. Separat zählt file_exists nur Dateien, die während des Durchlaufs erstellt wurden, daher ist eine Datei, die das Gerüst erstellt hat oder die Claude nur bearbeitet hat, für sie unsichtbar; bewerten Sie ihren Inhalt, oder verwenden Sie tool_used auf Edit.

Ein Regex über die Trace stimmt nicht mit Text überein, den ich sehen kann

Das Standard-target ist last_message, nicht die Trace. Wenn Sie trace als Ziel verwenden, ist es JSON pro Zeile, daher erscheinen Anführungszeichen als \". Regexes verwenden JavaScript-Syntax, daher setzen Sie i in flags, anstatt (?i) zu schreiben.

Tools werden verweigert, MCP-Tools fehlen, oder Bash wird nicht ausgeführt

Alles über die schreibgeschützte Menge hinaus benötigt Ihre Genehmigung, wie z. B. --allow-tools Bash Write. Ihre persönlichen MCP-Server werden in einem Durchlauf nie geladen. Die eigenen Server des Plugins starten nicht, es sei denn, Sie aktivieren sie, und ihre Tools benötigen dann auch eine --allow-tools "mcp__plugin_<plugin>_<server>__*"-Genehmigung; ein simuliertes Tool benötigt keine.

Der Durchlauf beendet sich mit 1, aber die Ergebnisse sehen gut aus

Das Standard---threshold ist 1,0, daher beendet sich der Befehl mit 1, wenn ein Fall unter perfekt bewertet wird. Legen Sie einen Schwellenwert fest, der Ihrem Standard entspricht. Exit 1 deckt auch eine Fall-Datei ab, die nicht geladen werden konnte, was auf stderr über der Tabelle gemeldet wird.

„—json output path must end in .json”

Sie haben das Ziel nach --json eingegeben, daher wurde es als Ausgabepfad gelesen. Geben Sie das Ziel zuerst an, wie in claude plugin eval . --json, oder geben Sie --json einen expliziten .json-Pfad.

Ein Grader zeigt passed: false unter einem Durchlauf, der 1,0 bewertet

Dieser Grader ist absichtlich von der Bewertung in einem Zwei-Arm-Durchlauf ausgeschlossen, und sein scored-Feld ist false. Siehe Compare against a no-plugin baseline.

Durchläufe schlagen mit einem Nutzungslimit- oder Rate-Limit-Fehler in der Mitte fehl

Wenn Ihr Konto während der Ausführung einer Suite das Nutzungslimit des Plans oder ein API-Rate-Limit erreicht, endet jeder spätere Durchlauf mit diesem Fehler, wird auf das bewertet, was er produziert hat, und bewertet normalerweise 0. Die Suite wird trotzdem beendet und ist nicht als partial gekennzeichnet, daher kann das Ergebnis wie eine Regression aussehen. Überprüfen Sie die NOTES-Spalte oder cases[].arms.with[].error im JSON auf die Limit-Nachricht, bevor Sie den Bewertungen vertrauen, und führen Sie dann erneut aus, nachdem das Limit zurückgesetzt wurde, mit --runs 1 oder einem --case-Filter, wenn Sie darunter bleiben müssen.

Durchläufe überschreiten das Zeitlimit oder erreichen die Obergrenze für Durchläufe

Die Standardwerte sind 10 Durchläufe und 300 Sekunden. Erhöhen Sie max_turns und timeout_seconds im Fall für Aufgaben, die mehr benötigen, und verwenden Sie --max-cost-usd als Kostendeckel anstelle von engen Pro-Durchlauf-Limits.

Siehe auch

Plugins erstellen: bauen Sie das Plugin, das Sie testen, und laden Sie es mit --plugin-dir während der Entwicklung
Plugins-Referenz: die plugin eval und plugin eval init Befehlseinträge und der Manifest’s experimental.evals Schlüssel
Skills: wie die description eines Skills entscheidet, wann Claude ihn aufruft, was das ist, was ein Fall, der überprüft, ob der Skill auslöst, misst
Sandboxing: die OS-Level Sandbox, die angewendet wird, wenn Sie Bash einem Durchlauf gewähren
Erstellen und verteilen Sie einen Plugin-Marketplace: veröffentlichen Sie das Plugin, sobald seine Suite bestanden wird

​Anforderungen

​Wie ein Eval-Durchlauf funktioniert

​Was in einem Durchlauf passiert

​Wie ein Fall bewertet wird

​Die Baseline ohne Plugin

​Erstellen Sie Ihre erste Eval-Suite

​Fälle schreiben und verfeinern

​Schreiben Sie einen Fall von Hand

​Legen Sie Durchlauf-Limits und Tools in prompt.md fest

​Wählen Sie Grader und gewichten Sie sie

​Wählen Sie Grader, die ein stabiles Signal geben

​Bewerten Sie gegen die Baseline ohne Plugin

​Verwenden Sie ein anderes Eval-Verzeichnis

​Richten Sie Fixtures und Mocks ein

​Säen Sie den Arbeitsbereich oder die Konversation

​Mock MCP Server

​Wiedergeben Sie Agent-Mock-Antworten

​Führen Sie Evals aus

​Wählen Sie aus, was zu evaluieren ist

​Gewähren Sie Tools

​Befehlsoptionen

​Führen Sie Evals in CI aus

​Lesen Sie die Ergebnisse

​HTML-Bericht

​JSON-Ergebnis

​Was ein Durchlauf zugreifen kann

​Vertrauen Sie dem Plugin-Verzeichnis

​Wie Durchläufe isoliert sind

​Eval-Suite-Referenz

​prompt.md Frontmatter

​case.yaml Felder

​Grader Frontmatter

​Was ein Grader ansehen kann

​Grader-Typen

​Mock-Dateien

​Fehlerbehebung

​„plugin eval is currently in early access”

​„plugin eval is currently unavailable”

​„is not a trusted plugin directory, and this run cannot stop to ask you about it”

​„No eval cases found”

​Die Baseline-Arm zeigt kein Plugin, oder Delta ist null

​Alles bewertet null, obwohl die richtigen Dateien erstellt wurden

​Ein Regex über die Trace stimmt nicht mit Text überein, den ich sehen kann

​Tools werden verweigert, MCP-Tools fehlen, oder Bash wird nicht ausgeführt

​Der Durchlauf beendet sich mit 1, aber die Ergebnisse sehen gut aus

​„—json output path must end in .json”

​Ein Grader zeigt passed: false unter einem Durchlauf, der 1,0 bewertet

​Durchläufe schlagen mit einem Nutzungslimit- oder Rate-Limit-Fehler in der Mitte fehl

​Durchläufe überschreiten das Zeitlimit oder erreichen die Obergrenze für Durchläufe

​Siehe auch

Anforderungen

Wie ein Eval-Durchlauf funktioniert

Was in einem Durchlauf passiert

Wie ein Fall bewertet wird

Die Baseline ohne Plugin

Erstellen Sie Ihre erste Eval-Suite

Fälle schreiben und verfeinern

Schreiben Sie einen Fall von Hand

Legen Sie Durchlauf-Limits und Tools in prompt.md fest

Wählen Sie Grader und gewichten Sie sie

Wählen Sie Grader, die ein stabiles Signal geben

Bewerten Sie gegen die Baseline ohne Plugin

Verwenden Sie ein anderes Eval-Verzeichnis

Richten Sie Fixtures und Mocks ein

Säen Sie den Arbeitsbereich oder die Konversation

Mock MCP Server

Wiedergeben Sie Agent-Mock-Antworten

Führen Sie Evals aus

Wählen Sie aus, was zu evaluieren ist

Gewähren Sie Tools

Befehlsoptionen

Führen Sie Evals in CI aus

Lesen Sie die Ergebnisse

HTML-Bericht

JSON-Ergebnis

Was ein Durchlauf zugreifen kann

Vertrauen Sie dem Plugin-Verzeichnis

Wie Durchläufe isoliert sind

Eval-Suite-Referenz

prompt.md Frontmatter

case.yaml Felder

Grader Frontmatter

Was ein Grader ansehen kann

Grader-Typen

Mock-Dateien

Fehlerbehebung

„plugin eval is currently in early access”

„plugin eval is currently unavailable”

„is not a trusted plugin directory, and this run cannot stop to ask you about it”

„No eval cases found”

Die Baseline-Arm zeigt kein Plugin, oder Delta ist null

Alles bewertet null, obwohl die richtigen Dateien erstellt wurden

Ein Regex über die Trace stimmt nicht mit Text überein, den ich sehen kann

Tools werden verweigert, MCP-Tools fehlen, oder Bash wird nicht ausgeführt

Der Durchlauf beendet sich mit 1, aber die Ergebnisse sehen gut aus

„—json output path must end in .json”

Ein Grader zeigt passed: false unter einem Durchlauf, der 1,0 bewertet

Durchläufe schlagen mit einem Nutzungslimit- oder Rate-Limit-Fehler in der Mitte fehl

Durchläufe überschreiten das Zeitlimit oder erreichen die Obergrenze für Durchläufe

Siehe auch