Тестирование plugins с помощью evals

Напишите eval-кейсы для вашего Claude Code plugin, запустите их с помощью claude plugin eval, оцените результаты, сравните с базовым вариантом без plugin и установите ограничение CI на основе оценки.

Команда claude plugin eval запускает ваш plugin на наборе тестовых кейсов и оценивает результаты. Каждый кейс — это реалистичный запрос плюс один или несколько graders. Grader — это проверка pass/fail того, что произвел Claude, например регулярное выражение для ответа, был ли вызван конкретный инструмент или рубрика, которую вторая модель оценивает в ответе.

Вам не нужно писать набор вручную; claude plugin eval init спрашивает вас о вашем plugin, предлагает кейсы и graders, пробует их и записывает файлы, и вы можете попросить Claude сделать то же самое из уже открытой сессии.

Используйте evals для:

• Измерения того, насколько надежно ваш plugin направляет Claude к правильному результату
• Выявления регрессий при изменении plugin или выпуске новой модели
• Определения того, что plugin вносит в сравнении с отсутствием plugin

Эта страница предназначена для авторов plugin и skills, у которых есть работающий plugin и которые хотят протестировать его поведение, а также для команд, которые ограничивают изменения plugin в CI. Формат кейса отличается от файла evals/evals.json, который использует skill-creator plugin. Чтобы создать plugin, см. Create a plugin; чтобы проверить файлы plugin на синтаксические и схемные ошибки, а не его поведение, используйте claude plugin validate.

Требования

Для запуска plugin evals вам нужно:

• Claude Code v2.1.269 или позже. Запустите claude --version для проверки и claude update для обновления.
• Директория plugin с манифестом plugin.json или .claude-plugin/plugin.json, или skills-directory plugin.
• Та же аутентификация и поставщик модели, которые используют ваши обычные Claude Code сессии. Запуски eval, graders, оцениваемые judge, и claude plugin eval init вызывают модель с вашими учетными данными, поэтому они учитываются в пределах использования вашего плана или счета API. Когда команда сообщает стоимость, цифра — это оценка по прейскуранту этих вызовов.

Как работает запуск eval

Eval suite находится в директории под названием evals/ внутри вашего plugin, расположенной так, как показано в Write and refine cases. Каждый case — это собственная поддиректория с prompt и одним или несколькими graders. Prompt — это что-то, что может напечатать человек, использующий ваш plugin, например запрос, который должен обработать один из его skills.

Что происходит во время запуска

Для каждого запуска case Claude Code запускает свежую, изолированную неинтерактивную сессию только с вашим plugin, отправляет prompt и позволяет Claude работать, пока он не закончит или не достигнет лимита turn или времени case. Затем каждый grader проверяет финальный ответ, полный транскрипт или файл, созданный Claude, и проходит или не проходит.

Как оценивается case

Один запуск недетерминированного агента говорит вам мало, поэтому каждый case по умолчанию запускается три раза. Оценка запуска — это доля его graders, которые прошли, взвешенная, если вы установили веса, и оценка case — это среднее значение по его запускам. Case проходит, когда его оценка соответствует --threshold, по умолчанию 1.0. При вызовах модели suite создает примерно cases × runs запусков агента с plugin и столько же для no-plugin baseline, плюс три коротких вызова judge на llm или baseline grader на запуск.

The no-plugin baseline

Высокая оценка сама по себе не говорит вам, что plugin помог, потому что Claude может работать так же хорошо без него. Чтобы разделить эти два, запуски каждого case по умолчанию повторяются без загруженного plugin, и вы получаете две оценки, WITH и W/OUT. Их разница, Δ, — это то, что внес plugin. Если case оценивается в 1.0 как с plugin, так и без него, plugin не является тем, что заставило его пройти.

Два набора запусков называются with-arm и without-arm; Score against the no-plugin baseline охватывает, как graders оцениваются в обоих arms и как отключить baseline.

Создайте свой первый eval suite

Это пошаговое руководство написания одного кейса для вашего собственного plugin, его запуска и чтения результата. Перед началом убедитесь, что у вас есть:

• Claude Code v2.1.269 или позже и другие требования
• Терминал, открытый в корневой директории вашего plugin, той, которая содержит plugin.json или .claude-plugin/plugin.json
• Один skill в plugin, который вы хотите протестировать, и запрос, который пользователь должен напечатать, чтобы его запустить

claude plugin eval init

claude plugin eval .

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

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

Написание и уточнение кейсов

