self-eval

Visão geral do skill self-eval

Para que serve o self-eval

O self-eval skill é um skill do Claude Code baseado apenas em prompt, criado para uma avaliação honesta depois que o trabalho já foi feito. Ele ajuda um agente de IA a avaliar a própria entrega após uma tarefa, revisão de código, sessão de implementação, rodada de depuração ou exercício de planejamento, sem cair em elogios vagos ou notas infladas do tipo “4/5”.

Em vez de perguntar “quão bom foi isso?” em uma única escala subjetiva, o self-eval separa a avaliação em dois eixos: ambição da tarefa e qualidade da execução. Isso o torna útil quando você precisa de uma resposta calibrada para: “Este foi um trabalho realmente forte ou apenas um trabalho adequado em uma tarefa fácil?”

Usuários e tarefas mais indicados

Use o skill self-eval se você quer que um agente revise um trabalho concluído antes de você aceitá-lo, fazer merge ou continuar construindo em cima dele. Ele é especialmente relevante para equipes de engenharia que usam IA em geração de código, refatoração, triagem de issues, escrita de testes ou análise de arquitetura.

Ele não substitui suítes de teste, revisão humana, revisão de segurança ou validação em produção. Seu valor está na autocrítica estruturada: reduzir excesso de confiança, expor fragilidades e criar um histórico de pontuação ao longo das sessões de trabalho.

O que torna isso diferente de um prompt comum

Um prompt comum de “avalie seu trabalho” costuma gerar pontos positivos genéricos, ressalvas leves e uma nota otimista. O self-eval adiciona restrições que dificultam a inflação: raciocínio obrigatório de advogado do diabo, uma matriz fixa de pontuação e persistência das notas em .self-eval-scores.jsonl.

Essa persistência importa. Se avaliações recentes ficarem concentradas demais, o skill pode sinalizar padrões de inflação de nota em vez de tratar cada revisão como um caso isolado.

Como usar o skill self-eval

Instalação do self-eval e verificação do repositório

Instale a partir da fonte do skill no GitHub usando seu gerenciador de skills, por exemplo:

npx skills add alirezarezvani/claude-skills --skill self-eval

O caminho relevante no repositório é:

engineering/skills/self-eval/SKILL.md

Na estrutura atual, não há dependências externas, scripts auxiliares, regras empacotadas ou arquivos de referência. Para uma revisão rápida antes da instalação, leia primeiro SKILL.md; ele contém o modelo de pontuação, o fluxo de trabalho e as expectativas de saída. Como este é um skill baseado apenas em prompt, o risco de adoção é baixo, mas a qualidade da saída depende muito de fornecer contexto suficiente sobre a tarefa.

Entradas de que o skill precisa

Para usar o self-eval de forma útil, não basta dizer “avalie isto”. Forneça ao agente o trabalho concluído e o padrão pelo qual ele deve ser julgado.

Boas entradas incluem:

• A solicitação original do usuário ou a descrição da issue
• A resposta final, patch, plano ou revisão produzida pelo agente
• Restrições relevantes, como limites de tempo, regras de estilo, requisitos de teste ou abordagens proibidas
• Evidências de validação, como testes executados, arquivos alterados, comandos rodados ou lacunas conhecidas
• O público pretendido: maintainer, reviewer, product owner, usuário iniciante ou equipe de produção

Um prompt fraco pede uma nota. Um prompt forte dá ao skill evidências suficientes para diferenciar “baixa ambição, mas bem executado” de “alta ambição, mas incompleto”.

Padrão de prompt para melhores resultados

Use o self-eval depois que o trabalho estiver concluído, não antes. Um prompt prático seria:

Use the self-eval skill to evaluate the work below. Original task: [goal]. Output produced: [answer or diff summary]. Constraints: [tests, style, repo rules]. Validation performed: [commands or none]. Known concerns: [risks]. Give the two-axis evaluation, devil's advocate reasoning, final matrix score, and concrete follow-up actions.

Essa estrutura melhora o resultado porque impede que o modelo avalie apenas o tom ou o esforço. Ela força a revisão a considerar ambição, execução, evidências e riscos não resolvidos.

Fluxo de trabalho sugerido

Execute o self-eval em pontos de controle nos quais uma avaliação positiva demais poderia sair caro:

