Skill de Estrutura de Avaliação
Um framework formal de avaliação para sessões do Claude Code, implementando princípios de desenvolvimento orientado por avaliação (EDD).
Quando Ativar
- Ao configurar desenvolvimento orientado por avaliação (EDD) para fluxos de trabalho assistidos por IA
- Ao definir critérios de aprovação/reprovação para conclusão de tarefas do Claude Code
- Ao medir a confiabilidade do agente com métricas pass@k
- Ao criar suítes de teste de regressão para alterações de prompt ou agente
- Ao comparar o desempenho do agente entre versões de modelo
Filosofia
O Desenvolvimento Orientado por Avaliação trata avaliações como os "testes unitários do desenvolvimento de IA":
- Defina o comportamento esperado ANTES da implementação
- Execute avaliações continuamente durante o desenvolvimento
- Acompanhe regressões a cada alteração
- Use métricas pass@k para medir a confiabilidade
Tipos de Avaliação
Avaliações de Capacidade
Testam se o Claude consegue fazer algo que antes não conseguia:
[AVALIAÇÃO DE CAPACIDADE: nome-da-funcionalidade]
Tarefa: Descrição do que o Claude deve realizar
Critérios de Sucesso:
- [ ] Critério 1
- [ ] Critério 2
- [ ] Critério 3
Saída Esperada: Descrição do resultado esperado
Avaliações de Regressão
Garantem que alterações não quebrem funcionalidades existentes:
[AVALIAÇÃO DE REGRESSÃO: nome-da-funcionalidade]
Linha de Base: SHA ou nome do checkpoint
Testes:
- teste-existente-1: APROVADO/REPROVADO
- teste-existente-2: APROVADO/REPROVADO
- teste-existente-3: APROVADO/REPROVADO
Resultado: X/Y aprovados (anteriormente Y/Y)
Tipos de Avaliador
1. Avaliador Baseado em Código
Verificações determinísticas usando código:
# Verifica se o arquivo contém o padrão esperado
grep -q "export function handleAuth" src/auth.ts && echo "APROVADO" || echo "REPROVADO"
# Verifica se os testes passam
npm test -- --testPathPattern="auth" && echo "APROVADO" || echo "REPROVADO"
# Verifica se a build é bem-sucedida
npm run build && echo "APROVADO" || echo "REPROVADO"
2. Avaliador Baseado em Modelo
Usa o Claude para avaliar saídas abertas:
[PROMPT DO AVALIADOR DE MODELO]
Avalie a seguinte alteração de código:
1. Ela resolve o problema declarado?
2. Está bem estruturada?
3. Casos extremos são tratados?
4. O tratamento de erros é adequado?
Pontuação: 1-5 (1=ruim, 5=excelente)
Justificativa: [explicação]
3. Avaliador Humano
Sinaliza para revisão manual:
[REVISÃO HUMANA NECESSÁRIA]
Alteração: Descrição do que mudou
Motivo: Por que a revisão humana é necessária
Nível de Risco: BAIXO/MÉDIO/ALTO
Métricas
pass@k
"Pelo menos um sucesso em k tentativas"
- pass@1: Taxa de sucesso na primeira tentativa
- pass@3: Sucesso dentro de 3 tentativas
- Alvo típico: pass@3 > 90%
pass^k
"Todas as k tentativas são bem-sucedidas"
- Padrão mais alto para confiabilidade
- pass^3: 3 sucessos consecutivos
- Use para caminhos críticos
Fluxo de Trabalho da Avaliação
1. Definir (Antes de Codificar)
## DEFINIÇÃO DE AVALIAÇÃO: funcionalidade-xyz
### Avaliações de Capacidade
1. Consegue criar uma nova conta de usuário
2. Consegue validar o formato de email
3. Consegue hash de senha com segurança
### Avaliações de Regressão
1. O login existente ainda funciona
2. Gerenciamento de sessão inalterado
3. Fluxo de logout intacto
### Métricas de Sucesso
- pass@3 > 90% para avaliações de capacidade
- pass^3 = 100% para avaliações de regressão
2. Implementar
Escreva código para passar nas avaliações definidas.
3. Avaliar
# Executar avaliações de capacidade
[Execute cada avaliação de capacidade, registre APROVADO/REPROVADO]
# Executar avaliações de regressão
npm test -- --testPathPattern="existing"
# Gerar relatório
4. Relatar
RELATÓRIO DE AVALIAÇÃO: funcionalidade-xyz
========================
Avaliações de Capacidade:
criar-usuário: APROVADO (pass@1)
validar-email: APROVADO (pass@2)
hash-senha: APROVADO (pass@1)
Geral: 3/3 aprovados
Avaliações de Regressão:
fluxo-login: APROVADO
gerenciamento-sessão: APROVADO
fluxo-logout: APROVADO
Geral: 3/3 aprovados
Métricas:
pass@1: 67% (2/3)
pass@3: 100% (3/3)
Status: PRONTO PARA REVISÃO
Padrões de Integração
Pré-Implementação
/avalie definir nome-da-funcionalidade
Cria o arquivo de definição de avaliação em .claude/evals/nome-da-funcionalidade.md
Durante a Implementação
/avalie verificar nome-da-funcionalidade
Executa as avaliações atuais e relata o status
Pós-Implementação
/avalie relatar nome-da-funcionalidade
Gera um relatório completo de avaliação
Armazenamento de Avaliações
Armazene avaliações no projeto:
.claude/
evals/
funcionalidade-xyz.md # Definição da avaliação
funcionalidade-xyz.log # Histórico de execução da avaliação
baseline.json # Linhas de base de regressão
Melhores Práticas
- Defina avaliações ANTES de codificar - Força uma reflexão clara sobre critérios de sucesso
- Execute avaliações com frequência - Detecte regressões cedo
- Acompanhe pass@k ao longo do tempo - Monitore tendências de confiabilidade
- Use avaliadores de código quando possível - Determinístico > Probabilístico
- Revisão humana para segurança - Nunca automatize completamente verificações de segurança
- Mantenha avaliações rápidas - Avaliações lentas não são executadas
- Versionar avaliações com código - Avaliações são artefatos de primeira classe
Exemplo: Adicionando Autenticação
## AVALIAÇÃO: adicionar-autenticacao
### Fase 1: Definir (10 min)
Avaliações de Capacidade:
- [ ] Usuário pode registrar com email/senha
- [ ] Usuário pode fazer login com credenciais válidas
- [ ] Credenciais inválidas rejeitadas com erro apropriado
- [ ] Sessões persistem após recarregar a página
- [ ] Logout limpa a sessão
Avaliações de Regressão:
- [ ] Rotas públicas ainda acessíveis
- [ ] Respostas da API inalteradas
- [ ] Esquema de banco de dados compatível
### Fase 2: Implementar (variável)
[Escreva código]
### Fase 3: Avaliar
Execute: /avalie verificar adicionar-autenticacao
### Fase 4: Relatar
RELATÓRIO DE AVALIAÇÃO: adicionar-autenticacao
==============================
Capacidade: 5/5 aprovadas (pass@3: 100%)
Regressão: 3/3 aprovadas (pass^3: 100%)
Status: PODE LANÇAR