Кейсы, которые пишет claude plugin eval init, — это простые файлы, которые вы можете открыть, изменить и добавить. Кейс — это директория под директорией eval plugin, которая содержит prompt.md, case.yaml или оба. Чтобы сгруппировать кейсы, вложите их в директорию, которая сама не является кейсом; все, что находится внутри директории кейса, такое как graders/ и файлы fixtures, принадлежит этому кейсу.

Это макет, который пишет claude plugin eval init, и тот, который нужно использовать для новых suites. eval suite reference содержит полное дерево, включая mocks и результаты:

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

Напишите кейс вручную

Рекомендуемый путь — это написание кейсов Claude с помощью claude plugin eval init. Чтобы написать один самостоятельно, начните с пустого шаблона. Следующая команда пишет кейс с именем first-case с placeholder prompt.md и одним placeholder grader и ничего не запускает:

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

В prompt.md вы пишете сообщение, которое Claude получает в каждом запуске, и устанавливаете лимиты запуска и инструменты, которые кейс может использовать в его frontmatter. Откройте evals/first-case/prompt.md и замените placeholder body на запрос, который должен обработать один из ваших skills, сформулированный так, как пользователь его напечатает, а не называя skill. Этот пример предназначен для skill, который составляет сообщения коммитов; используйте свой собственный запрос:

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

Каждый запуск начинается в пустой рабочей директории, поэтому поместите все, что нужно для задачи, в сам prompt, или установите workspace первым. Полный список frontmatter полей охватывает модель, timeout, теги и переменные окружения.

Каждый файл под graders/ — это одна проверка, применяемая после запуска. Откройте evals/first-case/graders/criteria.md и замените placeholder на рубрику для judge модели, написанную как конкретные условия PASS и FAIL:

---
type: llm
---

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

Затем добавьте второй grader, который проверяет, является ли ваш skill тем, что произвел ответ. Создайте evals/first-case/graders/skill-fired.md, заменив your-skill-name на имя директории skill под skills/, которое является именем, по которому Claude его вызывает:

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

Это проходит, когда Claude вызвал этот skill хотя бы один раз во время запуска, включая его форму с пространством имен plugin-name:skill-name.

Grader types перечисляет другие доступные проверки, такие как сопоставление регулярного выражения или подтверждение создания файла.

С обоими сохраненными файлами запустите кейс так, как это делает quickstart, с claude plugin eval . из корня plugin.

Установите лимиты запуска и инструменты в prompt.md

Установите max_turns, timeout_seconds, model, tags кейса и allowed_tools, которые он может использовать в frontmatter prompt.md; справочник prompt.md frontmatter перечисляет каждое поле и его значение по умолчанию.

Claude получает body ровно так, как вы его написали. Упоминания @path в нем не расширяются в вложения файлов, поэтому, если Claude нужно прочитать файл, предоставьте инструмент для него в allowed_tools.

Выберите и взвесьте graders

Frontmatter grader устанавливает его type и опционально weight, который делает его более значимым в оценке запуска, и arm, который контролирует, как он оценивается в сравнении с базовым вариантом. Из шести типов regex, tool_used, tool_order и file_exists вычисляются из транскрипта и файлов и ничего не стоят, в то время как llm и baseline вызывают judge модель и добавляют к стоимости запуска.

Нет custom-code graders.

Grader types перечисляет опции каждого типа и условие прохождения, и what a grader can look at перечисляет значения, которые принимают target и focus.

Judge для llm и baseline graders по умолчанию — это небольшая быстрая модель. Передайте --judge-model sonnet или полный ID модели, чтобы использовать более сильную для нюансированных рубрик.

Выберите graders, которые дают стабильный сигнал

llm grader спрашивает модель о вердикте, поэтому его ответ может отличаться между запусками, и он отличается больше, чем длиннее текст, который ему нужно прочитать. Эти привычки держат оценки suite достаточно стабильными, чтобы им доверять:

• Для длинного вывода, такого как сгенерированный файл, оцените его с помощью regex grader над содержимым файла, который проверяет весь файл одинаково каждый раз. Держите llm graders для коротких выводов с рубриками, написанными как конкретные условия PASS и FAIL.
• Дайте каждому кейсу один grader на результат, такой как финальное сообщение или произведенный файл, и один на то, как Claude туда попал, такой как tool_used или tool_order. Вместе они говорят вам как то, был ли ответ правильным, так и то, произвел ли ваш plugin его.
• Если grader tool_used: Skill кейса проходит, но Δ отрицательное, подозревайте judge перед plugin. Небольшая judge модель может отметить правильный ответ как неправильный, потому что он отформатирован иначе, чем описывает рубрика. Перезапустите с --judge-model sonnet и затяните рубрику, чтобы форматирование не решало вердикт.
• Чтобы проверить, что сборка или тест прошли внутри запуска, попросите Claude запустить его и написать результат в файл, оцените этот файл и утверждайте, что команда запустилась с помощью tool_used grader, чей input_match называет команду.

