Harness de IA: o que é, quando construir o seu e por que a maioria falha

O modelo de IA é o motor. Mas ninguém dirige um motor: dirige-se um carro, com volante, freio, painel e cinto de segurança. Harness é o carro. É tudo o que existe em volta do modelo para que ele trabalhe de verdade, dentro de limites, e com alguém conferindo o resultado.

O termo virou moda, e por isso mesmo virou vago. Este artigo é a base de uma série: o que um harness realmente contém, a diferença entre o que já vem pronto e o que você constrói, quando vale a pena construir, e o erro que vejo repetido nas empresas — montar o harness e esquecer dele.

Onde as empresas mais pecam

Antes da teoria, o erro mais comum — e o mais caro. As empresas costumam errar de três formas ao mesmo tempo:

• Superestimam o harness. Tratam como produto que se instala e resolve: "montamos os agentes, agora a qualidade está garantida". Não está. Um harness é um ponto de partida, não uma entrega.
• Subestimam a manutenção e o amadurecimento. Ninguém é dono dele, ninguém tem tempo reservado para ajustá-lo, e cada falha real que poderia virar uma regra melhor vira só mais um incidente esquecido.
• Querem tudo muito rápido. Copiam uma estrutura pronta, ligam todos os agentes de uma vez e não medem nada. O resultado é qualidade reduzida, o time perde a confiança no processo e o abandona.

Um harness maduro não nasce de uma sprint. Ele é resultado de ciclos repetidos: usar, observar onde falhou, aprender, ajustar. Isso leva meses, não semanas — e só acontece se alguém tiver o trabalho de fazer.

A anatomia de um harness

Um harness não é uma coisa só. São camadas, e nem toda organização precisa de todas. Cada uma responde a uma pergunta diferente:

A última camada é o assunto do artigo sobre multiagente. Repare que ela é a única realmente opcional: dá para ter um ótimo harness só com as sete primeiras.

Dois harnesses: o da ferramenta e o seu

Existem dois níveis de harness, e eles não competem — se complementam:

O harness próprio serve a fins bem específicos: impor padrões do time (arquitetura, bibliotecas proibidas, convenções), garantir verificações que não podem depender de boa vontade (build, teste, revisão independente), carregar conhecimento do domínio (o que já deu errado, o que já foi decidido) e tornar a qualidade mensurável.

Quando vale construir o seu

Nem todo projeto precisa de um harness próprio. Um checklist honesto:

Se você marcou "não vale" em mais da metade, comece pelo básico do próximo tópico e só evolua quando o problema aparecer.

Níveis de maturidade

Um harness cresce por níveis. A regra é subir um nível só quando o problema do nível atual aparecer e se repetir — nunca por antecipação.

A maioria dos times ganha muito entre os níveis 1 e 2, e pouca gente precisa chegar ao 4. Meu próprio harness está no nível 4 porque tenho um motivo específico (medir o efeito de cada mudança). Ter chegado lá não é mérito; é custo que aceitei pagar.

O que entra no arquivo de regras

O nível 1 é o mais barato e o mais mal aproveitado. Um arquivo de regras ruim é longo, genérico e ignorado. Um bom é curto e cada linha existe por um motivo.

Um teste simples para cada linha: "que erro real isso evita?" Se não há resposta, a linha é ruído, e ruído custa: tudo que fica sempre carregado é pago em toda chamada e disputa espaço com o que importa.

O custo que não aparece no diagrama

Montar o harness é a parte cara que todo mundo enxerga. A parte cara que ninguém enxerga é mantê-lo.

Um harness é um conjunto de compensações: cada regra, cada gate, cada passo obrigatório existe porque, numa certa versão de modelo e de ferramenta, algo dava errado sem ele. Quando o modelo evolui, parte dessas compensações deixa de ser necessária. Quando a ferramenta ganha um recurso nativo, parte vira duplicação. E o harness, parado, continua aplicando tudo isso:

