Skip to main content
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 plugins; чтобы проверить файлы plugin на синтаксические и схемные ошибки, а не его поведение, используйте claude plugin validate.
Каждый запуск eval и каждый judge grader — это реальный вызов модели на вашем аккаунте, учитываемый в использовании вашего плана или счете API, поэтому сначала проверьте требования. Затем создайте свой первый eval suite или перейдите к Run evals in CI, если у вас уже есть один.

​
Требования

Для запуска 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; Compare against a no-plugin baseline охватывает, как graders оцениваются в обоих arms и как отключить baseline.

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

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

Создайте кейсы

Из корня plugin запустите:
Если Claude Code еще не доверяет этой директории, он сначала спрашивает Trust this plugin directory?; ответьте y. Затем открывается интерактивная Claude Code сессия. Claude читает ваш plugin и спрашивает вас, как должен выглядеть хороший результат, предлагает prompts, которые должны и не должны запускать plugin, разрабатывает graders для каждого, пилотирует их один раз, чтобы проверить их поведение, и записывает одну директорию кейса на prompt под evals/, каждую названную в честь своего prompt. Когда Claude скажет вам, что suite готов, выйдите из этой сессии с /exit или Ctrl+D, чтобы вернуться в shell.Если у вас уже есть Claude Code сессия, открытая в корне plugin, вы можете вместо этого попросить Claude там запустить claude plugin eval init. Claude запускает команду и затем задает вам те же вопросы в этом разговоре.Если вы предпочитаете написать кейс самостоятельно, чтобы увидеть ровно то, что содержат файлы, следуйте Write a case manually и вернитесь сюда, чтобы запустить его.
2

Запустите suite

Вернитесь в shell в корне plugin и запустите каждый кейс под evals/:
Вы уже доверяли этой директории на шаге 1, поэтому запуск начинается немедленно. Если вы написали кейс вручную, запуск сначала спрашивает Trust this plugin directory? [y/N]; ответьте y. What a run can access объясняет, на что вы соглашаетесь.Каждый кейс запускается три раза с вашим plugin и три раза без него, поэтому один кейс — это шесть запусков. Строка прогресса печатается по мере завершения каждого запуска с оценкой этого запуска и вердиктом каждого grader.
3

Прочитайте сводку

Когда suite завершится, вы увидите таблицу сводки, за которой следует, где был записан отчет:
WITH — это оценка кейса с загруженным вашим plugin, W/OUT — это оценка без него, и положительное Δ означает, что plugin повысил оценку. COST — это оценка по прейскуранту вызовов модели, и NOTES показывает объяснение самого высокого веса неудачного grader или ошибку запуска из with-arm.
4

Откройте отчет и повторяйте

Откройте URL Published: или путь Report:, когда нет строки Published:, чтобы увидеть вердикт каждого grader и объяснение для каждого запуска, и для llm graders голоса judge и отрывок, который он оценивал. Строка Published: появляется только, когда ваш аккаунт может публиковать отчеты.Наиболее частое первое открытие — это Δ близко к нулю с неудачным grader tool_used: Skill кейса, что означает, что Claude не выбирает ваш skill при естественной формулировке. Отрегулируйте description skill, запустите claude plugin eval . снова и сравните.Чтобы повторять один кейс дешево, запустите один arm один раз. Один запуск шумный, поэтому подтвердите любое изменение при трех запусках по умолчанию, прежде чем доверять ему. С одним arm таблица показывает столбцы SCORE и PASS% вместо WITH, W/OUT и Δ:
Замените <case-name> на одно из имен директорий под evals/.

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

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

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

Рекомендуемый путь — это написание кейсов Claude с помощью claude plugin eval init. Чтобы написать один самостоятельно, начните с пустого шаблона. Следующая команда пишет кейс с именем first-case с placeholder prompt.md и одним placeholder grader и ничего не запускает:
В prompt.md вы пишете сообщение, которое Claude получает в каждом запуске, и устанавливаете лимиты запуска и инструменты, которые кейс может использовать в его frontmatter. Откройте evals/first-case/prompt.md и замените placeholder body на запрос, который должен обработать один из ваших skills, сформулированный так, как пользователь его напечатает, а не называя skill. Этот пример предназначен для skill, который составляет сообщения коммитов; используйте свой собственный запрос:
Каждый запуск начинается в пустой рабочей директории, поэтому поместите все, что нужно для задачи, в сам prompt, или установите workspace первым. Полный список frontmatter полей охватывает модель, timeout, теги и переменные окружения. Каждый файл под graders/ — это одна проверка, применяемая после запуска. Откройте evals/first-case/graders/criteria.md и замените placeholder на рубрику для judge модели, написанную как конкретные условия PASS и FAIL:
Затем добавьте второй grader, который проверяет, является ли ваш skill тем, что произвел ответ. Создайте evals/first-case/graders/skill-fired.md, заменив your-skill-name на name из SKILL.md вашего skill:
Это проходит, когда 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
  • Любой grader, который вы отметили arm: with-only