Оцените в сравнении с базовым вариантом без plugin

Когда plugin находится под тестом, каждый кейс по умолчанию запускается в двух arms. With-arm — это его запуски с загруженным plugin, а without-arm — это то же количество запусков без plugin вообще. Сводка и отчет показывают обе оценки и Δ, оценку with-arm минус оценку without-arm.

Передайте --ablation none, чтобы запустить только with-arm, что вдвое снижает стоимость, когда вам не нужно сравнение, например при повторении graders.

В двухarm запуске некоторые graders сообщаются с scored: false. Проверка типа "skill был вызван" никогда не может пройти без plugin, поэтому подсчет ее толкнул бы without-arm к нулю и завысил бы Δ. Чтобы держать два arms сравнимыми, Claude Code исключает такие graders из оценки в обоих arms и сообщает их в with-arm только как индикаторы pass/fail. Это включает:

• Каждый tool_used grader, чей tool — это Skill
• Каждый regex grader с target: mock_calls и каждый llm grader с focus: mock_calls, когда каждый mocked server в кейсе — это один, который объявляет ваш plugin
• Любой grader, который вы отметили arm: with-only

Три параметра изменяют это исключение:

• Каждый grader исключен: если каждый grader в кейсе — это один из них, они вместо этого оцениваются нормально, так как не осталось бы ничего для оценки.
• arm: both: установите arm: both на grader, чтобы оценить его в обоих arms независимо, что вам нужно для проверки "не должен вызывать skill" с min: 0 и max: 0.
• --ablation none: под --ablation none ничего не исключается, поэтому одна и та же suite может производить разную абсолютную оценку в двух режимах.

Используйте другую директорию eval

Если evals/ уже занята другим инструментом, держите suite в другой директории. Вы можете записать эту директорию в plugin.json plugin, чтобы каждый запуск и каждый сотрудник использовали ее, или передайте ее в командной строке для одного запуска:

• В plugin.json: добавьте "experimental": { "evals": "quality/evals" }.
• В командной строке: передайте --eval-dir quality/evals как claude plugin eval, так и claude plugin eval init.

Если вы установите оба, используется директория флага. Дайте относительный путь из простых имен директорий, таких как qa или quality/evals. Абсолютный путь или содержащий .. не принимается: как значение флага это ошибка, в то время как неиспользуемое значение манифеста выводит строку Warning: и запуск использует evals/ вместо этого. Кейсы, результаты и вывод init все перемещаются в эту директорию.

Установите fixtures и mocks

Кейс может нуждаться в большем, чем prompt: файлы или git репозиторий в workspace, более ранний разговор для продолжения или ответы от MCP серверов, с которыми разговаривает ваш plugin. Каждый из них установлен рядом с кейсом, чтобы запуски оставались повторяемыми.

Заполните workspace или разговор

Каждый запуск начинается в пустом workspace. Когда кейс нуждается в большем, чем prompt, добавьте case.yaml рядом с prompt.md с блоком context:

• Файлы fixtures или git репозиторий: напишите Bash скрипт в директории кейса и назовите его в context.scaffold_script. Скрипт запускается как вы, вне sandbox агента, и только когда вы передаете --scaffold, поэтому передавайте этот флаг только для suites, которые вы или ваша организация написали.
• Более ранний разговор для продолжения: сохраните транскрипт как файл .jsonl и назовите его в context.history_file, и prompt кейса становится следующим ходом пользователя.
• Директории fixtures, которые Claude может читать во время запуска: перечислите их в context.add_dirs.

case.yaml также нуждается в schema_version: "1.1" и name; справочник case.yaml fields содержит полный список.

Этот case.yaml заполняет workspace из скрипта и позволяет Claude читать fixtures из директории resources/:

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

Mock MCP серверы

Вы можете оценить plugin, чьи skills вызывают MCP инструменты без реального сервиса позади них. Поместите один Markdown файл на инструмент под evals/mocks/<server>/<tool>.md для всей suite или под собственную директорию mocks/ кейса для одного кейса, где <server> — это имя сервера в MCP конфигурации вашего plugin.

