Como testar plugins do Claude Code e medir sua contribuição

O momento dessa mudança importa. O Claude Code 2.1.269 passou a oferecer evals de plugins em 11 de setembro de 2026. O tutorial datado que ainda lidera essa busca descreve um runner personalizado em Python. Para quem mantém um plugin local hoje, o caminho mais curto agora é nativo: inicializar um caso de comportamento, executá-lo contra um controle, examinar o relatório e fazer o CI rejeitar a mesma regressão que você acabou de provocar de propósito.

Como testar plugins do Claude Code: o que o eval nativo mede

Um eval de plugin é um teste A/B do comportamento do agente. Imagine duas oficinas idênticas recebendo a mesma ordem de serviço. Uma delas tem seu plugin instalado; a outra, não. O Claude Code repete a tarefa nas duas, avalia o trabalho e informa WITH, W/OUT e Δ — a nota com o plugin menos a nota sem ele.

Esse delta é o número que realmente interessa. Uma nota 1.0 nas duas variantes pode parecer excelente, mas indica que o Claude já conseguia concluir a tarefa sem seu plugin. Um delta positivo mostra uma contribuição mensurável. Um delta negativo revela que o plugin piorou o comportamento testado.

Por padrão, um caso gera três sessões novas com o plugin e três sem ele. Cada sessão recebe um diretório home, um diretório de trabalho e uma configuração do Claude Code isolados. Suas configurações pessoais, o CLAUDE.md do projeto, outros plugins, a memória e seus servidores MCP pessoais não acompanham a execução. Esse isolamento deixa a comparação mais limpa, mas também faz um plugin que depende secretamente da configuração do seu notebook falhar pelo motivo certo. A documentação da Anthropic sobre evals de plugins detalha todo o contrato de isolamento e segurança.

Comece com um plugin local que já funciona

Os evals de comportamento são a segunda verificação, não a primeira. O diretório do plugin precisa conter um plugin.json, um .claude-plugin/plugin.json ou uma estrutura válida de diretório de skills. Use claude plugin validate para encontrar problemas de arquivo e schema. Deixe claude plugin eval para perguntas como: “A skill foi acionada por uma solicitação natural e entregou o padrão editorial da equipe?”

Também é necessário usar o Claude Code v2.1.269 ou posterior, com a mesma autenticação das sessões comuns. As sessões de eval, os avaliadores por modelo e o inicializador interativo consomem a franquia do seu plano ou geram cobrança pela API. Se a configuração mais ampla do Claude Code ainda for novidade, comece pelo fluxo local básico antes de acrescentar um gate de lançamento.

Na raiz de um plugin confiável, confira a versão e crie um caso vazio:

claude --version
claude plugin eval init --bare release-note

A alternativa interativa é claude plugin eval init. Ela lê o plugin, pergunta como deve ser um bom resultado, propõe casos e avaliadores, faz uma execução-piloto e grava a suíte. Para aprender o contrato, a opção --bare é melhor porque cria os arquivos sem executar nada.

Monte um caso de comportamento fácil de interpretar

Suponha que o plugin em funcionamento contenha uma skill chamada release-notes. O valor dela não está apenas em redigir um texto. A skill deve reconhecer uma solicitação natural sobre uma mudança de produto e responder no formato de release note da equipe, dividido em três partes: Summary, Impact e Risk.

Coloque a solicitação realista do usuário em prompt.md. Depois, acrescente um avaliador determinístico para o resultado e outro para o mecanismo. “Determinístico” significa que a CLI verifica diretamente o trace ou o texto, sem chamar um modelo avaliador.

# evals/release-note/prompt.md
---
name: release-note
tags: [smoke]
runs: 3
max_turns: 8
timeout_seconds: 180
allowed_tools: [Skill]
---

Turn this change into a customer-facing release note: checkout now retries a failed payment once before showing an error.

# evals/release-note/graders/format.md
---
type: regex
target: last_message
pattern: 'Summary[\s\S]*Impact[\s\S]*Risk'
flags: i
---

# evals/release-note/graders/skill-fired.md
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?release-notes"'
---

Troque release-notes pelo name real definido no SKILL.md da sua skill. O prompt evita de propósito citar a skill ou impor os três títulos. Desse modo, o teste verifica se o plugin reconhece a tarefa e contribui com seu formato. Se o próprio prompt trouxer todas as respostas, a variante sem plugin também poderá passar, e o delta mostrará que o plugin acrescentou pouco.

O frontmatter acima segue o schema nativo atual. Em prompt.md, campos como runs, max_turns, timeout_seconds, model, tags e allowed_tools ficam no nível superior. Caso precise de fixtures, histórico da conversa ou diretórios, adicione case.yaml; esse arquivo exige schema_version: "1.1" e name, além de mover os campos de execução para execution:.

