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

Esta é uma análise de Addy Osmani sobre “Harness Engineering”. Segundo ele, nos últimos dois anos a atenção da indústria ficou concentrada demais na pergunta “qual modelo de IA é mais inteligente?”. Comparações intermináveis seguiram sobre se o GPT escreve código mais limpo ou se o Claude alucina menos, mas a tese dele é que, na prática, o desempenho real de uma IA para programação é definido menos pelo modelo em si e mais pelo harness ao redor dele. Harness é um termo que abrange tudo, exceto o modelo: o system prompt que manda a IA executar tarefas, as ferramentas e servidores externos que ela pode usar, a política de gestão de contexto, os mecanismos de verificação que entram automaticamente durante a execução (hooks), o ambiente seguro de execução (sandbox), IAs auxiliares (subagentes), loops de feedback e até o fluxo de recuperação quando o trabalho emperra. Viv Trivedy formalizou essa ideia na frase “agente de IA = modelo + harness”, e pessoas como a equipe de engenharia da Anthropic, a HumanLayer e Simon Willison estão refinando esse movimento. Osmani entende que essa linha agora já se consolidou como um campo de engenharia.

Os pontos centrais podem ser detalhados assim.

• O que é o harness Só o modelo não basta para virar uma IA que realmente trabalha. É preciso somar código e configurações que permitam lembrar o progresso, executar ferramentas, analisar resultados, decidir de novo e bloquear ações que não deveriam acontecer. Produtos como Claude Code, Cursor, Codex, Aider e Cline são todos harnesses, e mesmo quando usam o mesmo modelo por dentro, o comportamento que percebemos é determinado pelo harness. Nas palavras de Simon Willison, um agente de IA é “um sistema que executa ferramentas repetidamente para atingir um objetivo”, e a essência da competência está em como se projeta essa estrutura de ferramentas e repetição.

• A visão de que o problema não é do modelo, mas da configuração Quando a IA faz algo absurdo, engenheiros costumam culpar o modelo e concluir que “é melhor esperar a próxima versão”. A engenharia de harness rejeita essa reação. Pegando a expressão da HumanLayer, “isso não é problema do modelo, é problema de configuração (skill issue)”. Mesmo usando o mesmo modelo Claude Opus 4.6, houve casos em que ele ficou no pelotão inferior do Terminal Bench 2.0 dentro do harness padrão Claude Code, mas saltou para o topo quando foi movido para um harness ajustado manualmente. A equipe do Viv elevou o mesmo modelo da faixa de trigésimos lugares para o top 5 só mudando o harness. Isso significa que o potencial do modelo muitas vezes está sendo desperdiçado pelo próprio harness.

• O princípio do “ratchet”, que transforma erros em regras Se a IA cometeu um erro ao menos uma vez, isso não deve ser tratado como acidente pontual, mas como sinal permanente. Para evitar a repetição, adiciona-se uma linha ao documento de regras, acopla-se um bloqueio automático e, se necessário, coloca-se uma IA auxiliar de revisão, apertando o sistema um passo de cada vez. Por exemplo, se a IA comentou o código de teste em vez de corrigi-lo, a próxima versão do documento de regras passa a incluir uma linha como “não comente testes; remova ou corrija”, e o passo de checagem antes do commit ganha um verificador para detectar esse padrão. O ponto central é que cada linha de um bom documento de regras deve estar ligada a uma falha concreta já ocorrida. Por isso, engenharia de harness não é simplesmente pegar um framework pronto, mas algo mais próximo de uma “disciplina” cultivada a partir do histórico de falhas da própria base de código.

• Projetar de trás para frente a partir do comportamento desejado O modelo mental mais útil proposto por Viv é projetar em sentido inverso: “quero este comportamento → quais componentes de harness tornam isso possível?”. Se não dá para explicar em uma linha que comportamento um componente existe para viabilizar, talvez seja melhor removê-lo. Em termos concretos, sistema de arquivos e Git servem para preservar o trabalho por longos períodos e permitir reversão; bash e execução de código são ferramentas universais para tentar qualquer coisa; a sandbox é um espaço seguro onde erros não afetam o sistema principal; arquivos de memória, busca na web e ferramentas MCP são canais para acumular conhecimento recém-descoberto; compressão por resumo, separação da saída das ferramentas e funcionalidades de skill expandem os limites de memória da IA; e o Ralph loop junto com a separação entre planejador e avaliador são formas de sustentar tarefas longas que duram dias.