Запуск никогда не запускает реальные MCP серверы вашего plugin, если вы не попросите. Claude Code регистрирует substitute server под каждым именем сервера. Инструменты с файлом mock отвечают из него и разрешены без гранта --allow-tools, и инструмент без файла mock недоступен Claude. Сервер без mocks вообще появляется в строке прогресса кейса как plugin_<plugin>_<server>[not started: no mock].

Body файла — это то, что инструмент возвращает Claude. Этот mock стоит на месте инструмента create_issue на сервере с именем tracker, проверяет input, который Claude отправляет, и эхо-возвращает заголовок. Сохраните его как evals/mocks/tracker/create_issue.md:

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

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

Body файла mock и frontmatter принимают эти опции:

• Подстановки: вставьте поля из input вызова с {{input.<field>}} и содержимое файла fixture рядом с mock с {{file:fixtures/{input.<field>}.json}}.
• expect:: блок expect: охраняет input. Если вызов нарушает его, запуск прерывается с оценкой 0 и записывает почему, поэтому кейс может утверждать, что ваш plugin попросил сервер сделать.
• error: true: установите error: true, чтобы вернуть body как ошибку инструмента вместо этого.
• type: agent: установите type: agent, чтобы иметь небольшую модель ответить как сервер из инструкций в body.

Справочник mock file reference перечисляет каждый ключ и файлы _server.md и _tools.json.

Чтобы оценить сами вызовы, укажите grader на target: mock_calls.

Чтобы запустить против реальных MCP серверов plugin вместо этого, передайте один из этих флагов. В любом случае эти процессы запускаются как вы, вне sandbox запуска, и их инструменты нуждаются в гранте --allow-tools:

• --allow-real-servers: запустите реальный процесс для каждого сервера, который вы не замокировали, и продолжайте отвечать замокированные инструменты из их файлов
• --mocks off: игнорируйте mocks/ полностью и запустите каждый сервер, который объявляет plugin

Воспроизведите ответы agent mock

type: agent mock отвечает с вызовом --judge-model, поэтому его вывод варьируется между запусками и изменяется, если вы измените judge. Когда запуск завершается без ошибки или прерывания, Claude Code сохраняет каждый ответ, который дал agent mock, под директорией результатов в mock-recordings/.

Откройте ADOPT.txt там, чтобы увидеть каждую запись и директорию .replay/<server>/, чтобы скопировать ее в, рядом с mock, который ее произвел. После того как вы скопируете запись туда, более поздние запуски отвечают на идентичный вызов из нее без вызова модели. Зафиксируйте mocks/.replay/ вместе с остальной частью mocks/, чтобы запуски CI были повторяемыми.

Запустите evals

Как только suite существует, claude plugin eval запускает его. Вы выбираете, какой plugin и кейсы запускаются с аргументом target, предоставляете любые инструменты, которые кейсы нуждаются за пределами набора только для чтения с --allow-tools, и контролируете количество запусков, модели, стоимость и вывод с другими опциями.

Выберите, что оценивать

Большую часть времени вы запускаете claude plugin eval . из корня plugin, который запускает каждый кейс в suite с загруженным plugin, который вы разрабатываете. Чтобы запустить один файл кейса или оценить установленный plugin вместо того, который вы разрабатываете, передайте другой target:

Добавьте --case <glob> для фильтрации по имени кейса и --tag <tag> для сохранения кейсов с любыми из данных тегов.

Поместите target перед --tag, --allow-tools и --json. Первые два принимают список и --json принимает опциональный путь, поэтому каждый из них читает target, который следует как его собственное значение.

Предоставьте инструменты

Запуски никогда не останавливаются, чтобы попросить разрешение. Встроенные инструменты, которые нуждаются в гранте, который вы не дали, такие как Bash, Write, Edit, WebFetch и WebSearch, удаляются из сессии, поэтому Claude не может их вызывать вообще.

Запуск позволяет только инструменты только для чтения, которые кейс перечисляет в allowed_tools, из Read, Glob, Grep, NotebookRead, Skill, AskUserQuestion, Agent, TodoWrite и инструменты задач TaskCreate, TaskGet, TaskList, TaskUpdate и TaskStop, плюс все, что вы предоставляете с --allow-tools. Этот грант применяется к каждому кейсу в запуске. Чтобы позволить кейсам использовать Bash, Write, Edit, WebFetch или WebSearch, предоставьте их сами:

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

