O que é Harness Engineering? Projetando a camada ao redor do LLM na era dos agentes de IA

Harness engineering é um termo que se espalhou em fevereiro de 2026. Em 5 de fevereiro de 2026, Mitchell Hashimoto (criador do terminal Ghostty e cofundador da HashiCorp) usou o nome para um hábito: toda vez que um agente erra, você constrói uma solução para que ele nunca mais cometa aquele erro. Seis dias depois, a OpenAI colocou o termo no título de um relato da equipe do Codex. A Anthropic já vinha publicando projetos da estrutura em volta de agentes de longa duração sob o nome de "harness". Se em 2025 se dizia que depois dos prompts vinha a engenharia de contexto, o harness engineering cuida da camada ainda mais externa.

Este artigo expõe o que harness engineering realmente é, como se diferencia do prompt engineering e da engenharia de contexto, os seis componentes que formam um harness, harnesses reais publicados pela OpenAI e pela Anthropic, um checklist prático de design e uma comparação das principais ferramentas de hoje — a base que você precisa se leva a sério usar ou construir agentes de IA.

1. O que é Harness Engineering?

"Harness" originalmente se refere ao arreio e à montaria usados em um cavalo — o equipamento que canaliza a força do animal na direção que você quer. O termo em IA funciona exatamente como a mesma metáfora: o conjunto completo de equipamentos que coloca um LLM poderoso, mas indomado, para fazer trabalho produtivo.

Concretamente, isso inclui:

• Ferramentas: operações de arquivo, busca na web, execução de código — os meios pelos quais o LLM pode agir.
• Gestão de contexto: a estratégia para o que entra no prompt e o que é comprimido ou descartado.
• Sistemas de memória: conhecimento persistente e preferências do usuário que sobrevivem entre sessões.
• Agent loop: o ciclo perceber → raciocinar → agir → observar.
• Guardrails: permissões, sandbox, Hooks, fluxos de aprovação.
• Formato de saída: markdown, JSON, citações, streaming.

Projetar tudo isso em conjunto é o que chamamos de harness engineering. Em vez de treinar ou melhorar o próprio LLM, é o ofício de elevar a utilidade no mundo real ao engenheirar tudo que está ao redor do LLM. Claude Code, Cursor, Devin, Codex CLI — todos rodam aproximadamente sobre os mesmos modelos, e ainda assim seu comportamento e desempenho divergem fortemente por causa da diferença em seus harnesses.

Para saber onde começa e termina a palavra "harness", Birgitta Böckeler, da Thoughtworks, resumiu bem no martinfowler.com (2 de abril de 2026): o harness é tudo em um agente, exceto o modelo — ou seja, Agent = Model + Harness. A Anthropic usa a mesma palavra para o próprio serviço em nuvem: descreve o Claude Managed Agents como um harness de agente configurável.

2. Harness Engineering vs Prompt Engineering

Prompt engineering não desapareceu — mas o escopo é fundamentalmente diferente.

Se prompt engineering é o ofício de "o que dizer ao LLM", harness engineering é o ofício de "o que dar ao LLM e como operá-lo". Os dois não competem — eles são empilhados em camadas. O prompt é apenas um componente dentro do harness.

O outro termo que costuma ser confundido é engenharia de contexto. Em um texto de 29 de setembro de 2025, a Anthropic a chamou de evolução natural do prompt engineering. Böckeler descreve a construção do harness de um agente de programação como uma forma específica de engenharia de contexto. Juntos, eles se encaixam: prompt (o que você diz) ⊂ contexto (o que o modelo vê) ⊂ harness (o que ele recebe, como o trabalho é verificado e como ele é interrompido). O que é próprio do harness é a parte que verifica os resultados de forma mecânica e devolve as falhas ao agente — linters e testes, por exemplo.

3. Os 6 componentes de um harness

1. Tool Use (uso de ferramentas)

