Módulo 0.1 · o método

Comece pelas falhas — triadas por um juiz

Antes de escrever um único juiz, você precisa saber como seu sistema falha. O estado da arte recomenda começar pelos dados. O problema é que ninguém consegue analisar manualmente dez mil registros de execução. O juiz faz essa leitura; você examina os grupos produzidos e decide o que importa. Esse é o harness em um movimento.

o que você vai conseguir fazer Ao final deste módulo você pode mapear os modos de falha reais do seu sistema com um juiz de descoberta e decidir quais merecem um gate.

A armadilha: enviar juízes para falhas que você nunca mapeou

A maioria das equipes pula direto para "vamos adicionar uma avaliação de alucinação". Mas esse problema pode representar apenas 3% das falhas reais, enquanto erros silenciosos em chamadas de ferramenta representam 40%. Escreva juízes antes de mapear as falhas e você endurece a parede errada. O primeiro trabalho é sempre o mesmo: encontrar os modos de falha que realmente ocorrem, ordenados por frequência.

o movimento Aplique um juiz de descoberta a uma amostra de registros de produção. Seu trabalho não é aprovar ou reprovar, mas é agrupar falhas em modos nomeados com uma contagem. A saída é uma taxonomia ordenada, não uma pontuação. Agora você sabe onde investir.

A decisão continua humana

Analisar manualmente 10 mil registros de execução exige um volume de revisão inviável para uma pessoa. Já examinar doze grupos de falhas e decidir "estes três representam problemas reais, aquele resulta de um rótulo ruim, o restante pode esperar" leva poucos minutos. O juiz processa os casos; você decide quais falhas merecem um gate. Assim, um critério definido por uma pessoa pode ser aplicado de forma consistente a todo o conjunto.

o humano continua definindo o padrão O harness não remove você. Ele automatiza a parte repetitiva da revisão: ler registros e executar verificações a cada mudança. Você continua definindo a direção: quais grupos representam falhas reais, quais importam e onde está a barra. O que deixa de fazer é a leitura manual e repetitiva, que não acompanha o volume de produção.

nosso exemplo em andamento — o bot de suporte fundamentado em recuperação Através dos módulos 0.1→0.9 carregaremos um sistema de brinquedo para que o método leia como uma única história cumulativa, não nove truques não relacionados: um bot de suporte fundamentado em recuperação que responde perguntas de clientes a partir de uma base de conhecimento. É desse sistema que você analisará os registros. Seus modos de falha — respostas não citadas, erros silenciosos de tool-call, recusas excessivas — são aqueles que o juiz de descoberta abaixo identifica. No 0.3 você escreverá juízes para eles; no 0.5 você aplicará um gate neles; no 0.9 você conectará todo o harness em torno deles. (Um padrão, não um benchmark — você constrói e mede o seu próprio.)

antes de prosseguir — em que você apontaria um juiz de descoberta primeiro?

Uma amostra de registros de produção — entrada, saída e metadados de ferramenta ou erro —, não um conjunto de avaliação previamente selecionado. A descoberta procura entender como o sistema realmente falha em uso; um conjunto selecionado à mão esconde o modo de 40% e sobrepesa o de 3%.

Um juiz de descoberta, concretamente

Ele recebe registros, propõe rótulos para os modos de falha, atribui cada registro a um modo — ou o marca como "limpo" — e retorna a taxonomia com contagens e um exemplo por modo — a evidência que você folheará.

A ordenação é a saída: você aplica um gate no modo de 40%, não o de 3% — frequência combinada com severidade, nunca apenas contagens.

def discover_failures(traces, discovery_judge):
    labeled = []
    for t in sample(traces, n=500):          # o juiz examina o volume; você revisa o resumo
        mode = discovery_judge(t)             # {"mode": "silent_tool_error", "evidence": span}
        labeled.append(mode)
    taxonomy = cluster(labeled)               # ordenado: mode -> (count, example)
    return taxonomy                           # VOCÊ revisa isso — 12 linhas, não 10 mil registros

Agora — e apenas agora — você escolhe os modos principais e, nos próximos módulos, transforma cada um em um juiz com um veredito, evidência e um limite. A descoberta prioriza o trabalho; o harness aplica os critérios definidos.

contagens são o início, não a resposta Uma taxonomia ordenada diz a você com que frequência cada modo acontece. O próximo passo é métricas estratificadas — medir precisão e revocação por grupo, não apenas um número global — e uma análise de erros nos grupos principais: eles representam a mesma causa raiz dividida em três rótulos ou três falhas realmente distintas? Um grupo frequente ainda pode ter baixa gravidade; um raro pode causar perda de clientes. A descoberta oferece o mapa, e a estratificação ajuda a definir prioridades.

caso na prática Em um fluxo de vídeo operado por uma única pessoa, o mesmo movimento funciona: uma passagem de descoberta identifica os modos de falha que realmente recorrem — deslocamento de sincronização labial, quebras de persona — e um operador decide quais se tornam gates rígidos. Uma pessoa define o critério; um painel de juízes o aplica ao conjunto inteiro. (Este é um método, não um benchmark: use o exercício prático para construir e medir o seu.)

por que a descoberta deve ser recorrente — mudança de critério Um juiz de descoberta é ele próprio um LLM, e juízes LLM não mantêm seus critérios fixos. Shankar et al., "Who Validates the Validators?" (arXiv 2404.12272, UIST '24), documentam a mudança de critério: avaliadores baseados em LLM aplicam a rubrica de forma inconsistente e a alteram durante a anotação, afastando-se do critério que deveriam codificar. A consequência é direta: não execute a descoberta uma única vez nem confie indefinidamente na taxonomia. Repita-a periodicamente e trate os grupos ordenados como um retrato temporário.

por que agrupar falhas antes de escrever qualquer juiz?

Porque você protege primeiro o modo de falha que realmente domina o risco. Escrever juízes antes da descoberta pode otimizar uma falha presente em 3% dos casos enquanto outra, presente em 40%, continua chegando à produção. A descoberta prioriza o trabalho — e, como um juiz de descoberta também muda de critério (Shankar et al., 2404.12272), essa classificação deve ser refeita periodicamente.

um grupo reúne 40% das falhas de baixa gravidade; outro, com 3%, causa perda de clientes. Qual deve receber um gate primeiro?

Nenhuma decisão segue apenas da contagem. A descoberta lhe dá o mapa; você ainda combina frequência, gravidade e precisão/revocação por grupo para decidir o que merece um gate. As contagens são o início, não o veredito.

▶ laboratório executável

failure-discovery

Aplique um juiz de descoberta a uma pasta de registros e obtenha uma taxonomia ordenada de falhas, com contagens e exemplos. Execute-o sobre a amostra incluída e depois use seus próprios registros.

labs/failure-discovery/ · python discover.py --lang pt

pontos-chave

Mapeie falhas antes de construir juízes — proteja primeiro o modo que realmente domina o risco.
Um juiz de descoberta agrupa o conjunto inteiro; você revisa os grupos, não os registros brutos.
As contagens são apenas o início: adicione métricas por grupo, com estratificação, e faça uma análise de erros antes de decidir a quais falhas aplicar um gate.
O humano define a barra (o que é real, o que importa); os juízes a aplicam a tudo.