Claude Code проверяет, не зря ли вы написали плагин

Самое полезное число в claude plugin eval это не балл теста, а разница двух баллов: сколько кейс набрал с загруженным плагином и сколько без него. Если оба раза выходит 1,0, плагин ни при чём, Claude справился бы и сам, и документация Claude проговаривает это прямо.

Коротко

• claude plugin eval прогоняет набор кейсов из каталога evals внутри плагина, где каждый кейс это реалистичный запрос и одна или несколько проверок, и выставляет баллы.
• Каждый кейс по умолчанию запускается три раза в каждой из двух веток, порог прохождения равен 1,0, а балл прогона считается как доля прошедших проверок с учётом весов.
• Прогоны и судейские проверки идут через ваши учётные данные и съедают лимиты тарифа или счёт за API, а показанная стоимость только оценка по прайс-листу.

Если вы не следили: плагины Claude Code собирают навыки, агентов, хуки и MCP-серверы и ставятся из каталогов-маркетплейсов. По данным GitHub, сам Claude Code вышел исследовательским превью в феврале 2025 года, протокол MCP компания Anthropic показала в ноябре 2024 года, а субагенты добавили в июле 2025 года. Файлы плагина на ошибки синтаксиса и схемы умеет проверять claude plugin validate, но про поведение он ничего не говорит; новой команде нужен Claude Code 2.1.269 или новее.

Δ отделяет вклад плагина от того, что Claude умеет и так

Когда плагин найден, каждый кейс по умолчанию идёт в двух ветках: with-arm с загруженным плагином и without-arm, где не загружено ничего. Сводка и отчёт показывают оба балла и их разницу Δ. Флаг --ablation none оставляет только первую ветку и вдвое снижает стоимость, что удобно, пока вы правите сами проверки.

Балл прогона считается как доля прошедших проверок с учётом весов, балл кейса это среднее по его прогонам, а проходит кейс, когда набирает не меньше --threshold, по умолчанию 1,0. Любой кейс ниже порога даёт код возврата 1.

Есть тонкость: проверка tool_used с инструментом Skill без плагина пройти не может никогда, поэтому Claude Code исключает такие проверки из счёта в обеих ветках и показывает их в with-arm только как индикатор. Иначе базовая ветка валилась бы к нулю и раздувала Δ. Пометка arm: both возвращает проверку в счёт, и она нужна для условия «навык не должен сработать» с min: 0 и max: 0.

Из шести типов проверок четыре ничего не стоят

regex, tool_used, tool_order и file_exists считаются по стенограмме сессии и по файлам, поэтому они бесплатны. llm и baseline зовут модель-судью и добавляют к счёту. Своего кода в проверку не подставить, типов ровно шесть.

llm-проверка засчитывается, если судья проголосовал PASS хотя бы в двух случаях из трёх. Судьёй по умолчанию работает маленькая быстрая модель, для тонких рубрик документация советует --judge-model sonnet. Смотреть проверка может на последнее сообщение (это значение по умолчанию), на всю стенограмму, на список созданных файлов, на содержимое одного файла или на вызовы к мокнутым MCP-инструментам; из стенограммы судья видит первые 12 и последние 12 сообщений, а regex читает её целиком.

Отсюда совет из документации: длинный результат вроде сгенерированного файла проверять регуляркой по его содержимому, а llm оставить коротким ответам с рубрикой из конкретных условий PASS и FAIL. И если tool_used: Skill проходит, а Δ отрицательная, подозревать сначала судью: маленькая модель способна забраковать верный ответ за непривычное форматирование.

Писать всё это руками не обязательно: claude plugin eval init расспросит про плагин, предложит кейсы и проверки, попробует их и запишет файлы; о том же можно попросить Claude в уже открытой сессии.

Почему прогон не видит ни ваших настроек, ни текстов кейсов?

Каждый прогон идёт как отдельный неинтерактивный процесс claude -p со своим временным домашним каталогом, рабочим каталогом и конфигурацией, и загружен в него только тестируемый плагин. Ваши настройки, хуки, файлы CLAUDE.md, MCP-серверы, память и остальные плагины не подхватываются, из переменных окружения доходит лишь белый список и переменные EVAL_*. Каталог с эвалами агенту недоступен, так что он не прочитает ни свою рубрику, ни соседние кейсы. Проще говоря, это чужой ноутбук, на котором из всего вашего хозяйства установлен один плагин.

Рабочий каталог пустой, поэтому фикстуры создают bash-скриптом из case.yaml, и он запускается только с флагом --scaffold. Реальные MCP-серверы плагина сами не стартуют: инструмент отвечает из markdown-файла вида mocks/имя-сервера/имя-инструмента.md, а инструмент без мока агенту просто недоступен.

Из инструментов доступен только read-only набор, который кейс перечисляет в allowed_tools. Bash, Write, Edit, WebFetch и WebSearch без вашего гранта из сессии вырезаны, а выданный Bash работает под OS-песочницей; без её бэкенда прогон не стартует, поэтому на Windows набор гоняют в WSL2, а на Linux сначала ставят bubblewrap и socat.

В CI набор запускают с --trust-plugin и потолком по деньгам

Бюджет считается просто: набор делает примерно кейсы × прогоны запусков агента с плагином и столько же на базовую ветку, плюс три коротких обращения к судье на каждую llm- или baseline-проверку в каждом прогоне.

Потолок --max-cost-usd проверяется перед стартом каждого прогона, уже запущенные доигрывают, так что траты могут его перешагнуть. Если что-то не стартовало, команда выходит с кодом 2 и пишет частичный результат с полем partial. Коды такие: 0 всё прошло, 1 кейс ниже порога или файл кейса не загрузился, 2 частичный прогон, 130 прерывание, 143 завершение, например по таймауту CI.

Документация советует фиксировать --model и --judge-model, чтобы выкатка новой модели не выглядела регрессией плагина, отдавать результат в --json со схемой версии 1 и передавать --trust-plugin, иначе job упрётся в вопрос о доверии к каталогу. Интерактивный claude plugin eval init в CI не работает, для пустого шаблона есть claude plugin eval init --bare.

Одну деталь стоит запомнить до первого запуска в CI: если во время набора вы упрётесь в лимит тарифа или в rate limit API, каждый следующий прогон завершится ошибкой, будет оценён по тому, что успел сделать, и обычно получит 0, при этом набор не помечается как partial. На наш взгляд, это самое коварное место всей схемы: картинка на выходе неотличима от честной регрессии плагина, и авторам приходится сначала смотреть колонку NOTES или поле error в JSON.

Куда движется формат кейсов Формат этих кейсов отдельный от файла evals/evals.json, который использует плагин skill-creator, и сойдутся ли они когда-нибудь, документация не говорит. Сроков она тоже не называет: команду могут выключить со стороны Anthropic, тогда вы увидите сообщение «plugin eval is currently unavailable», а рекомендация одна, обновиться и попробовать позже в новой сессии. На вашей машине это ничем не лечится.