Harness: a camada que ninguém vê, mas que decide tudo

Quando você usa o mesmo modelo de IA em duas aplicações diferentes, digamos, Cursor e Claude Code, e percebe resultados visivelmente diferentes, a explicação geralmente não está no modelo. Está no harness.

##O que é harness, afinal?

Harness não é “mais um arquivo de tools que você controla a todo momento”. Em muitos agentes, ele nem é acessível para nós, devs curiosos.

Numa definição direta: harness é o código e a infraestrutura que envolvem a chamada ao modelo não o modelo em si responsáveis por gerenciar prompt, contexto, ferramentas, memória e o momento de parar.

Ele funciona como uma espécie de filtro: trata os inputs que chegam ao modelo e os outputs que saem dele, visando tanto a qualidade do que o agente recebe quanto a qualidade da resposta que devolve.

Pense no harness como uma estrutura de suporte: ela orienta em que direção a LLM deve seguir, quais caminhos deve tomar e, principalmente, o momento em que deve parar de procurar e devolver uma resposta.

##De onde isso veio?

O harness nasceu da desconfiança no código e nas respostas gerados por IA. Modelos de linguagem puros, sem essa camada de suporte, tendem a alucinar chamadas de ferramenta, perder o fio da meada em tarefas longas ou simplesmente não saber quando parar de tentar novamente.

O harness surgiu como resposta a isso: engenharia de confiabilidade construída em cima de um componente que, por natureza, é probabilístico.

Essa camada de suporte mitiga esses problemas e melhora os resultados do uso de IA. De quebra, abriu espaço para um segundo tipo de harness, que fica na mão do usuário final.

##As duas camadas de harness

##System / Application Harness

É o harness “de fábrica”, provido e manipulado pela empresa por trás do modelo — ou pela aplicação que você está usando.

Inclui elementos como:

• Injeção de system prompt;
• Filtros de segurança;
• Loop de chamadas de ferramentas;
• Gerenciamento e compactação de contexto;
• Critério para considerar uma tarefa concluída.

##User / Dev Harness

É toda a camada que nós, programadores, construímos por cima do modelo: tools, skills, prompt engineering, contexto, arquivos como AGENTS.md, memória persistente, subagentes e hooks.

Se você já criou uma skill com múltiplas passadas de revisão, um CLI que gera contexto para IA consumir ou um servidor MCP com camadas de conhecimento, você já está, na prática, escrevendo harness.

##Por que o mesmo modelo se comporta diferente em apps diferentes?

Isso explica por que você usa o mesmo modelo em aplicações distintas e recebe resultados diferentes: o harness muda.

Uma aplicação pode ter um harness mais refinado, com memória e observabilidade; outra pode ter pouco suporte ao redor do modelo.

O mesmo modelo de base rodando no Claude.ai, no Claude Code e em uma IDE como o Cursor pode produzir resultados diferentes. Não porque o modelo mudou, mas porque cada harness decide de forma diferente como injeta contexto, quais ferramentas expõe, como trata erros de chamadas de ferramenta e quando decide parar de iterar.

##Os componentes do harness

Para visualizar essa camada como um sistema, e não como um conceito abstrato, podemos dividi-la em algumas partes:

• Tratamento de input: sanitização, formatação, injeção de contexto e de system prompt;
• Orquestração de ferramentas: o loop de decisão entre chamar uma ferramenta, ler o resultado e decidir o próximo passo;
• Gerenciamento de memória e contexto: compactação, resumo e RAG;
• Critério de parada: quando o harness considera que a tarefa está concluída;
• Guardrails de saída: filtros de segurança aplicados à resposta final.

##Por que isso importa para você, dev?

Entender harness muda a forma como você depura um agente que “não funciona”. O problema pode não estar no modelo, mas no harness ao redor dele.

Também muda a forma como você constrói suas próprias skills e tools, porque, goste ou não, você já está escrevendo harness todos os dias.