Когда кейс попросил инструмент, который вы не предоставили, вывод прогресса перечисляет его как not granted. Инструменты на замокированном MCP сервере не нуждаются в гранте. Инструменты на реальном plugin MCP сервере нуждаются как в запущенном сервере, с --allow-real-servers или --mocks off, так и в гранте по имени, такой как --allow-tools "mcp__plugin_my-plugin_github__*"; инструменты MCP plugin названы mcp__plugin_<plugin>_<server>__<tool>.

Когда вы предоставляете Bash в любой форме, каждая команда запускается под Claude Code OS-level sandbox. Записи ограничены workspace запуска, ваша домашняя директория и конфигурация Claude Code нечитаемы, и доступ в сеть ограничен доменами, которые вы предоставляете с --allow-tools "WebFetch(domain:example.com)". Если вы предоставляете Bash или PowerShell на машине без backend sandbox, Claude Code отказывает каждому запуску вместо его запуска без ограничений, и кейс показывает ошибку запуска и обычно оценивается в 0. Native Windows не имеет backend, поэтому запустите suites, предоставляющие shell, под WSL2; на Linux сначала установите bubblewrap и socat. См. sandboxing prerequisites.

Опции команды

Эта таблица охватывает опции для количества запусков, моделей, оценки, стоимости, грантов инструментов, mocks и вывода. Запустите claude plugin eval --help для полного списка, который также включает --case, --tag, --eval-dir, --no-scaffold, --report и --verbose.

Запустите evals в CI

В вашей CI работе запустите suite с --json, чтобы написать результат для архивирования, и не пройдите сборку на exit коде. Передайте --trust-plugin, чтобы работа никогда не ждала на первом запросе доверия, закрепите обе модели, чтобы оценки были сравнимы со временем, держите отчет локально и установите потолок стоимости как верхний лимит:

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

Exit код работы говорит вам, что произошло:

Проблемы с написанием или публикацией HTML отчета никогда не изменяют exit код.

Чтобы увидеть, почему кейс оценен низко, запустите его локально без --json, чтобы строки прогресса per-run и grader печатались.

CI runner также нуждается в этом на месте:

• Установка и учетные данные: CI runner нуждается в Claude Code установке и учетных данных в окружении, такие как ANTHROPIC_API_KEY.
• Доверие: без --trust-plugin, работа, чья директория checkout Claude Code еще не доверяет, нуждается в первом запросе доверия, и запуск, который не может спросить, отказан с exit 1.
• init в CI: claude plugin eval init нуждается в терминале, чтобы задать вам его вопросы; в CI запустите claude plugin eval init --bare <name>, чтобы получить пустой шаблон.

Чтобы держать стоимости предсказуемыми, дайте быстрым every-change suites только graders, которые не вызывают judge, используйте --ablation none, где вам не нужно Δ, и оставьте partial: true документы и запуски с skippedPaidGraders вне любого тренда, который вы составляете.

Прочитайте результаты

Каждый запуск с по крайней мере одним кейсом пишет директорию results/<timestamp>/ внутри директории eval, содержащую aggregate-result.json и report.html. Для path target, который находится под plugin; для plugin, который вы назвали, это под вашей текущей директорией, как показывает target table. Таблица сводки, JSON и отчет все отображают одни и те же данные результата.

HTML отчет

report.html — это один самодостаточный файл, который не делает внешних запросов, поэтому вы можете прикрепить его к CI работе или открыть его с диска. Это пример верхней части отчета для запуска трёхкейсного набора с --threshold 0.8; показанная стоимость — это оценка по прейскуранту и варьируется в зависимости от модели и количества кейсов:

Читайте его сверху вниз:

• Строка вердикта и плитки отвечают на вопрос, помог ли plugin по всему набору. Suite score — это среднее значение per-case with-plugin оценок, Ablation Δ — это то, насколько это находится выше или ниже baseline score, и Cases считает, сколько соответствовали threshold. Perfect runs — это доля with-plugin запусков, где каждый grader прошёл.
• Каждая карточка кейса показывает собственный Δ кейса и with-plugin оценку, с отметкой на полосе в threshold. Кейс, чей Δ отрицательный, получает красный левый край, поэтому регрессии выделяются при прокрутке.
• Внутри кейса with-plugin запуски идут первыми, а baseline запуски после. Каждый запуск перечисляет своих graders с чипом pass или fail. Неудачный grader уже развёрнут с его объяснением, и llm grader также показывает голоса судьи и доказательства, которые ему были показаны, что является местом, где вы узнаёте, почему запуск получил низкую оценку. Graders, которые не учитываются в оценке, такие как tool_used: Skill, несут plugin-fired indicator значок.
• Prompt и Graders, ниже запусков, показывают prompt кейса и rubric или pattern каждого grader, поэтому кто-то, читающий отчет без набора, может увидеть, что было запрошено и что считалось хорошим.

