Engenharia de harness: a era de projetar o ambiente de trabalho, mais importante que o modelo

Este é um artigo de análise sobre “engenharia de harness” compilado por Addy Osmani. Segundo ele, nos últimos dois anos a atenção da indústria ficou concentrada demais na pergunta “qual modelo de IA é mais inteligente?”. As comparações intermináveis sobre se o GPT escreve código mais limpo ou se o Claude alucina menos continuaram, mas a tese dele é que, na prática, o desempenho real da IA para programação é decidido menos pelo modelo em si e mais pelo harness ao redor dele. Harness é um termo que engloba tudo exceto o modelo: o system prompt usado para dar tarefas à IA, as ferramentas e servidores externos disponíveis, a política de gerenciamento de contexto, os mecanismos de verificação que entram automaticamente durante a execução (hooks), o espaço seguro de execução (sandbox), IAs auxiliares (subagentes), loops de feedback e até o fluxo de recuperação quando o trabalho trava. Viv Trivedy formalizou esse conceito com a frase “agente de IA = modelo + harness”, e pessoas como a equipe de engenharia da Anthropic, a HumanLayer e Simon Willison vêm refinando essa linha de pensamento. Para Osmani, isso já se consolidou como um campo próprio de engenharia.

Desdobrando os pontos principais, temos o seguinte.

• O que é o harness Só o modelo não basta para virar uma IA que realmente conclui trabalho. É preciso acrescentar código e configurações que permitam lembrar o andamento, executar ferramentas, analisar resultados, decidir de novo e bloquear ações que não devem acontecer. Produtos como Claude Code, Cursor, Codex, Aider e Cline são todos harnesses, e mesmo quando usam o mesmo modelo, o comportamento que percebemos é definido pelo harness. Para usar a expressão de Simon Willison, um agente de IA é “um sistema que roda ferramentas repetidamente para alcançar um objetivo”, e a essência da competência está em como essa estrutura de ferramentas e repetição é projetada.

• A visão de que o problema não é do modelo, e sim da configuração Quando a IA faz algo absurdo, engenheiros frequentemente culpam o modelo e concluem que “é melhor esperar a próxima versão”. A engenharia de harness rejeita essa reação. Nas palavras da HumanLayer, “isso não é problema do modelo, é problema de configuração (skill issue)”. Há casos em que o mesmo modelo Claude Opus 4.6 fica na parte de baixo do Terminal Bench 2.0 dentro do harness padrão, Claude Code, mas salta para o topo quando é colocado em um harness customizado. A equipe de Viv elevou o mesmo modelo da faixa do 30º lugar para a do 5º apenas trocando o harness. Isso significa que, muitas vezes, o potencial do modelo está sendo reduzido pelo próprio harness.

• O princípio do “ratchet”, que transforma erros em regras Se a IA comete um erro uma única vez, isso não é tratado como acidente aleatório, mas como um sinal permanente. Para evitar que o mesmo erro volte a acontecer, adiciona-se uma linha ao documento de regras, instala-se um bloqueio automático ou coloca-se uma IA auxiliar de revisão, apertando o processo passo a passo. Por exemplo, se a IA já comentou código de teste em vez de corrigi-lo, a próxima versão do documento de regras passa a incluir algo como “não comentar testes; apague ou corrija”, e a etapa de checagem antes do commit ganha um validador para detectar esse padrão. O ponto central é que cada linha de um bom documento de regras deve estar ligada a uma falha concreta do passado. Por isso, engenharia de harness não é simplesmente pegar um framework pronto e usar como está, mas algo mais próximo de uma “disciplina” cultivada com base no histórico de falhas do próprio codebase.

• Projetar de trás para frente a partir do comportamento desejado A forma de pensar mais útil proposta por Viv é projetar ao contrário: “quero este comportamento → quais componentes do harness tornam esse comportamento possível?”. Se você não consegue explicar em uma frase para que um componente existe, é melhor removê-lo. Em termos concretos: sistema de arquivos e Git servem para preservar e reverter trabalho; Bash e execução de código são ferramentas universais para experimentar qualquer coisa; a sandbox é um espaço seguro onde erros não afetam o ambiente principal; arquivos de memória, busca na web e ferramentas MCP servem para acumular conhecimento recém-descoberto; compressão por resumo, separação da saída das ferramentas e recursos de skill ampliam os limites de memória da IA; e o Ralph loop, junto com a separação entre planejador e avaliador, ajuda a sustentar tarefas longas que duram vários dias.