Execute o teste e interprete o relatório

Na raiz do plugin, rode claude plugin eval .. Com esse único caso, o comando inicia três sessões com o plugin e três sessões de baseline. As linhas de progresso mostram o resultado dos avaliadores à medida que cada sessão termina. Ao final, o resumo apresenta WITH, W/OUT, Δ, RUNS, COST e NOTES.

Leia os campos nesta ordem:

1. WITH responde se as sessões equipadas com o plugin atenderam aos avaliadores.
2. W/OUT mostra com que frequência o Claude chegou sozinho ao mesmo resultado.
3. Δ mede a contribuição do plugin. Um valor positivo é útil; perto de zero exige investigação; negativo significa regressão.
4. COST é uma estimativa baseada no preço de tabela, não necessariamente o valor cobrado em uma assinatura.
5. NOTES aponta a falha de maior peso ou o erro de execução mais importante na variante com plugin.

Toda suíte com pelo menos um caso grava aggregate-result.json e um report.html independente em um diretório de resultados com timestamp. No relatório HTML, você pode abrir cada execução, conferir o veredito e a explicação de cada avaliador e comparar as definições do prompt e dos avaliadores com o que o Claude realmente fez. O JSON traz campos estáveis para CI, incluindo nota geral, casos aprovados, delta médio, status parcial, estimativa de custo, duração e versão do Claude Code.

Provoque uma regressão antes de confiar no teste

Agora prove que o teste sabe falhar. Substitua temporariamente a descrição da skill release-notes por algo vago, que já não mencione a tarefa que ela deveria reconhecer. Não altere o caso de eval. Execute novamente o mesmo comando, examine o novo relatório e então restaure a descrição correta.

A falha procurada é comportamental: o avaliador Skill deixa de passar, o formato esperado fica menos confiável ou a vantagem da variante com plugin diminui. Não tente prever uma nota exata; execuções de agentes variam. Se a quebra intencional deixar o relatório praticamente igual nas três execuções padrão, o caso ainda não protege o plugin. Torne a solicitação mais representativa, restrinja melhor o avaliador de resultado ou adicione um caso negativo no qual a skill não possa ser acionada.

Essa quebra deliberada equivale a apertar o botão de teste de um detector de fumaça. Um painel verde não vale nada até você comprovar que um defeito relevante consegue deixá-lo vermelho.

Defina o orçamento do ciclo antes de criar mais casos

Um único caso padrão já cria seis sessões de agente. Ao adicionar um avaliador com LLM, o mesmo caso passa a gerar dezoito votos do modelo avaliador: três votos para cada uma das seis sessões. As próprias sessões podem consumir vários turnos. Por isso, uma suíte pequena pode gastar bem mais do que a contagem de casos sugere.

Use três orçamentos para três decisões distintas:

O ciclo de uma execução é ruidoso por definição. Use-o para detectar erros óbvios e depois confirme com as três execuções padrão antes de aceitar uma mudança. Prefira regex, tool_used, tool_order e file_exists nas verificações frequentes, pois elas não acrescentam chamadas de avaliadores. Reserve um avaliador com LLM para resultados curtos cuja qualidade não possa ser expressa por uma regra estável.

A opção de custo exige uma ressalva. --max-cost-usd limita a estimativa de preço de tabela feita pela CLI antes do início de cada execução. Execuções que já começaram chegam ao fim, então a estimativa informada pode ultrapassar o teto. Quando o teto é atingido, os resultados ficam parciais e o processo termina com o código 2. É uma barreira de proteção, não uma carteira pré-paga.

Leve a verificação de regressão para o CI

Depois que a regressão intencional aparecer e o plugin restaurado passar, coloque exatamente a mesma suíte sob controle de versão. O exemplo de CI da Anthropic fixa os modelos do agente e do avaliador, grava results.json, usa um limite de 0.8, mantém o relatório local e define um teto de custo estimado de $20. Ele também passa --trust-plugin, algo apropriado apenas quando o plugin e a suíte obtidos no checkout são códigos que você executaria por conta própria.

O comando exato para essa passagem é 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. Coloque-o no job depois de instalar e autenticar o Claude Code; em seguida, arquive os dois arquivos de resultado.

O status de saída do comando basta para bloquear um build. O código 0 indica que todos os casos foram carregados e atingiram o limite. O código 1 cobre uma nota abaixo do limite e diversos erros de configuração. O código 2 representa uma execução parcial causada pelo teto de custo ou por uma rejeição inicial das credenciais. Arquive results.json e report.html mesmo quando houver falha, para que o autor identifique se o plugin regrediu, a execução excedeu o tempo ou o orçamento a interrompeu.