1. Conclua a tarefa ou rascunhe a solução.
2. Peça o self-eval usando o objetivo original e as evidências do trabalho.
3. Leia a seção de advogado do diabo antes da nota final.
4. Converta as fragilidades em uma lista curta de correções.
5. Rode novamente apenas depois de mudanças significativas, não após edições cosméticas.

Se .self-eval-scores.jsonl for criado no seu diretório de trabalho, trate-o como histórico local de avaliação. Decida se sua equipe quer fazer commit desse arquivo, ignorá-lo ou revisá-lo periodicamente.

FAQ do skill self-eval

O self-eval serve para Model Evaluation ou qualidade de código?

Ele é útil para ambos, mas em um sentido específico. self-eval for Model Evaluation deve ser entendido principalmente como avaliação em nível de tarefa do próprio trabalho de um agente de IA, não como medição de modelo em nível de benchmark. Ele pode ajudar a comparar sessões, detectar autoavaliações infladas e melhorar a disciplina de revisão, mas não substitui harnesses formais de avaliação, datasets de referência ou pontuação rotulada por humanos.

Quando eu não devo usar o self-eval?

Não o use como a única barreira para trabalhos de alto risco: mudanças sensíveis à segurança, conteúdo jurídico ou médico, migrações de produção ou qualquer coisa que exija correção verificada. Também evite usá-lo quando não houver um artefato concreto a avaliar. O skill precisa de uma tarefa, uma saída e critérios de avaliação; caso contrário, ele ainda produzirá uma estrutura, mas com evidências fracas.

Ele é amigável para iniciantes?

Sim, porque é baseado apenas em prompt e não tem dependências de ferramenta. Ainda assim, iniciantes devem ler SKILL.md antes de usá-lo, especialmente a lógica de pontuação. A principal curva de aprendizado não está na instalação; está em fornecer contexto suficiente para que a avaliação não seja baseada em impressão subjetiva.

Como ele é diferente de pedir uma crítica?

Uma crítica pode listar problemas sem uma pontuação calibrada. O self-eval usa um modelo de dois eixos e uma nota final travada por matriz, então o agente tem menos liberdade para justificar qualquer avaliação que “pareça” certa. A etapa de advogado do diabo também exige argumentar tanto por uma nota mais alta quanto por uma nota mais baixa antes de resolver o julgamento final.

Como melhorar o skill self-eval

Dê evidências mais fortes ao self-eval

A melhor forma de melhorar os resultados do self-eval é tornar as evidências concretas. Inclua arquivos alterados, testes que falharam ou passaram, omissões importantes e critérios de aceitação. Se nenhum teste foi executado, diga isso. Se a resposta ignorou intencionalmente algum requisito, inclua essa informação também.

Entrada melhor não significa entrada mais longa; significa entrada avaliável. “Refatorei o código de autenticação” é fraco. “Refactored auth/session.ts to remove duplicated token parsing; ran npm test -- auth; did not test OAuth callback manually” dá ao skill algo real para pontuar.

Fique atento a modos de falha comuns

A falha mais comum é deixar o modelo recompensar esforço em vez de resultado. Outra é tratar uma tarefa difícil com execução parcial como automaticamente forte. O self-eval foi projetado para resistir a isso, mas só funciona bem se o usuário incluir a ambição original e a entrega real.

Também fique atento ao ruído no histórico de pontuações. Se .self-eval-scores.jsonl mistura tipos de tarefa sem relação entre si, os sinais de agrupamento podem ser menos significativos. Uma rodada de polimento de documentação e uma migração complexa não devem ser interpretadas como equivalentes só porque compartilham uma nota numérica.

Itere da nota para a ação

Não pare na nota final. A saída útil é a lacuna entre ambição e execução. Transforme essa lacuna em um prompt de correção:

Based on the self-eval weaknesses, revise the work to address the top three execution gaps. Do not expand scope. Preserve the original constraints and report what changed.

Isso mantém a próxima iteração focada. Também impede que o agente “melhore” o trabalho adicionando funcionalidades sem relação apenas para buscar uma nota mais alta.

Personalize com cautela

Se você adaptar o skill self-eval, preserve as partes que criam calibração: eixos separados, raciocínio de advogado do diabo, mapeamento fixo de notas e consciência do histórico de pontuação. Personalizar rótulos, formato de saída ou critérios de aceitação específicos da equipe costuma ser seguro. Remover as restrições que fazem o modelo argumentar contra si mesmo fará o skill se comportar mais como um prompt comum de revisão.