O que é harness engineering: como tornar o agente de IA uma ferramenta de trabalho

O que é harness engineering, em poucas palavras

Harness engineering é a disciplina de engenharia que trata de como construir, em volta de um modelo de linguagem, um ambiente no qual ele realiza trabalho real de forma confiável. A palavra harness significa «arreio», aquela estrutura que conduz a força de um animal. O modelo é muito capaz, mas por si só não sabe para onde ir, quais ferramentas usar nem quando parar. O harness é o que direciona essa força.

A formulação mais curta é esta:

Agente = Modelo + Harness

O modelo são os pesos e a capacidade de raciocinar e gerar texto ou código. O harness é todo o resto: as instruções do sistema e arquivos como CLAUDE.md ou AGENTS.md, o conjunto de ferramentas (shell, edição de arquivos, servidores MCP), o sandbox onde os comandos são executados, os arquivos de estado que sobrevivem entre sessões e os testes, linters e hooks que avisam o agente quando ele erra. Se você remover o harness, sobra apenas uma janela de chat que responde com texto.

Por que o mesmo agente parece um especialista em um projeto e um iniciante em outro

Essa situação é comum: em um repositório o agente trabalha como um desenvolvedor experiente; em outro, se perde, esquece as decisões da véspera e declara «pronto» uma funcionalidade que não roda. A reação natural é trocar por um modelo mais novo, mas isso costuma não resolver, porque o modelo é o mesmo nos dois casos. A diferença está no ambiente.

É aqui que começa a ideia central do harness engineering: o agente não está quebrado, quem está quebrado é o que o cerca. Se o agente não consegue rodar os testes, ele não tem como testar. Se nada registra o que ele já tentou, ele não se lembra. Se nenhuma verificação lhe diz que a funcionalidade está quebrada, ele não tem como saber. São defeitos de construção, não «personalidade» do modelo, e podem ser corrigidos de forma sistemática.

Sintomas típicos de um harness ruim

• Cada nova sessão começa consertando o ambiente: dependências erradas, banco que não sobe, variáveis ausentes.
• O agente repete soluções já descartadas, porque não lembra da sessão anterior.
• A regra está escrita nas instruções, mas o agente a ignora.
• «Os testes estão verdes», mas a funcionalidade está quebrada, porque os testes verificavam outra coisa.
• O agente começa três tarefas ao mesmo tempo e não termina nenhuma.

Do que é feito um harness: cinco subsistemas

Um erro comum é considerar o harness um arquivo com um prompt. Na prática, são cinco mecanismos, e cada um quebra de um jeito diferente.

Instruções

As instruções respondem à pergunta: o agente vai encontrar a regra certa? Um bom arquivo de entrada é um mapa, não um livro-texto: um sumário curto com os comandos de verificação e as restrições rígidas, com os detalhes em documentos separados que o agente abre quando precisa. Boas instruções definem invariantes («todas as consultas SQL são parametrizadas»), e não dizem linha por linha como implementar.

Ferramentas

O agente só consegue verificar o que tem acesso. Se ele não consegue rodar o linter, uma regra do tipo «rode o linter antes do commit» não funciona. As ferramentas são oferecidas pelas capacidades nativas do agente (ler e editar arquivos, executar comandos) e pelo MCP, um protocolo que dá acesso a bancos de dados, navegadores e gerenciadores de tarefas.

Ambiente

O ambiente é onde o agente executa os comandos. Ele deve subir com um único comando, ser igual de uma sessão para outra e limitar o estrago de um erro: um sandbox sem acesso à produção, uma branch ou cópia de trabalho separada, e a possibilidade de voltar ao estado inicial em um minuto.

Estado

O modelo não tem memória entre sessões: tudo que não foi escrito no repositório desaparece junto com a janela de contexto. Por isso, o objetivo, o que já foi feito, as decisões tomadas, os becos sem saída e o próximo passo precisam morar em arquivos. O teste é simples: abra uma sessão nova e diga ao agente apenas «continue». Veja se ele começa a trabalhar ou pergunta o que deve fazer.

Feedback

Os laços de feedback são o subsistema mais importante. Sem eles, o agente é o único juiz do próprio trabalho e, com toda honestidade, acredita que a tarefa está concluída. Testes, checagem de tipos, linter, um hook executado a cada edição e um cenário end-to-end no navegador devolvem ao agente um sinal vermelho enquanto o erro ainda é barato de corrigir.

O harness é um circuito, não uma lista

Os cinco subsistemas funcionam como um circuito fechado. O modelo lê as instruções, age pelas ferramentas no ambiente, altera o repositório, e a verificação confere o resultado. O vermelho volta ao modelo para correção; o verde é registrado no estado. O estado, por sua vez, atualiza as instruções para a próxima sessão.