O meio pelo qual o LLM age sobre o mundo: ler e escrever arquivos, executar código, buscar na web, chamar APIs. Erre na interface da ferramenta — nomes, argumentos, valores de retorno — e o LLM não conseguirá usá-la corretamente. Concretamente:

• Nomes inequívocos baseados em verbos (ex.: read_file).
• Argumentos obrigatórios vs. opcionais explícitos, com valores padrão.
• Mensagens de erro estruturadas em caso de falha (diga ao modelo o que fazer em seguida).
• Avisos explícitos em operações com efeitos colaterais (destrutivas).

2. Gestão de contexto

A atenção do LLM é finita — o que você mostra a ele determina o que ele diz. Concretamente:

• Filtragem por relevância: puxe apenas as partes relevantes para a tarefa, não arquivos inteiros.
• Compactação: resuma conversas longas para retê-las.
• Integração com RAG: busque o necessário via busca vetorial.
• Cache: reduza o custo em system prompts repetidos usando ferramentas como o prompt cache da Anthropic.

Relacionado: O que é RAG?

3. Sistema de memória

Reter conhecimento entre sessões. O CLAUDE.md do Claude Code, o .cursor/rules do Cursor e o AGENTS.md do Codex são todos exemplos de memória de projeto. Além disso:

• Memória de curto prazo: histórico recente da conversa.
• Memória de longo prazo: perfil do usuário, decisões anteriores.
• Conhecimento factual: bases de conhecimento específicas de domínio.

4. Agent loop

O núcleo que faz um "agente de IA" realmente funcionar. A forma básica é o ciclo perceber → raciocinar → agir → observar:

1. Receber o objetivo do usuário.
2. Analisar o estado atual (coletar informação com ferramentas, se preciso).
3. Planejar a próxima ação.
4. Agir via uma ferramenta.
5. Observar o resultado; verificar se o objetivo foi alcançado.
6. Repetir, se não; encerrar, se sim.

Quão inteligente seu agente fica depende de você embutir ou não replanejamento, autocrítica e decomposição de subobjetivos.

5. Guardrails

Os mecanismos que evitam comportamento descontrolado. Como aborda Por que a IA ignora suas regras .md, impor o comportamento pelo ambiente é muito mais confiável do que pedir educadamente em prosa:

• Modo de aprovação: uma pessoa confirma antes que operações perigosas rodem (ex.: as permissões do Claude Code e os modos de aprovação do Codex CLI).
• Sandbox: restringir acesso a sistema de arquivos e rede.
• Hooks: verificações arbitrárias antes e depois das chamadas de ferramentas.
• Rate limiting: minimizar danos se algo sair dos trilhos.

6. UX de saída

Apresentar resultados em uma forma que o usuário consiga entender e verificar. Renderização em markdown, citação de fontes, blocos de código com syntax highlighting, saída em streaming, raciocínio visível (thinking), saída estruturada (JSON), e por aí vai. Produzir a "resposta certa" não basta — é trabalho do harness entregá-la em uma forma em que o usuário possa confiar e verificar.

4. Por que Harness Engineering, e por que agora?

Três forças estão impulsionando o aumento de interesse no trabalho de harness.

1. Ficou demonstrado que o mesmo modelo dá resultados muito diferentes conforme o que o envolve. Em um experimento que a Anthropic publicou em 24 de março de 2026, o mesmo modelo Claude Opus recebeu, em uma única frase, o pedido de criar um editor de jogos retrô 2D. Um agente sozinho terminou em 20 minutos por US$ 9, mas a fase que ele criou não podia ser jogada. Um harness dividido em planejador, gerador e avaliador rodou por 6 horas e custou US$ 200 — e entregou um jogo em que dava para mover o personagem de verdade (a física ainda era rústica). O custo foi mais de 20 vezes maior, mas a diferença de qualidade também. Escolher entre qualidade e custo passou a ser tanto uma decisão de harness quanto de modelo.