• O problema da deterioraçã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 limite, mais seu julgamento piora de forma perceptível. Por isso, o harness também é um conjunto de mecanismos para usar bem esse espaço finito. Primeiro, quando o limite vai enchendo, comprime-se o conteúdo antigo com resumos inteligentes. Segundo, saídas grandes como um log de 2.000 linhas mantêm só o começo e o fim no contexto, enquanto o corpo vai para um arquivo a ser relido apenas quando necessário. Terceiro, em vez de mostrar todas as ferramentas e instruções desde o início, usa-se “divulgação progressiva”, liberando apenas o que é realmente necessário no momento da tarefa. Em trabalhos muito longos, às vezes recomeça-se do zero em uma nova janela levando apenas um documento de handoff estruturado. A Anthropic observa que, em tarefas longas, só resumir e comprimir nem sempre basta; às vezes é preciso reiniciar com um documento de handoff estruturado. Em termos humanos, é parecido com preparar um documento organizado ao passar o trabalho para uma pessoa nova.

• Padrões para sustentar trabalhos longos Uma fraqueza dos modelos atuais é a tendência de encerrar o trabalho cedo demais, a dificuldade em quebrar problemas grandes em partes menores e a perda de fluxo quando a janela de contexto muda. O harness precisa compensar isso. O Ralph loop é uma técnica simples em que um hook intercepta a tentativa do modelo de encerrar a tarefa e reinjeta o objetivo original numa nova janela de contexto para continuar o trabalho. Cada iteração começa limpa, mas o resultado da etapa anterior segue adiante pelo sistema de arquivos. Já a Anthropic enfatiza que “quem gera” e “quem avalia” devem ser IAs diferentes, porque a IA tende a ser complacente ao julgar o próprio resultado. Além disso, o padrão de “contrato de sprint”, que define antes do início o que exatamente significa “terminado”, é eficaz para impedir que o objetivo vá se expandindo silenciosamente no meio da execução.

• O papel dos hooks “Dizer para a IA agir de certo jeito” e “fazer o sistema obrigá-la a agir assim” são coisas diferentes. Hooks são o mecanismo automático que cobre essa diferença, entrando em ação antes de usar ferramentas, depois de editar arquivos, antes do commit ou no início da sessão. Isso inclui rodar automaticamente verificação de sintaxe, lint e testes sempre que o código muda; 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 com barulho”. Se a checagem passa, a IA não recebe nenhuma mensagem; se falha, a mensagem de erro é injetada no fluxo para que ela mesma corrija. É uma estrutura que quase não custa nada no dia a dia e só intervém com precisão quando surge um problema.

• Documento de regras e escolha de ferramentas devem ser curtos e claros O AGENTS.md na raiz do projeto é o arquivo de configuração mais influente, 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 cada linha tem; por isso, a recomendação é que ele não seja um guia de estilo geral, mas algo mais parecido com um checklist de piloto de avião, contendo apenas o indispensável. O mesmo vale para ferramentas: como nome, descrição e schema entram no prompt a cada requisição, é melhor ter 10 ferramentas bem lapidadas do que 50 parecidas entre si. A HumanLayer também chama atenção para o lado de 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 escritas por terceiros.

Pontos que podem ser vistos como vantagens.