Если вы вошли с подпиской claude.ai и artifacts доступны для вашего аккаунта, Claude Code также публикует отчет как приватный artifact и печатает Published: <url>. Передайте --no-publish, чтобы держать его локально. Если нет строки Published:, такой как с API-key аутентификацией, локальный файл — это отчет.

Запуск, который Claude Code сессия запустила, такой как когда вы просите Claude запустить suite для вас, также остается локально, и его строка Report: говорит kept local. Добавьте --publish-report к этой команде, чтобы опубликовать его.

JSON результат

aggregate-result.json и --json вывод — это версионированный документ с schemaVersion: 1 для CI скриптов для парсинга. Имена полей — это camelCase и новые поля добавляются без переименования существующих, поэтому напишите ваш скрипт, чтобы игнорировать поля, которые он не признает.

Это поля, которые скрипт gating обычно читает. Документ также несет конфигурацию suite, каждое определение grader и результаты grader на запуск с объяснениями и доказательствами:

Что может получить доступ запуск

claude plugin eval загружает skills, hooks и agents целевого плагина и запускает его набор тестов на вашей машине от вашего имени. Указание на плагин — это то же самое решение о доверии, что и claude --plugin-dir, поэтому оценивайте только плагины, которым вы доверяете.

Изоляция, описанная в этом разделе, ограничивает то, что может достичь тестируемый агент; это не граница против собственного кода плагина, и набор, который проходит, ничего не говорит о том, безопасен ли плагин.

Доверяйте директории плагина

При первом запуске claude plugin eval для директории Claude Code спрашивает Trust this plugin directory? перед загрузкой чего-либо из неё, если вы уже не приняли приглашение доверия там в интерактивном сеансе claude. Внутри репозитория git ответ «да» доверяет всему репозиторию, также для интерактивных сеансов. Когда stdin или stdout не является терминалом, под --json, или когда переменная окружения CI установлена на значение true, такое как true, запуск не может спросить и отказывается с выходом 1; передайте --trust-plugin, чтобы утвердить доверие самостоятельно, только для плагина, который вы бы запустили на своей машине. Цель, которую вы называете, а не даёте как путь, то есть установленный плагин или плагин из директории skills, пропускает приглашение.

Некоторые части плагина и набора запускаются только при передаче их флага для этого запуска:

• scaffold_script случая с --scaffold
• Tools за пределами набора только для чтения с --allow-tools
• Реальные MCP серверы плагина с --allow-real-servers или --mocks off

allowed_tools случая и собственный frontmatter allowed-tools skill не могут расширить ни один из них.

Когда плагин поставляется с hooks, которые вы не писали, или вы запускаете его реальные MCP серверы, рассматривайте его оценки как рекомендательные, если вы не запустили его в изолированной среде, такой как контейнер или CI runner, поскольку hooks и серверы работают вне sandbox агента и могут изменять файлы, которые читают грейдеры.

Как запуски изолированы

Каждый запуск получает одноразовую домашнюю директорию, рабочую директорию и конфигурацию Claude Code, и тестируемый агент работает там как дочерний процесс claude -p с загруженным только вашим плагином. Помните об этих последствиях при написании случаев:

• Ничего личного или на уровне проекта не загружается. Ваши пользовательские настройки, hooks, файлы CLAUDE.md, MCP серверы, другие установленные плагины, память и skills отсутствуют, и никакой проект-scoped .claude/ или .mcp.json выше sandbox не читается. Большая часть вашей shell среды также скрывается; только allowlist и переменные EVAL_* достигают запуска. Если плагину нужна настройка, поставляйте её в плагине, создавайте её в scaffold_script или передавайте переменные EVAL_*.
• Управляемая политика всё ещё может ограничить запуск. Ограничения в управляемых настройках, которые администратор развернул на машине, применяются внутри запуска, поэтому результаты на управляемой машине могут отличаться от неуправляемой на эту политику.
• Инструмент Artifact отключён. Skill, который публикует artifact, может быть оценён только на основе того, что он производит до этого шага.
• Определения случаев скрыты от агента. Запуск не может читать директорию eval, поэтому Claude не может видеть приглашение случая, его грейдеры или соседние случаи.
• Нет сетевого sandbox вне shell команд. Shell команды, которые вы предоставляете, работают под правилами сети sandbox. Грант WebFetch(domain:…) достигает этого домена напрямую, и собственные hooks плагина и любые реальные MCP серверы, которые вы запускаете, могут достичь любого хоста.