• Passos obrigatórios que o modelo novo faria melhor sozinho. Quebrar em micro-tarefas, reforçar contexto, decompor o raciocínio: andaimes que ajudavam um modelo mais fraco e agora só limitam um mais capaz.
• Instruções que competem com recursos novos da ferramenta. Você construiu à mão o que a plataforma passou a oferecer pronto, e os dois convivem em conflito.
• Instruções sempre carregadas que só crescem. Cada incidente vira uma regra nova; nenhuma regra é removida; o contexto pago em toda chamada engorda.
• Premissas congeladas. "Spec formal sempre" foi certo para o modelo de ontem; para o de hoje, pode ser cerimônia.

Sinais de que isso já começou:

Uma rotina de manutenção que funciona

• Trate o harness como produto, não como projeto. Projeto acaba; produto tem dono, backlog e cadência de revisão.
• Reavalie a cada troca de modelo ou ferramenta. É o gatilho natural. Rode os mesmos cenários com e sem cada componente e compare (o artigo sobre medição mostra como).
• Remova com medição, nunca por sensação. Num branch, medir antes e depois, decidir. "Acho que não ajuda mais" não é dado.
• Pergunte: "se eu montasse isso hoje, com o modelo atual, ficaria igual?" Se a resposta é não, você está mantendo um museu.
• Registre o porquê de cada regra e gate. Componente sem motivo escrito não pode ser reavaliado: só mantido por medo ou removido por chute.
• Reserve tempo. Se manter o harness não está na agenda de ninguém, ele não vai ser mantido.

Por onde começar (sem construir tudo de uma vez)

Se ficou com a impressão de que é preciso montar o sistema inteiro, não é. Do mais barato ao mais caro:

1. Comece pelo harness da ferramenta e um arquivo de regras do projeto. Registre ali a arquitetura, os padrões e o que a IA nunca deve fazer. Só isso já elimina uma parte grande dos erros de "IA sem contexto".
2. Adicione verificações automáticas. Build e testes rodando de verdade, com o resultado guardado: não a palavra de quem implementou.
3. Adicione um crítico só de leitura e um único gate, depois da spec. É o ponto mais barato para pegar erro: corrigir texto custa uma fração de corrigir código.
4. Só então acrescente o resto: mais papéis, revisão de código independente, métricas, base de conhecimento.

E uma regra para cada peça que você adicionar: escreva o problema que ela resolve e a data em que vai reavaliá-la.

As armadilhas de virar bandeira

• Copiar a estrutura sem entender o porquê de cada gate. Vira teatro de processo: os nomes estão lá, a disciplina não.
• Empilhar camadas de revisão sem verificação real. "Agente revisor" e "agente crítico" não valem nada se ninguém checa build, teste ou evidência.
• Usar o processo completo para qualquer mudança. Passar uma correção de uma linha por todas as fases não é rigor, é desperdício.
• Achar que o processo substitui entender o problema de negócio. Nenhum gate resolve requisito mal levantado.
• Configurar uma vez e esquecer. A armadilha desta série inteira, e a mais silenciosa.

Um cenário comum: o time adota "harness" como palavra de ordem, monta agentes com nomes bonitos, e nas primeiras semanas a entrega até parece mais organizada. Meses depois, ninguém lembra por que o gate de crítica existe, ele vira etapa que todo mundo aprova sem ler, e o processo que devia pegar erro cedo só atrasa a entrega — pior que não ter processo, porque agora há falsa sensação de segurança.

Para estudar mais

• Guia da Anthropic sobre agentes: Building effective agents. Defende começar com a solução mais simples possível e só aumentar a complexidade quando for necessário, princípio que vale para o harness também.
• Documentação de subagentes do Claude Code: Create custom subagents. Mostra como um agente especializado, com contexto e ferramentas próprios, é configurado na prática.
• Termos para pesquisar: spec-driven development, agent evals, context engineering.

Mini-glossário