2. Problemas que os prompts sozinhos não resolvem estão se acumulando. "Ferramentas demais, o modelo escolhe a errada." "O contexto está tão lotado que o sinal importante fica enterrado." "Em tarefas longas, o agente perde o fio da meada no meio do caminho." Estes não são problemas que você resolve com uma redação mais esperta em um único turno — são problemas de design.

3. O próprio trabalho do engenheiro começou a mudar. A equipe do Codex da OpenAI relatou ter construído um produto interno por cinco meses sem nenhuma linha de código escrita à mão, chegando a cerca de um milhão de linhas e cerca de 1.500 pull requests (11 de fevereiro de 2026). A conclusão: o trabalho principal passou de escrever código para projetar ambientes, especificar a intenção e construir ciclos de feedback. Claude Code, Codex, Cursor, Devin e os outros produtos importantes disputam no design que fica fora do modelo.

5. Exemplos publicados: três harnesses reais

Harness engineering tende a ficar no abstrato. Aqui estão três exemplos cujos autores publicaram os detalhes, descritos no nível do que eles realmente fizeram.

1. A equipe do Codex da OpenAI: AGENTS.md como mapa, regras impostas por linters

• Mantiveram o AGENTS.md como um sumário de cerca de 100 linhas e fizeram de um diretório docs/ no repositório a fonte da verdade para design, planos e notas de qualidade. Um arquivo gigante empurrava a tarefa para fora do contexto, ficava desatualizado rápido e não podia ser verificado mecanicamente.
• Para manter a documentação atual, linters e CI verificam links cruzados e estrutura, e um agente recorrente procura descrições que não batem mais com o código e abre PRs de correção.
• Camadas, direção das dependências, logs estruturados, limite de tamanho de arquivo e mais são impostos por linters próprios e testes estruturais. As mensagens de erro explicam como corrigir o problema, para que o agente as leia e conserte o próprio trabalho.

2. Anthropic: projetar a passagem de bastão de agentes de longa duração

Quando o desenvolvimento atravessa várias janelas de contexto, os agentes tentavam construir coisas demais de uma vez ou declaravam o trabalho concluído pela metade. A Anthropic (26 de novembro de 2025) resolveu assim:

• Só a primeira sessão roda um agente inicializador com prompt próprio. Ele prepara uma lista de funcionalidades (feature_list.json), um registro de progresso (claude-progress.txt), um init.sh que sobe o servidor de desenvolvimento e um primeiro commit no git.
• Cada sessão seguinte lê o registro de progresso e o git log para se situar, implementa uma única funcionalidade e termina com um commit e uma atualização do registro.
• A lista de funcionalidades é JSON, não Markdown, porque o modelo tendia menos a reescrevê-la indevidamente. O único campo que ele pode mudar é o de aprovado/reprovado (passes).
• Uma funcionalidade só é marcada como pronta depois de testada de ponta a ponta com automação de navegador, como um usuário faria.

3. Mitchell Hashimoto: o mesmo erro não acontece duas vezes

Quem deu o nome trabalha em escala menor. Quando o agente comete um erro simples, ele acrescenta uma linha ao AGENTS.md; no projeto do terminal Ghostty, cada linha desse arquivo corresponde a um mau comportamento passado, e isso resolveu quase todos. Quando o texto não basta, ele cria scripts de verdade — para tirar capturas de tela, para rodar testes filtrados — e os entrega ao agente.

O que os três têm em comum é que o peso está em mecanismos que verificam e devolvem o trabalho, mais do que em pedidos por escrito. O checklist a seguir ajuda a decidir quanto transformar em mecanismo.

6. Um checklist prático de design de harness

7. Comparando os principais harnesses

Cada um destes harnesses roda sobre mais ou menos os mesmos LLMs (Claude / GPT / Gemini), e ainda assim seus pontos fortes divergem fortemente por causa de filosofias distintas de design de harness. "Qual harness?" importa mais que "qual LLM?" — esse é o verdadeiro campo de batalha da era dos agentes.

8. Antipadrões

1. Adicionar ferramentas demais