Fixar os modelos é importante. Caso contrário, a troca de um modelo pode parecer uma regressão do plugin. Aplique a mesma disciplina ao esforço de raciocínio: teste qualidade e esforço em trilhas separadas, evitando que uma mudança de custo fique escondida dentro da nota de comportamento.

Sete comportamentos de plugins que valem testar primeiro

As equipes com maior retorno são as que distribuem plugins para outras pessoas. Um utilitário particular tolera uma conferência manual. Já um plugin de marketplace ou de uma organização transforma uma descrição fraca, uma permissão de ferramenta ou uma mudança de saída em chamados de suporte recorrentes.

Comece pelos dois primeiros comportamentos cuja ausência seria percebida pelos usuários. Dez casos vagos ajudam menos do que um teste de acionamento e um teste de resultado capazes de expor um defeito reproduzível.

Dois produtos que podem nascer dos evals nativos de plugins

1. Um gate de delta para pull requests é a melhor oportunidade

Crie um produto enxuto de CI que execute o comando nativo, leia aggregate-result.json e publique uma única revisão com a variação da nota, o delta, o custo, o avaliador que falhou e links para o relatório arquivado. Equipes de plugins e responsáveis por marketplaces pagam pela camada de decisão, não por mais um avaliador.

A demanda ainda está no começo, mas o sinal comercial é claro. claude code evals registra cerca de 50 buscas mensais nos EUA, alta de 600% em relação ao ano anterior e CPC de $17.61. Plataformas de avaliação mais amplas também mostram que existe orçamento para qualidade: a Braintrust oferece um plano Pro de $249 por mês. Isso serve como referência da categoria, não como recomendação de preço para um wrapper de plugin.

A menor versão vendável é uma GitHub Action acompanhada de um comentário no PR. Ela recebe o caminho do plugin, o limite de aprovação, os modelos fixados e o teto de custo estimado; envia o JSON e o HTML nativos; e diferencia o código de saída 1 da saída parcial 2. O risco de plataforma é real: a Anthropic pode acrescentar relatórios de PR próprios. A camada defensável está nas políticas entre repositórios, nas comparações históricas e nas regras de aprovação — não em uma cópia mais bonita do relatório nativo.

2. Pacotes de evals selecionados podem atender autores de skills

Venda pacotes de casos mantidos para tarefas comuns de plugins, como revisão de código, redação de changelogs, triagem de incidentes e seleção segura de ferramentas. Um pacote é um diretório evals/ comum, com prompts positivos e negativos realistas e avaliadores determinísticos, para que uma equipe possa adaptá-lo em vez de inventar do zero seu padrão de qualidade.

A palavra-chave direta claude code skill evals recebe cerca de 10 buscas mensais nos EUA. É um volume minúsculo, portanto funciona melhor como complemento especializado do que como mercado independente para uma startup financiada por venture capital. O MVP é um pacote excelente para uma categoria valiosa de plugin, versionado conforme as versões do Claude Code e acompanhado de um guia curto de calibração. A ressalva também é evidente: claude plugin eval init já propõe casos e faz execuções-piloto. Os pacotes só vencem quando seus cenários de domínio e critérios de falha são melhores do que uma geração genérica.

O que esse comando não resolve

Evals nativos não provam que um plugin é universalmente bom. Eles mostram como o plugin se comportou diante dos prompts, do ambiente, do modelo, das permissões de ferramentas e dos avaliadores escolhidos. Prompts fracos produzem notas que agradam. Uma regex pode recompensar o título certo acompanhado do conteúdo errado. Um avaliador com LLM pode variar e acrescenta três votos por avaliador em cada execução.

O isolamento traz outra restrição legítima. Cada execução começa limpa, portanto arquivos do projeto, configurações do usuário, hooks e servidores pessoais ficam de fora. Isso é excelente para a reprodutibilidade e ruim para um caso que não declarou as fixtures de que precisa. Ferramentas além do conjunto somente leitura exigem uma permissão explícita na linha de comando. Servidores MCP reais do plugin precisam de habilitação e permissões adicionais; hooks e servidores reais, por sua vez, merecem um runner isolado porque podem operar fora da sandbox do agente.

Por fim, não aperte max_turns ou timeout_seconds até o trabalho legítimo bater no limite. Uma execução que estoura o tempo ou atinge o limite de turnos é registrada como erro e geralmente reduz a nota. Reserve espaço suficiente para a tarefa pretendida e use o teto de custo estimado para controlar a suíte como um todo.

Na segunda-feira, quem mantém o plugin deve acrescentar um caso de acionamento, fazê-lo falhar de propósito, restaurar o plugin e limitar no CI exatamente essa verificação. Se você quiser implantar esse sistema de lançamento em todos os plugins da sua equipe, posso ajudar a projetar o gate para produção.