• O problema da degradação de contexto (context rot) A IA tem limite para a quantidade de texto que consegue ler de uma vez, e, quanto mais se aproxima desse teto, mais sua capacidade de julgamento cai de forma visível. Por isso, o harness também é um conjunto de mecanismos para usar bem esse espaço limitado. Primeiro, quando o limite vai enchendo, o conteúdo antigo é resumido e comprimido de forma inteligente. Segundo, saídas grandes como um log de 2.000 linhas mantêm só o começo e o fim, enquanto o corpo é jogado em um arquivo para ser relido apenas quando necessário. Terceiro, ferramentas e instruções não são mostradas todas de uma vez logo no início, mas reveladas apenas no momento em que de fato são necessárias para aquela tarefa, em um modelo de “divulgação progressiva”. Em trabalhos realmente longos, chega-se a reiniciar tudo em uma nova janela levando apenas um documento de handoff estruturado. A Anthropic observa que “em tarefas longas, só a compressão por resumo não basta; às vezes é preciso recomeçar com um documento de handoff estruturado”. Isso se parece com preparar documentação organizada ao transferir trabalho para uma nova pessoa da equipe.

• Padrões para sustentar trabalhos longos Uma das fraquezas dos modelos atuais é querer encerrar o trabalho cedo demais, não conseguir decompor bem problemas grandes e perder o fio quando a janela de contexto muda. O harness precisa compensar isso. O Ralph loop é uma técnica simples em que um hook intercepta cada tentativa do modelo de concluir o trabalho e reinjeta o objetivo original em uma nova janela de contexto, permitindo que a tarefa continue. Cada repetição começa em um estado limpo, mas os resultados anteriores seguem disponíveis pelo sistema de arquivos. Já a Anthropic enfatiza que “quem gera” e “quem avalia” devem ser IAs separadas, porque a IA tende a ser indulgente ao avaliar o próprio resultado. Além disso, o padrão de “contrato de sprint”, em que se define antecipadamente o que significa “estar concluído”, é eficaz para impedir que o objetivo vá se expandindo silenciosamente ao longo da execução.

• O papel dos hooks “Dizer para a IA fazer algo desse jeito” e “fazer o sistema obrigá-la a agir assim” são coisas diferentes. Hooks são os mecanismos automáticos que preenchem essa diferença, entrando em ação antes do uso de uma ferramenta, depois de editar arquivos, antes do commit ou no início da sessão. Eles podem rodar automaticamente checagem de sintaxe, lint e testes a cada mudança no código, bloquear comandos perigosos como rm -rf ou git push --force, ou exigir aprovação humana antes de abrir um PR. O princípio é “sucesso em silêncio, falha em alto volume”. Se a checagem passa, a IA não recebe nenhum retorno; se falha, a mensagem de erro é injetada de volta no fluxo para que ela mesma corrija. É uma estrutura que quase não custa nada no dia a dia e ajuda com precisão exatamente quando aparece um problema.

• Documentos de regras e escolha de ferramentas devem ser curtos e claros O arquivo AGENTS.md na raiz do projeto é o arquivo de configuração de maior impacto, porque entra no system prompt a cada turno. A HumanLayer recomenda manter esse documento com menos de 60 linhas. Quanto mais longo ele fica, menos peso tem cada linha, então a recomendação é não tratá-lo como um guia de estilo geral, mas como uma checklist de piloto de avião, mantendo só o essencial. Com ferramentas vale o mesmo princípio: como nome, descrição e schema entram no prompt em toda requisição, é melhor ter 10 ferramentas bem lapidadas do que 50 parecidas entre si. A HumanLayer também chama atenção para a segurança. Como a descrição da ferramenta é texto lido pela IA, conectar um servidor MCP externo não verificado pode virar um canal para injetar instruções que outra pessoa escreveu de antemão.

Pontos que podem ser vistos como vantagens.