Quanto mais ferramentas você adiciona, mais fácil é o LLM escolher a errada. A documentação da Anthropic diz que a precisão do Claude na escolha de ferramentas cai quando há mais de 30–50 disponíveis, e oferece a busca de ferramentas para carregar só as relevantes sob demanda. O guia da empresa sobre como escrever ferramentas também diz que mais ferramentas não significam resultados melhores: em vez de embrulhar cada endpoint da API, junte as funções parecidas.

2. Empurrar tudo para dentro do contexto

"É só mostrar tudo, por garantia" é contraproducente. Passe as coisas por um filtro de relevância e inclua apenas o necessário. O contexto é um dispositivo para fazer emergir o sinal importante — não um depósito.

3. Implementar segurança só com prompts

"Por favor, não execute operações perigosas" cedo ou tarde acaba sendo ignorado, dependendo da situação. A resposta certa é torná-lo fisicamente impossível no nível do ambiente — sandbox, Hooks, limites de permissão.

4. Nunca revisar o que você adicionou

Cada peça adicionada deixa o harness mais pesado, lento e caro. Depois do experimento citado, a Anthropic removeu os componentes um a um e comparou os resultados, mantendo só o que ainda ajudava (o planejador e o avaliador). O argumento: cada componente de um harness embute uma suposição sobre o que o modelo não consegue fazer sozinho, e essas suposições envelhecem rápido conforme os modelos melhoram. Ao trocar de modelo, confira um por um se cada verificação e cada divisão que você adicionou ainda fazem diferença.

Resumo

Harness engineering é o ofício de projetar a camada "do lado de fora" do LLM. Prompt engineering é apenas um componente dentro do harness. Tratar deliberadamente os seis elementos — definição de ferramentas, gestão de contexto, memória, loop, guardrails, UX de saída — pode transformar o desempenho no mundo real a partir do mesmo LLM subjacente.

Em 2026, o principal campo de batalha dos agentes de IA em produção claramente migrou para o harness. Construir "harnesses inteligentes" — não apenas escrever "prompts inteligentes" — será o diferencial para a próxima geração de engenheiros.

FAQ

Q1. Então não precisamos mais de prompt engineering?

Errado. Continua essencial — como um componente dentro do harness. Descrições de ferramentas, system prompts, mensagens de erro — tudo isso é superfície de design de prompt. O que ficou ultrapassado é a mentalidade de "vou consertar isso com um prompt melhor".

Q2. Qual o primeiro passo para aprender harness engineering?

Pegue o Claude Code ou o Cursor e não apenas use — mude o comportamento ajustando a configuração. Transformado em passos, o método do Hashimoto fica assim:

1. Anote cada falha do agente (com qual instrução e o que deu errado).
2. Para falhas simples, acrescente uma linha ao CLAUDE.md / AGENTS.md / .cursor/rules.
3. Falhas que se repetem, ou que causariam estrago, bloqueie de forma mecânica com Hooks, linters ou testes — e escreva a correção na mensagem de erro.
4. Peça a mesma tarefa de novo e confirme que a falha sumiu.

Q3. Harnesses são o mesmo que frameworks como o LangChain?

Próximos, mas não a mesma coisa. Um framework é um kit de ferramentas de implementação; um harness é uma disciplina e mentalidade de design. LangChain, LlamaIndex, o Claude Agent SDK e afins são ferramentas para construir harnesses.

Q4. Construir o próprio harness ou usar um existente?

Para a maioria dos casos, um harness existente (Claude Code, Cursor, etc.) mais customização é suficiente. Construir um do zero só faz sentido para requisitos corporativos, domínios de nicho ou otimização extrema de custo.

Q5. "Harness engineer" vai virar um cargo de verdade?

Ainda não há um nome de cargo consolidado. O próprio Hashimoto escreveu que não sabia se existia um termo aceito pelo setor. Mas a equipe do Codex da OpenAI relata que o trabalho principal do engenheiro passou a ser projetar ambientes, especificar a intenção e construir ciclos de feedback — o conteúdo do trabalho está mudando antes que um nome de cargo se firme.