![Imagem de capa de [Design de agentes #1] O que é engenharia de harness? O que vem depois do prompt](/assets/images/posts/e5b7d384-3107-41fb-a62e-34369bc15f27/harness-engineering-1.jpg)
Mesmo usando o mesmo modelo, a qualidade dos resultados varia entre as equipes. Em uma, a IA faz uma refatoração completa; em outra, uma pessoa precisa reescrever até as correções simples.
A diferença não está no texto do prompt. Está no ambiente de execução que envolve o modelo—ou seja, no harness.
Em uma frase, engenharia de harness é projetar todo o loop em que o modelo usa ferramentas, tem seus resultados validados e trabalha até concluir a tarefa. Se engenharia de prompts é “como se comunicar bem”, engenharia de harness é “como montar um local de trabalho que faça o trabalho bem”.
Neste artigo, vamos explicar exatamente o que é um harness, quais são seus componentes e como avaliar um bom harness.
Vamos começar pelo resumo dos pontos principais.
- Um harness é o loop de execução que envolve o modelo. Seus componentes são ferramentas, permissões, gerenciamento de contexto e feedback.
- O desempenho do agente é determinado por inteligência do modelo × qualidade do harness.
- O ponto central de um bom harness é um loop de feedback que permite ao modelo verificar seus próprios resultados.
- A essência de agentes de programação como Claude Code e Cursor é justamente o harness.
O que exatamente é um harness?
Originalmente, harness significava o arreio usado em um cavalo. Ele não aumenta a força do cavalo; converte essa força em trabalho útil, como puxar uma carroça.
O termo test harness vem da mesma linhagem.
Um harness de LLM funciona da mesma forma. Mantém o modelo—a inteligência—inalterado e se refere a todo o software que o envolve para transformar essa inteligência em trabalho real.
Especificamente, inclui coisas como estas.
- Camada de ferramentas: funções que o modelo pode chamar, como ler e gravar arquivos, executar o shell e pesquisar.
- Camada de permissões: políticas sobre o que perguntar e executar e o que aprovar automaticamente.
- Camada de contexto: o que mostrar ao modelo, o que ocultar e quando resumir.
- Camada de loop: estrutura repetitiva que transforma resultados de ferramentas na próxima ação, além das condições de encerramento.
Chamamos Claude Code ou Cursor de “ferramentas de programação com IA”, mas o modelo em si é o mesmo modelo por trás da API. A essência do produto é o harness.
Desempenho = Modelo × Harness
Já são comuns os casos em que as pontuações de benchmark divergem muito com o mesmo modelo. Nos rankings de benchmarks de agentes, a taxa de sucesso pode variar dezenas de pontos percentuais conforme o harness, mesmo com modelos idênticos.
O motivo é simples. As tarefas de um agente são cadeias de dezenas de chamadas de ferramentas, e o harness interfere em todas as etapas.
| Quando o harness é ruim | Quando o harness é bom |
|---|---|
| Despejar todo o resultado da ferramenta no contexto | Resumir e transmitir apenas o necessário |
| Repetir a mesma tentativa mesmo após uma falha | Usar a mensagem de erro como entrada da próxima tentativa |
| Considerar a tarefa concluída com base na afirmação do modelo | Validar com testes e builds e encerrar somente quando passarem |
Modelos cometem erros probabilisticamente. O papel do harness não é eliminar erros, mas fazer com que sejam detectados na etapa de validação e corrigidos pelo próprio modelo.
Três condições de um bom harness
Na prática, a qualidade do harness pode ser resumida em três condições.
Primeiro, um loop de feedback verificável. Se o modelo alterou o código, é preciso executar os testes e mostrar os resultados a ele.
Assim como não confiamos em código escrito sem compilá-lo, um agente sem feedback apenas acumula autoconfiança. Por isso, bases de código com bons testes são onde a adoção de agentes tem maior impacto.
Segundo, gerenciamento do orçamento de contexto. A janela de contexto é finita, mas os resultados das ferramentas chegam sem limite.
Cortar saídas longas, resumir conteúdo antigo e isolar tarefas de exploração em subagentes são responsabilidades do harness.
Terceiro, um caminho seguro para falhas. Políticas de permissões e sandbox devem definir o “limite em que é possível se recuperar de um erro”.
Por exemplo, aprovar automaticamente operações reversíveis e pedir confirmação humana apenas para as destrutivas.
Relação com a engenharia de prompts
Isso não significa que engenharia de prompts tenha se tornado inútil. Ela apenas atua em outra camada.
Um prompt otimiza uma única solicitação. Um harness otimiza um loop de dezenas de solicitações consecutivas. Escrever o system prompt passa a ser um subconjunto do design do harness.
O centro de atenção mudou de “O que devemos dizer?” para “Que ambiente devemos oferecer?”. Quanto melhores os modelos, mais forte essa tendência fica. As instruções podem ser mais curtas, enquanto o valor das ferramentas e dos loops de validação aumenta.
Resumo
Se o resultado do agente decepciona, verifique o harness antes de ajustar o prompt. O modelo tem como conferir os resultados? O contexto está cheio de ruído? A falha alimenta a próxima tentativa?
No próximo artigo, vamos abordar engenharia de contexto, que investiga a fundo a camada de contexto.