Если каждый grader в кейсе — это один из них, они вместо этого оцениваются нормально, так как не осталось бы ничего для оценки. Установите arm: both на grader, чтобы оценить его в обоих arms независимо, что вам нужно для проверки “не должен вызывать skill” с min: 0 и max: 0. Под --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 кейса становится следующим ходом пользователя. Чтобы позволить Claude читать директории fixtures в кейсе во время запуска, перечислите их в context.add_dirs. case.yaml также нуждается в schema_version: "1.1" и name; справочник case.yaml fields содержит полный список. Этот case.yaml заполняет workspace из скрипта и позволяет Claude читать fixtures из директории resources/:

​
Mock MCP серверы

Вы можете оценить plugin, чьи skills вызывают MCP инструменты без реального сервиса позади них. Поместите один Markdown файл на инструмент под evals/mocks/<server>/<tool>.md для всей suite или под собственную директорию mocks/ кейса для одного кейса, где <server> — это имя сервера в MCP конфигурации вашего plugin. Запуск никогда не запускает реальные MCP серверы вашего plugin, если вы не попросите. Claude Code регистрирует stand-in под каждым именем сервера. Инструменты с файлом 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:
Вставьте поля из input вызова с {{input.<field>}} и содержимое файла fixture рядом с mock с {{file:fixtures/{input.<field>}.json}}. Блок expect: охраняет input. Если вызов нарушает его, запуск прерывается с оценкой 0 и записывает почему, поэтому кейс может утверждать, что ваш plugin попросил сервер сделать. Установите error: true, чтобы вернуть body как ошибку инструмента вместо этого, или 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 не может их вызывать вообще. Allowlist — это инструменты только для чтения, которые кейс перечисляет в allowed_tools, из Read, Glob, Grep, NotebookRead, Skill, Agent, TodoWrite и инструменты задач TaskCreate, TaskGet, TaskList, TaskUpdate, TaskStop и TaskOutput, плюс все, что вы предоставляете с --allow-tools, что применяется к каждому кейсу в запуске. Чтобы позволить кейсам использовать Bash, Write, Edit, WebFetch или WebSearch, предоставьте их сами:
Когда кейс попросил инструмент, который вы не предоставили, запуск перечисляет его на stderr как 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, чтобы работа никогда не ждала на первом запросе доверия, закрепите обе модели, чтобы оценки были сравнимы со временем, держите отчет локально и установите потолок стоимости как верхний лимит:
Exit код работы говорит вам, что произошло: Проблемы с написанием или публикацией HTML отчета никогда не изменяют exit код. Чтобы увидеть, почему кейс оценен низко, запустите его локально без --json, чтобы строки прогресса per-run и grader печатались. CI runner нуждается в Claude Code установке и учетных данных в окружении, такие как ANTHROPIC_API_KEY. Без --trust-plugin работа, чья директория checkout Claude Code еще не доверяет, отказана с exit 1, когда она не имеет терминала, или ждет на запросе, когда runner выделяет один. 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; показанная стоимость — это оценка по прейскуранту и варьируется в зависимости от модели и количества кейсов: Верхняя часть отчета eval: строка вердикта, читающая "Plugin effect: +33.3 pts vs baseline, improved 2, flat 1, regressed 0 of 3 cases", пять плиток сводки для оценки suite, ablation delta, baseline score, кейсов, прошедших threshold, и perfect runs, затем первый кейс с его delta, score bar и одним запуском, чьи два graders оба показывают pass Читайте его сверху вниз:
  • Строка вердикта и плитки отвечают на вопрос, помог ли 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 целевого плагина и запускает его набор тестов на вашей машине от вашего имени. Указание на плагин — это то же самое решение о доверии, что и claude --plugin-dir, поэтому оценивайте только плагины, которым вы доверяете. Изоляция, описанная в этом разделе, ограничивает то, что может достичь тестируемый агент; это не граница против собственного кода плагина, и набор, который проходит, ничего не говорит о том, безопасен ли плагин.

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

При первом запуске claude plugin eval для директории Claude Code спрашивает Trust this plugin directory? перед загрузкой чего-либо из неё, если вы уже не приняли приглашение доверия там в интерактивном сеансе claude. Внутри репозитория git ответ «да» доверяет всему репозиторию, также для интерактивных сеансов. Когда stdin или stdout не является терминалом или под --json, запуск не может спросить и отказывается с выходом 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:

​
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. Запустите 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.

​
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

Default target — это last_message, не trace. Когда вы действительно нацеливаетесь на trace, это JSON на строку, поэтому кавычки появляются как \". 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. См. Compare against a 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 для запуска
  • Создание и распространение marketplace плагинов: опубликуйте плагин после того, как его набор тестов пройдёт