• Fica mais claro onde vale investir esforço Os dados de benchmark mostram que o harness é o ponto em que dá para elevar bastante o comportamento sem trocar de modelo. Em vez de esperar vagamente pelo próximo modelo, surge uma área concreta que pode ser ajustada agora.
• Uma estrutura em que o know-how se acumula Com o método ratchet, que transforma erros em regras, uma lição aprendida uma vez permanece como ativo do time. Mesmo que as pessoas mudem, o documento de regras e os hooks continuam ali protegendo quem vier depois.
• A chegada de harnesses prontos (HaaS) O movimento que Viv chama de “Harness-as-a-Service” está se firmando rapidamente. Com produtos como Claude Agent SDK, Codex SDK e OpenAI Agents SDK, que já empacotam loop de trabalho, ferramentas, gestão de contexto, hooks e sandbox, ficou possível focar no conhecimento do próprio domínio sem construir tudo do zero.

Também há partes mais pesadas.

• A área de responsabilidade é ampla Instruções, ferramentas, ambiente seguro de execução, verificações automáticas e observabilidade de logs: tudo isso passa a ser responsabilidade direta de quem projeta o sistema. O ponto central é que isso não fica a cargo automático do fornecedor do modelo.
• O risco do acoplamento entre modelo e harness Os modelos atuais passam por treinamento com pós-processamento dentro de harnesses específicos, então ao migrá-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 depender do nome da ferramenta, mas como o aprendizado acontece em conjunto, acaba surgindo uma espécie de overfitting.
• Riscos de segurança de ferramentas externas Como servidores MCP expõem descrições de ferramentas que são lidas diretamente pela IA, no momento em que se conecta uma ferramenta não verificada, texto externo já começa a influenciar a IA antes mesmo de o usuário digitar uma única letra.

Pontos de vista que diferenciam essa abordagem.

• Distanciamento do discurso centrado no modelo Em vez de esperar por um GPT mais inteligente, a proposta é um método de engenharia para extrair o máximo do modelo que já se tem. O diagnóstico é que a maior parte da distância entre os limites visíveis da IA hoje e a capacidade real do modelo é, na verdade, uma lacuna de harness.
• O harness não desaparece, só muda de lugar Quando os modelos melhoram, alguns componentes do harness deixam de ser necessários. Por exemplo, o Opus 4.6 praticamente eliminou a ansiedade típica do Claude Sonnet 4.5, aquela tendência de “o contexto está acabando, preciso encerrar logo”, e com isso vários mecanismos auxiliares de contenção viraram código morto. Mas, nas novas áreas que o modelo passa a alcançar, surgem novas fragilidades, e novos harnesses voltam a ser necessários para cobri-las. A frase da Anthropic se encaixa bem aqui: “todo componente de harness embute uma hipótese sobre o que o modelo ainda não consegue fazer sozinho”.
• O ciclo de aprendizado entre modelo e harness Outro movimento apontado por Viv é o ciclo de retroalimentação entre projeto de harness e treinamento de modelos. Quando um padrão útil aparece no harness, ele é padronizado; a geração seguinte de modelos é treinada com esse padrão como referência; e, em cima desses modelos, novos padrões de harness surgem novamente. Por isso, a conclusão é que “um bom harness” não é necessariamente o harness no qual o modelo foi treinado, mas aquele retrabalhado para se ajustar ao seu trabalho real.
• A indústria converge para formas parecidas IAs de programação como Claude Code, Cursor, Codex, Aider e Cline usam modelos diferentes, mas a forma do harness está ficando cada vez mais parecida. O fato de os modelos divergirem e os harnesses convergirem pode ser lido como um sinal de onde este campo está se estabilizando.

O texto de Osmani propõe a visão de que a competitividade de uma IA de programação depende mais do projeto do harness ao redor do modelo do que da escolha do modelo em si, e que o harness não é um arquivo de configuração estático definido uma vez por todas, mas um sistema vivo, continuamente atualizado conforme o histórico de falhas. Melhorar o modelo não faz o harness desaparecer; em vez disso, o nível do problema sobe um degrau e um novo harness passa a ocupar esse espaço. Como na 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”, a leitura é que este campo, no fim, é uma disputa entre quem começa antes e refina com mais frequência. Em resumo, o lugar em que engenheiros deveriam investir tempo não é trocar o modelo da moda a todo momento, mas ajustar sem parar o harness ao próprio trabalho, elevando pouco a pouco o teto do que o modelo consegue alcançar.

[kimjoin2]

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

[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

[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

[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.