eval-harness

Visão geral da skill eval-harness

O que a eval-harness faz

A skill eval-harness é uma estrutura formal de avaliação para sessões no Claude Code e para desenvolvimento guiado por evals. Ela ajuda você a definir o que significa “bom” antes de entregar, e depois medir se um agente, prompt ou fluxo de trabalho realmente atende a esse padrão.

Quem deve usar

Use a skill eval-harness se você precisa de verificações repetíveis para programação assistida por IA, mudanças de prompt ou comportamento de agente. Ela é especialmente útil para equipes que comparam versões de modelos, acompanham regressões ou transformam expectativas vagas de tarefas em critérios de aprovação/reprovação.

Por que isso importa

O principal valor de eval-harness for Model Evaluation é a confiabilidade: em vez de julgar resultados no feeling, você escreve evals que mostram quando o comportamento muda. Isso facilita depurar o desempenho do agente, comparar execuções e evitar publicar atualizações de prompt que degradam a qualidade de forma silenciosa.

Quando é uma boa escolha

Ela funciona melhor quando a tarefa pode ser expressa como critérios de sucesso observáveis, estrutura de saída ou comportamento verificado em etapas. É menos útil para trabalho criativo em aberto, a menos que ainda seja possível definir condições mensuráveis de aceitação.

Como usar a skill eval-harness

Instale e ative

Para eval-harness install, use o fluxo de instalação de skills do repositório no seu ambiente do Claude Code e depois abra o arquivo da skill diretamente. A skill fica em skills/eval-harness/SKILL.md, e esse é o primeiro arquivo a ler porque ele define quando ativar o framework e como estruturar os evals.

Monte um prompt que a skill consiga avaliar

Para um bom eval-harness usage, não comece com “teste meu agente”. Comece com um alvo concreto, por exemplo: qual tarefa o agente precisa concluir, o que conta como sucesso, como é uma falha e se você está verificando capacidade ou regressão. Uma entrada melhor seria: “Avalie se o agente consegue atualizar um formulário em React sem quebrar a validação e exija três critérios explícitos de sucesso.” Isso dá ao harness algo mensurável.

Leia primeiro os arquivos certos

Se você está adotando a abordagem eval-harness guide no seu próprio fluxo, leia primeiro SKILL.md e depois inspecione quaisquer notas do repositório que descrevam estilo de avaliação, lógica de pontuação ou convenções de saída. Neste repositório, não há scripts auxiliares nem pastas extras de suporte, então o próprio arquivo da skill é a fonte da verdade.

Use em um fluxo prático

Um bom fluxo é: defina o comportamento, escreva um eval para o caminho feliz, adicione um eval de regressão para uma falha já conhecida, depois rode o harness e refine os critérios. Isso mantém os evals pequenos o bastante para depurar e reduz a chance de criar testes amplos demais para interpretar.

FAQ da skill eval-harness

A eval-harness é só para Claude Code?

Não. A skill foi escrita em torno de sessões no Claude Code, mas o método por trás dela é útil em qualquer lugar em que você precise de avaliação estruturada de agentes. Se o seu stack usa outras ferramentas, você ainda pode adaptar o formato dos evals e a lógica de pontuação.

A eval-harness é a mesma coisa que um prompt normal?

Não. Um prompt normal pede uma resposta; eval-harness pede uma forma repetível de julgar respostas. Essa diferença importa quando você precisa de consistência entre versões, e não apenas de uma única resposta boa.

É amigável para iniciantes?

Sim, se você consegue descrever uma tarefa com clareza. A parte mais difícil não é a sintaxe; é escrever bons critérios de sucesso. Iniciantes costumam se dar bem quando começam com um único eval simples de capacidade, em vez de tentar modelar um fluxo inteiro de uma vez.

Quando eu não devo usar?

Evite eval-harness se o trabalho for altamente subjetivo, se a saída não puder ser verificada de forma consistente ou se você só precisar de uma resposta pontual. Ela é mais forte quando confiabilidade, acompanhamento de regressões ou comparação de modelos é o objetivo real.

Como melhorar a skill eval-harness

Torne os critérios observáveis

O maior ganho de qualidade vem de transformar opiniões em verificações. Troque “deixe melhor” por condições como “preserve a estrutura existente da API”, “retorne JSON válido” ou “passe nos três casos de regressão”. Quanto mais observáveis forem os critérios, mais fácil fica executar e confiar em eval-harness.

Separe capacidade de regressão

Se você misturar verificações de nova funcionalidade com verificações de comportamento antigo, as falhas ficam difíceis de interpretar. Mantenha os evals de capacidade focados em saber se o Claude consegue fazer algo novo, e os de regressão focados em verificar se uma base conhecida continua válida.

Dê casos-limite reais ao harness

Evals mais fortes incluem modos de falha, e não só caminhos felizes. Adicione entradas complicadas, contexto incompleto ou instruções ambíguas para que a eval-harness skill revele se o agente é robusto ou apenas teve sorte em exemplos limpos.

Itere depois da primeira execução

Trate a primeira execução como calibração, não como prova. Se o resultado ficar अस्प? Wait.