Справочник набора тестов

Всё, что может содержать набор тестов, находится в директории evals/ плагина, если вы не настроили другую. Это дерево показывает каждый файл, который claude plugin eval читает или записывает там; для существования случая требуется только prompt.md или case.yaml:

evals/
├── <case>/                        # одна директория на случай; вложите в директорию без случаев для группировки
│   ├── prompt.md                  # frontmatter: поля case и run; тело: подсказка
│   ├── case.yaml                  # опционально: поля context.*, или весь случай в одном файле
│   ├── graders/
│   │   └── <name>.md              # один оценщик на файл; frontmatter: тип и опции; тело: рубрика
│   ├── mocks/                     # опционально: мокирование только для этого случая, такой же макет как ниже
│   └── <fixtures, scripts, transcripts referenced by case.yaml>
├── mocks/                         # опционально: мокирование на уровне набора тестов для MCP
│   ├── <server>/
│   │   ├── <tool>.md              # один мокированный инструмент; тело: результат инструмента
│   │   ├── _server.md             # опционально: один агент, который отвечает на несколько инструментов
│   │   ├── _tools.json            # опционально: сохранённый ответ tools/list для реальных описаний и схем
│   │   └── fixtures/              # файлы, вставленные с {{file:fixtures/...}}
│   └── .replay/<server>/          # принятые записи agent-mock, отвеченные без вызова модели
└── results/<timestamp>/           # записано каждым запуском; добавьте results/ в .gitignore
    ├── aggregate-result.json
    ├── report.html
    └── mock-recordings/           # ответы agent-mock из чистых запусков, с ADOPT.txt

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:. Когда оба файла существуют, frontmatter prompt.md переопределяет совпадающие поля case.yaml, тело prompt.md является подсказкой, и graders/*.md добавляются после любых оценщиков, указанных в case.yaml.

Эти поля существуют только в case.yaml:

Frontmatter оценщика

Каждый файл оценщика под graders/ принимает эти ключи в frontmatter, плюс опции для его типа. Имя оценщика — это имя файла без .md:

Что может видеть оценщик

Оценщики regex принимают target и оценщики llm принимают focus. Оба принимают одни и те же значения:

Типы оценщиков

Каждый тип оценщика ниже перечисляет его опции и когда он проходит:

Файлы мока

Файл <tool>.md под mocks/<server>/ отвечает на один инструмент. Его тело — это результат инструмента, с подстановками {{input.<field>}} и {{file:fixtures/<name>}}. Его frontmatter принимает эти ключи:

Два опциональных файла находятся рядом с файлами инструментов в директории сервера:

• _server.md: один мок type: agent, который отвечает на несколько инструментов, перечисленных в его ключе frontmatter tools:. <tool>.md для того же инструмента имеет приоритет. Поместите охрану expect: на отдельный <tool>.md, а не здесь
• _tools.json: сохранённый ответ tools/list от реального сервера, поэтому мокированные инструменты несут свои реальные описания и входные схемы вместо разрешающего заполнителя

Собственная директория mocks/ случая использует тот же макет и переопределяет файлы мока набора тестов файл за файлом.

Troubleshooting

Это проблемы, которые авторы встречают чаще всего, ключевые на том, что вы видите.

"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, или переменная окружения CI установлена на значение true, такое как true. Запустите claude plugin eval <dir> один раз в терминале и ответьте на запрос, или передайте --trust-plugin, если вы доверяете коду plugin и suite. См. What a run can access.

"No eval cases found"

Никакой <case>/prompt.md или <case>/case.yaml не существует под директорией eval в действии, или ваши фильтры --case и --tag не соответствовали никакому кейсу. Запустите из корня plugin или запустите claude plugin eval init, чтобы создать suite.

The baseline arm shows no plugin, or delta is zero

Если сводка не имеет столбца W/OUT или кейс не пройдет с "ablation requested but no plugin resolved", никакой plugin не был найден для кейса. Добавьте plugins: ["../.."] к кейсу, давая путь от директории кейса к директории plugin.

Если plugin действительно загружен и Δ все еще близко к нулю с неудачным grader tool_used: Skill, это обычно реальное открытие, означающее, что description skill не запускается на формулировке prompt. Отрегулируйте описание и перезапустите ту же suite.

"Agent type '...' not found" for one of your plugin's agents

По умолчанию каждый кейс запускается как с вашим plugin, так и без него, и запуски без него являются базовым запуском без plugin. Когда Claude отправляет одного из агентов вашего plugin в базовом запуске, вызов инструмента Agent не удается с Agent type '<plugin>:<agent-name>' not found. Available agents: .... Список называет только агентов, которые существуют без plugin, такие как встроенные подагенты.

Ошибка ожидается, так как Δ сравнивает запуски вашего plugin с базовым. В результате JSON базовые запуски находятся под cases[].arms.without.

В запусках с загруженным вашим plugin, кейс, который перечисляет Agent в allowed_tools, может отправить одного из агентов вашего plugin по его пространственному имени, такому как my-plugin:code-reviewer для агента code-reviewer в plugin с именем my-plugin. Чтобы пропустить базовые запуски, передайте --ablation none.

Everything scores zero although the right files were produced

Ваши graders нацелены на files, список созданных путей, когда вы имели в виду содержимое файла. Используйте { source: file, path: <path> } как target или focus.

Отдельно, file_exists считает только файлы, созданные во время запуска, поэтому файл, который scaffold создал или который Claude только отредактировал, невидим для него; оцените его содержимое или используйте tool_used на Edit.

A regex over the trace doesn't match text I can see

• Wrong target: default target — это last_message, не trace.
• JSON escaping: когда вы действительно нацеливаетесь на trace, это JSON на строку, поэтому кавычки появляются как \".
• Regex syntax: regexes используют JavaScript синтаксис, поэтому поместите i в flags вместо написания (?i).

Tools are denied, MCP tools are missing, or Bash won't run

Все, что за пределами набора только для чтения, нуждается в вашем гранте, такой как --allow-tools Bash Write. Ваши личные MCP серверы никогда не загружаются в запуск. Собственные серверы plugin не запускаются, если вы не opt in, и их инструменты затем также нуждаются в гранте --allow-tools "mcp__plugin_<plugin>_<server>__*"; замокированный инструмент не нуждается ни в чем.

The run exits 1 but the results look fine

Default --threshold — это 1.0, поэтому команда выходит 1, когда любой кейс оценен ниже совершенства. Установите порог, который соответствует требуемой оценке. Exit 1 также охватывает файл кейса, который не загружен, который сообщается на stderr выше таблицы.

"--json output path must end in .json"

Вы поместили target после --json, поэтому он был прочитан как путь вывода. Поместите target первым, как в claude plugin eval . --json, или дайте --json явный путь .json.

A grader shows passed: false under a run that scored 1.0

Этот grader исключен из оценки по дизайну в двухarm запуске, и его поле scored — это false. См. Score against the no-plugin baseline.

Runs fail with a usage-limit or rate-limit error partway through

Если ваш аккаунт достигает лимита использования плана или API лимита скорости, пока suite запускается, каждый более поздний запуск заканчивается этой ошибкой, оценивается на том, что он произвел, и обычно оценивается в 0. Suite все еще завершается и не отмечена partial, поэтому результат может выглядеть как регрессия. Проверьте столбец NOTES или cases[].arms.with[].error в JSON для сообщения лимита перед тем как доверять оценкам, затем перезапустите после того как лимит сбросится, с --runs 1 или фильтром --case, если вам нужно остаться под ним.

Runs time out or hit the turn cap

Defaults — это 10 turns и 300 секунд. Поднимите max_turns и timeout_seconds в кейсе для задач, которые нуждаются в большем, и используйте --max-cost-usd как потолок стоимости вместо плотных per-run лимитов.

См. также

• Создание плагина: создайте плагин, который вы тестируете, и загрузите его с помощью --plugin-dir во время разработки
• Справочник команд плагинов: записи команд plugin eval и plugin eval init. Ключ experimental.evals манифеста находится в справочнике манифеста
• Skills: как описание skill решает, когда Claude его вызывает, что измеряет случай, проверяющий, срабатывает ли skill
• Sandboxing: изолированная среда на уровне ОС, которая применяется при предоставлении Bash для запуска
• Публикация плагина: опубликуйте плагин после того, как его набор тестов пройдёт
• Измерение стоимости и использования плагина: что плагин добавляет к контексту каждой сессии и используют ли его люди