instruções → modelo → ferramentas → ambiente → alterações
                ↑                                  ↓
                └── vermelho ── verificação ───────┘
                                    ↓ verde
                                estado → (próxima sessão)

Remova qualquer seta e o circuito se rompe naquele ponto. Sem verificação, o agente não percebe o erro. Sem estado, a próxima sessão começa com arqueologia em vez de trabalho. Por isso, investir em um subsistema não compensa a lacuna de outro: um AGENTS.md de cinco páginas não substitui testes que não existem.

Harness engineering versus engenharia de prompt e de contexto

Esses conceitos estão aninhados uns nos outros; não competem entre si.

A engenharia de prompt é parte do subsistema de instruções. A engenharia de contexto abrange instruções e estado: o que o agente enxerga a cada momento. O harness engineering acrescenta o que nem cabe na janela de contexto: acessos, sandbox, testes, hooks e processo de trabalho. Nenhum prompt, por melhor que seja, ajuda um agente que fisicamente não consegue rodar os testes.

Por que existe o harness: a matemática das tarefas longas

Intuitivamente, um modelo que acerta 95% dos passos parece quase perfeito. Mas a tarefa de um agente tem muitos passos, e os erros se acumulam. Se os passos são independentes, a probabilidade de passar por todos sem erro é o produto das probabilidades:

0,95 ^ 10 ≈ 0,60
0,95 ^ 20 ≈ 0,36
0,95 ^ 50 ≈ 0,08

Ou seja, só cerca de 60% das execuções chegam ao décimo passo sem nenhum erro, e menos de uma em dez chega ao quinquagésimo. Elevar a precisão do modelo para 97% é caro e não depende de você. Já detectar o erro no próprio passo em que ele aconteceu e devolvê-lo ao agente para correção é o trabalho do harness. O laço de feedback transforma a cadeia «um erro puxa o seguinte» em uma sequência de passos curtos e corrigíveis.

Exemplo: o mesmo agente em dois repositórios

Tarefa: adicionar um desconto por cupom a um backend de pagamentos em FastAPI.

Sem harness

O agente lê alguns arquivos, escreve uma função de cálculo do desconto e um teste unitário que verifica apenas essa função. O teste passa, e o agente responde «pronto». Ele não sabia que o total do pedido é calculado em outro módulo e não conseguiu subir o banco para executar o fluxo de compra completo. Um dia depois descobre-se que o desconto não é aplicado no carrinho.

Com harness

Na raiz do repositório há um AGENTS.md de algumas dezenas de linhas: como subir o ambiente, quais comandos de verificação são obrigatórios e onde está descrita a arquitetura de pagamentos. O ambiente sobe com docker compose up -d. Há um arquivo de plano com critério de conclusão: «o cenário E2E de compra com cupom passa». Após cada alteração, um hook roda o linter e a checagem de tipos, e antes de encerrar o agente é obrigado a rodar o teste E2E.

# AGENTS.md (trecho)
## Verificação — obrigatória antes de dizer «pronto»
make lint        # ruff + mypy
make test        # pytest, unitários e de integração
make e2e         # cenário de compra

## MUST
- Valores monetários em centavos (int), nunca em float
- Todas as consultas SQL são parametrizadas
- Não alterar migrations já aplicadas em produção

O modelo é o mesmo. Mas agora o agente encontra o módulo do total pelo mapa do projeto, o teste E2E falha na primeira tentativa, o agente percebe que o desconto não chegou ao carrinho, corrige e só então relata, com o E2E verde. A diferença no resultado é inteiramente obra do harness.

Por onde começar

1. Descreva como o agente verifica o próprio trabalho: um a três comandos que ele é obrigado a rodar. O feedback é o que mais rende, então comece por ele.
2. Torne o ambiente reproduzível: sobe com um comando e pode ser revertido rapidamente.
3. Crie um arquivo de estado: objetivo, o que foi feito, decisões e becos sem saída, próximo passo.
4. Reduza as instruções a um mapa: comandos de verificação, restrições rígidas e links para os documentos detalhados.
5. Mantenha um diário de falhas do agente: a cada falha, anote qual subsistema a permitiu. O diário mostra o que consertar em seguida.

Uma prática útil é avaliar cada um dos cinco subsistemas de 1 a 5, gastar meia hora no mais fraco e executar o mesmo conjunto de tarefas típicas antes e depois. Assim, as melhorias do harness se tornam mensuráveis, e não uma questão de impressão.

Conclusão

Harness engineering não é trabalho sobre o modelo, e sim sobre tudo o que o cerca: instruções, ferramentas, ambiente, estado e laços de feedback. A confiabilidade do agente é determinada pelo elo mais fraco desse circuito, por isso trocar de modelo raramente resolve a instabilidade, enquanto acrescentar um teste ou um arquivo de plano costuma resolver. Todos os cinco subsistemas e a montagem completa do harness são explicados na prática no curso de harness engineering.