Como medir se o seu harness funciona

Você montou regras, agentes e gates. Três meses depois, alguém pergunta: isso está ajudando? Se a resposta é "acho que sim", você tem um problema, porque um harness sem medição não consegue ser melhorado com segurança nem simplificado com coragem. E, como mostrei no artigo sobre harness, o custo de manter é justamente o que faz um harness envelhecer mal.

Este artigo mostra como medir em três camadas, como montar uma versão mínima sem infraestrutura, e onde as métricas enganam.

As três camadas

Cada camada mede uma coisa diferente, em um momento diferente do processo:

Camada 1: a task fecha com número

Cada task de implementação gera um Quality Score em cinco eixos, cada um com semáforo. Eixo vermelho bloqueia: a task não é marcada como concluída, mesmo que o código "pareça" pronto.

Eixo que não se aplica (um módulo sem frontend, por exemplo) fica fora da tabela e da média, para não distorcer o resultado.

Semáforo: verde a partir de 90, amarelo a partir de 75, vermelho abaixo disso. Verde e amarelo prosseguem; vermelho volta para implementação e, passando do teto de tentativas, escala para o humano.

O que torna isso útil é que o número não depende de quem implementou concordar que está bom. Um detalhe de engenharia que vale copiar: os limites do semáforo vivem num arquivo de configuração, não espalhados em prompts. Quando o texto de uma regra e a configuração divergem, a configuração vence. Assim você ajusta um número num lugar só.

Camada 2: a clareza do texto entra na conta

Essa foi a que mais me surpreendeu. Dá para pontuar a clareza de uma spec ou de um design antes de existir uma linha de código, com um Assertiveness Score de três partes:

O componente de maior peso é o que mais ensina. Veja termos que quase sempre escondem uma decisão não tomada:

Um exemplo do antes e depois:

ANTES:  O sistema deve validar o CNPJ quando possível e tratar erros adequadamente.

DEPOIS: O sistema deve validar o CNPJ no cadastro de fornecedores.
        - Aceitar com e sem máscara (12.345.678/0001-95 e 12345678000195).
        - Rejeitar CNPJ com dígitos verificadores inválidos, com a mensagem
          "CNPJ inválido".
        - Se o CNPJ já existir, devolver o erro "CNPJ já cadastrado" sem
          gravar nada.

A versão "antes" parece razoável e passaria numa leitura rápida. Tem três decisões escondidas, e cada uma seria adivinhada pelo próximo agente, ou pelo próximo desenvolvedor humano. Pontuar o texto pega esse problema na fase mais barata.

Camada 3: o próprio harness é avaliado

A camada que fecha o ciclo. Como saber se uma mudança no harness (uma skill nova, um hook removido, uma fase reordenada) ajudou? Um conjunto fixo de cenários representativos roda antes e depois da mudança, e cada cenário recebe um score único de 0 a 1:

Repare que custo é um eixo. Um harness que entrega perfeito gastando dez vezes mais do que o pedido justifica está reprovado por outro motivo, e isso é fácil de esquecer quando só se olha a qualidade.

Outro ponto de engenharia: parte de cada eixo é checagem determinística de script (o build passou, o arquivo de evidência existe, quantos agentes foram disparados), e só a parte subjetiva pede julgamento. Separar as duas coisas reduz o custo de avaliar e fecha a porta para um avaliador "relevar" uma violação objetiva porque o resto pareceu bom.

Evidência: a palavra de quem fez não conta

Em modo estrito (implementação e correção de bug), a validação exige evidência real de build e teste: um arquivo gerado pela execução, não a frase "eu rodei e passou". Em revisão, refatoração, documentação e análise, a evidência é opcional. Escolher o rigor conforme o tipo de mudança evita exigir prova onde ela não faz sentido.

Uma versão mínima, em uma tarde

Você não precisa de 21 cenários nem de infraestrutura para começar. O caminho mais curto:

1. Escolha 5 tarefas reais que o seu time já fez, de tamanhos diferentes. Guarde o pedido original de cada uma.
2. Defina três perguntas por tarefa: o build passou? Cobriu o que foi pedido sem escopo extra? Quantos agentes e quanto tempo gastou?
3. Rode as 5 tarefas com o harness atual e anote as respostas. Essa é a sua linha de base.
4. Mude uma coisa (remova uma regra, um gate, um papel) e rode as mesmas 5 tarefas de novo.
5. Compare. Se a qualidade se manteve e o custo caiu, a peça era peso morto. Se a qualidade caiu, ela ajudava.

Faça a mudança num branch, nunca direto no que o time usa. E mude uma coisa por vez: se mudar três, não saberá qual causou o efeito.

O que os números não dizem

Métrica ajuda a sinalizar padrão, mas não decide sozinha se algo está pronto. Os limites que preciso deixar claros:

• Poucos cenários não provam nada com rigor de laboratório. Vinte e um cenários apontam direção; não têm poder estatístico para afirmar que uma mudança "melhorou 3%". Servem como diagnóstico, o suficiente para transformar "acho que" em "medi e".
• Score alto não garante que o requisito faz sentido de negócio. Uma spec clara pode descrever a coisa errada. Nenhuma pontuação de texto substitui entender o problema.
• Quando a métrica vira meta, deixa de ser boa métrica. É a lei de Goodhart: se o time passa a otimizar o número em vez do resultado, o número deixa de refletir a qualidade. Sinal de alerta: o score sobe e a percepção de qualidade não acompanha.
• A parte subjetiva continua subjetiva. Se um modelo de IA avalia a saída de outro, ele traz vieses próprios. Use-o como apoio, e mantenha a checagem determinística como âncora.

Para estudar mais

• Termos para pesquisar: agent evals, LLM as a judge (e seus vieses), golden dataset, regression testing para prompts.
• O princípio de começar simples do guia Building effective agents inclui um recado direto sobre avaliação: comece com prompts simples e otimize com avaliação abrangente, adicionando complexidade só quando as soluções mais simples falharem.