• Fica claro onde vale investir esforço Os dados de benchmark mostram que o harness é um ponto em que o comportamento pode melhorar muito sem trocar de modelo. Em vez da expectativa vaga de “vamos esperar o próximo modelo”, surge uma área concreta que pode ser ajustada agora.
• Uma estrutura em que o know-how se acumula Com a abordagem ratchet, que transforma erros em regras, cada lição aprendida uma vez permanece como ativo da equipe. Mesmo se as pessoas mudarem, os documentos de regras e os hooks continuam ali protegendo quem vier depois.
• Surgimento de harnesses prontos (HaaS) A tendência que Viv chama de “Harness-as-a-Service” está se consolidando rapidamente. Produtos como Claude Agent SDK, Codex SDK e OpenAI Agents SDK já empacotam loop de trabalho, ferramentas, gerenciamento de contexto, hooks e sandbox, permitindo focar mais no conhecimento do próprio domínio sem precisar construir tudo do zero.

Também há pontos mais pesados.

• A área de responsabilidade é ampla É preciso assumir diretamente instruções, ferramentas, ambiente seguro de execução, verificações automáticas e observabilidade de logs. O ponto central é que isso não é algo que o fornecedor do modelo vai resolver sozinho.
• Risco de acoplamento entre modelo e harness Os modelos atuais passam por aprendizado pós-processamento dentro de harnesses específicos, então, ao movê-los para outro harness, o desempenho pode cair de repente. Basta mudar o nome de uma ferramenta ou o formato de um argumento para o resultado oscilar. Um modelo realmente geral não deveria ser afetado pelo nome da ferramenta, mas, como o treinamento acontece junto com esse contexto, surge uma espécie de overfitting.
• Risco de segurança em ferramentas externas Em servidores MCP, a descrição da ferramenta é lida diretamente pela IA, então, no momento em que se conecta uma ferramenta não verificada, o texto externo já começa a influenciar a IA antes mesmo de o usuário digitar qualquer coisa.

Perspectivas que diferenciam o texto.

• Distanciamento do discurso centrado no modelo Em vez de esperar por um GPT mais inteligente, o texto propõe métodos de engenharia para extrair o máximo possível do modelo que já se tem. O diagnóstico é que a maior parte da distância entre os limites aparentes da IA e a capacidade real do modelo é, na verdade, uma distância de harness.
• O harness não desaparece; ele muda de lugar Quando o modelo melhora, alguns componentes do harness deixam de ser necessários. Por exemplo, o Opus 4.6 praticamente eliminou a ansiedade comum no Claude Sonnet 4.5, daquele tipo “o contexto está acabando, preciso terminar rápido”, e por isso vários mecanismos de segurança usados antes viraram código morto. Mas, nas novas áreas que o modelo passa a alcançar, surgem novas fraquezas, e novos harnesses voltam a ser necessários para preenchê-las. A frase da Anthropic combina bem aqui: “todos os componentes de um harness embutem uma hipótese sobre aquilo que o modelo não consegue fazer sozinho”.
• O ciclo de aprendizado entre modelo e harness Outro ponto destacado por Viv é o ciclo de realimentação entre o projeto do harness e o treinamento do modelo. Quando padrões úteis são descobertos no harness, eles se padronizam; a geração seguinte de modelos é treinada com base nesses padrões; e, sobre esses modelos, novos padrões de harness passam a surgir. Daí a conclusão de que “um bom harness” não é o harness em que o modelo foi treinado, mas aquele retrabalhado de acordo com o seu trabalho real.
• O setor converge para formas parecidas IAs de programação como Claude Code, Cursor, Codex, Aider e Cline usam modelos diferentes por dentro, mas seus harnesses estão ficando cada vez mais parecidos. O fato de os modelos serem diferentes e os harnesses se parecerem cada vez mais é um sinal de onde essa área está se estabilizando.

O texto de Osmani sustenta a visão de que a competitividade da IA para programação depende mais do projeto do harness ao redor do modelo do que da escolha do modelo em si, e que harness não é um arquivo de configuração definido uma vez e pronto, mas um sistema vivo que continua sendo atualizado conforme o histórico de falhas. Mesmo com modelos melhores, o harness não desaparece; apenas sobe um nível na hierarquia dos problemas, e um novo harness ocupa aquele espaço. Como diz a frase de Viv citada por ele, “fazer um bom agente é a arte da iteração, e sem a primeira versão não existe iteração”, o que sugere que, no fim, essa área é uma disputa para ver quem começa mais cedo e refina com mais frequência. Em resumo, o lugar onde engenheiros devem investir tempo não é trocar constantemente pelo modelo do momento, mas ajustar sem parar o harness adequado ao próprio trabalho, elevando aos poucos o teto que o modelo consegue alcançar.

[kimjoin2]

Parece que estão surgindo cada vez mais termos puramente de marketing.

[dongho42]

Mas, quando você coloca no prompt algo como "faça A, não faça B", essa abordagem parece válida se o modelo realmente entender muito bem. Só que, se o cumprimento do prompt acontecer de forma probabilística dependendo do estado do servidor de IA, será que essa abordagem continua sendo válida?

[dongho42]

Antigamente, mesmo quando eu escrevia claramente no prompt para fazer A, havia uma certa probabilidade de ele simplesmente não obedecer; então tentei de tudo: destacar em negrito no mrkdwn, escrever duas vezes, escrever em inglês, repetir a ideia no começo e no fim, escrever em XML... mas ele continuava ignorando o prompt com alguma frequência...

[kurthong]

Eu também estava colocando de tudo, parecido com o que o Osmani fala, e no meio de criar um app esse assunto surgiu, então acabei me apressando um pouco, mas acho que teria sido melhor se o próprio Osmani, em vez de só falar, tivesse colocado o que ele disse no Google Antigravity.
O mesmo vale para o Kaparthy; sinceramente, essa postura de não pensar mais em simplesmente construir e só jogar um texto de vez em quando... sei lá! É isso.

https://github.com/hang-in/tunaFlow

[tangokorea]

Em vez de recuar para a perspectiva de que ou o modelo ou o harness é melhor, que tal pensar em qual harness é mais adequado para qual modelo?

[jimmy2056]

Se o modelo for bom, a carga do projeto de chicotes também diminui.

[akapwhd]

Mesmo aplicando esse tipo de coisa, na hora de programar de verdade parece que não ajuda tanto assim... talvez seja porque é um desenvolvimento com um nível de dificuldade de só deixar um plano do codex e rodar o agente haha

[blackfabric]

Resumo em 3 linhas

• O sistema (harness) determina o sucesso mais do que o modelo: o desempenho da IA depende menos do modelo em si, como GPT ou Claude, e mais do projeto do ambiente de trabalho ao seu redor, chamado de harness, incluindo prompts, ferramentas, sandbox e loops de feedback
• O princípio de Ratchet: em vez de tratar os erros da IA como simples acidentes, é preciso refletí-los imediatamente em documentos de regras (como AGENTS.md) ou em hooks, para que o sistema fique mais robusto com o passar do tempo
• O problema muitas vezes não é o modelo, mas a configuração (Skill): quando a IA não consegue trabalhar bem, em muitos casos isso se deve mais à má concepção do harness do que à falta de inteligência do modelo, e uma abordagem de engenharia que projeta os componentes e as restrições a partir do resultado desejado, em ordem inversa, é essencial

[yungoun]

Mas o Harness estava sendo muito promovido até a semana passada, e desde esta semana ficou quieto... Será que é por causa das trapalhadas da Anthropic e porque o Codex 5.5 é excelente........

[click]

Coisas como SDD já perderam o hype faz tempo, e agora parece que a onda é harness.
Uma parte meio curiosa no harness é que, claramente, esse conceito não estava nos dados de treinamento, mas o modelo entende muito rápido a ideia de harness.
Talvez por usar exatamente o significado de uma palavra que já existia, eu nem mencionei isso e mesmo assim ele já faz comentários como atualizar o harness primeiro.

[kurthong]

É um conteúdo que chega até a analisar o texto de um desenvolvedor experiente que fala de forma convincente, mas sem muito conteúdo de fato (peço desculpas, pessoalmente não gosto do Google). Claro, acho que a abordagem de tentar entender o fenômeno em si é uma boa tentativa.