Como aplicar harness engineering no seu agente hoje

Harness engineering é a prática de projetar tudo que envolve o modelo de linguagem: instruções, contexto, ferramentas, permissões e critérios de validação. Como os modelos de fronteira estão cada vez mais próximos entre si, esse sistema em volta passou a determinar mais do resultado final do que a troca de modelo. Este guia mostra as camadas do harness, o que faz um agente de código funcionar e como diagnosticar falhas antes de culpar o modelo.

O que é harness engineering na arquitetura de agentes de IA

Harness engineering é a prática de projetar o sistema que envolve o modelo de linguagem: instruções, contexto, ferramentas, permissões e critérios de validação. O modelo é o coração do agente, mas é o harness que decide o que chega até ele e o que acontece depois da resposta.

A definição útil é curta: agente é modelo mais harness. O Claude Code e o OpenAI Codex são exemplos de agentes especializados em código, e cada um carrega um harness próprio com regras, ferramentas e fluxo de validação. Quando você troca o modelo dentro desse sistema, o harness continua definindo como a tarefa começa, avança e termina.

Essa separação importa porque ela muda o diagnóstico. Se um agente ignora uma regra do projeto ou inventa uma função inexistente, a resposta imediata costuma ser culpar o modelo. Harness engineering propõe olhar primeiro para o que o modelo recebeu: a instrução era clara, o contexto estava acessível e as ferramentas permitiam verificar o resultado?

A discussão migrou de prompt engineering para context engineering e, agora, para harness engineering. O prompt expressa o que você quer naquele momento; o contexto reúne as informações disponíveis na sessão; o harness organiza esse contexto e a capacidade de ação do agente ao longo da tarefa.

Por que trocar o modelo de fronteira rende cada vez menos

Os modelos de fronteira estão mais próximos entre si do que estavam dois anos atrás, e isso reduz o retorno de trocar de modelo para resolver um problema de engenharia. A diferença de qualidade entre as gerações mais recentes é menor do que o salto que separava as gerações anteriores.

O Artificial Analysis Intelligence Index acompanha esse tipo de comparação entre modelos. Números concretos mudam rápido e dependem da versão avaliada, então trate qualquer pontuação específica como uma fotografia datada, não como um placar permanente. O ponto estrutural é que modelos líderes frequentemente ficam a poucos pontos uns dos outros em índices agregados.

A consequência prática é a que interessa. Quando o modelo A e o modelo B entregam resultados parecidos, o que sobra como diferencial é o que você construiu em volta deles: as instruções persistentes, a forma como o projeto está organizado, as ferramentas disponíveis e a capacidade do agente de testar o próprio trabalho.

Isso não significa que o modelo não importa. Modelos diferentes têm especialidades diferentes em tarefas específicas. A questão é que esperar a próxima geração para resolver um problema mal especificado é uma estratégia fraca, porque o gargalo estava no harness.

O caso Nvidia e a abertura do DeepSeek Harness

Dois episódios são citados como marco desse movimento, e cada um merece ser lido pelo que ele realmente é. O primeiro é um resultado divulgado pela Nvidia em um sistema construído em torno de um modelo existente. O segundo é a publicação de uma infraestrutura de harness por um laboratório conhecido pelos próprios modelos.

O relato sobre a Nvidia descreve um sistema que teria passado de 30% para 100% de acerto em um teste difícil sem treinar um modelo novo e sem adicionar parâmetros. Trate esse número como um resultado específico daquele sistema naquele teste, reportado pela própria empresa. Ele não prova que qualquer harness produz esse salto, nem que a diferença entre modelos deixou de existir.

O segundo episódio é a publicação do DeepSeek Harness, uma infraestrutura organizada em plugins na qual modelo, ferramenta, skill e armazenamento são peças substituíveis. O valor desse tipo de publicação não é provar qual laboratório tem o melhor agente de código, e sim separar o harness do modelo e disponibilizar essa estrutura de forma independente.

A leitura correta dos dois casos é a mesma: o harness virou objeto de engenharia explícita. Antes, essa estrutura ficava embutida dentro de um produto fechado. Agora ela aparece como algo que você pode inspecionar, comparar e adaptar ao seu projeto.

Prompt, contexto e harness: a diferença que muda o diagnóstico

Prompt, contexto e harness são camadas distintas, e confundi-las leva a diagnósticos errados. O prompt define o que você quer agora. O contexto reúne o que o modelo pode consultar nesta sessão. O harness decide como o agente se comporta, quando chama ferramentas e como a conclusão é validada.

Um exemplo deixa a separação concreta. Quando você escreve “desenvolva essa API”, isso é o prompt. Os arquivos do projeto, o histórico da conversa e os artefatos de documentação formam o contexto. O harness define quando o agente considera a tarefa concluída, quais testes ele roda, quais comandos pode executar e o que acontece quando algo falha.

Harness engineering não é uma versão sofisticada de prompt engineering. O prompt continua sendo uma entrada importante, mas ele é apenas uma das peças. Um agent MD bem escrito, os sensores de teste e as permissões de ferramenta compõem uma camada que não desaparece quando você reescreve a instrução.

Essa distinção também explica o ceticismo de quem diz que arquitetura de agentes é “só prompt”. Se o seu agente não consegue verificar o próprio resultado, nenhuma reformulação de instrução resolve a falta de validação. O problema não está no texto, está na estrutura.

Contexto é recurso finito: por que um AGENTS.md gigante pode piorar

Contexto é um recurso finito e competitivo, e aumentar a janela nem sempre melhora o resultado. Informações relevantes disputam espaço com informações irrelevantes, e o agente precisa saber priorizar o que consultar em cada etapa da tarefa.

O erro comum é transformar toda a documentação da empresa em um único arquivo markdown e colocá-lo no projeto. O AGENTS.md é um arquivo markdown agnóstico de agente, que funciona como onboarding do projeto: regras, arquitetura e convenções que o agente deve seguir. Quando esse arquivo vira um documento enorme, ele deixa de orientar e passa a poluir a janela de contexto.

O problema tem duas consequências práticas. A primeira é o custo de inferência: um agente que não encontra a informação rapidamente lê dezenas ou centenas de arquivos, consumindo tokens sem garantia de acerto. A segunda é o risco de alucinação: sem referência clara, o modelo pode inferir uma solução a partir do treinamento geral e propor algo que quebra o projeto.

Dentro de uma tarefa específica, o agente não precisa conhecer a arquitetura inteira do sistema. Ele precisa saber onde buscar a informação certa quando ela for necessária. Essa é a diferença entre jogar contexto e organizar contexto.

O AGENTS.md como índice, não como enciclopédia

O padrão que funciona melhor é usar o AGENTS.md como índice do projeto, não como enciclopédia. Ele mostra o mapa do repositório, aponta onde cada tipo de informação está e lista regras e restrições de arquitetura em nível alto.

Na prática, o arquivo diz ao agente algo como: se você precisar alterar limites de módulo e dependências, consulte este outro artefato. O agente passa a ter um caminho de busca em vez de um bloco de texto. O documento de arquitetura detalhado, as regras de negócio e o histórico de decisões ficam em arquivos separados, carregados só quando a tarefa pede.

Foi exatamente esse tipo de ajuste que a equipe da OpenAI descreveu ao relatar que um AGENTS.md inchado estava atrapalhando o próprio agente. A correção foi enxugar o arquivo e transformá-lo em orientação de busca. O relato é de primeira parte: descreve a experiência da equipe no projeto dela, não uma lei geral para todos os repositórios.

A distribuição de contexto em artefatos separados ajuda inclusive quando você mantém uma base de conhecimento paralela, como um vault de notas para resolver problemas recorrentes. O agente só consulta essa base quando está lidando com um bug daquela área, e o AGENTS.md avisa onde ela está.

Guias e sensores: as duas famílias de componentes do harness

Um harness completo se organiza em dois tipos de componente, e essa divisão ajuda a identificar o que está faltando no seu agente. Guias atuam antes da ação e fornecem contexto. Sensores atuam depois da ação e produzem um sinal sobre o resultado.

O modelo de guias e sensores foi popularizado por Martin Fowler em textos sobre agentes de código e vale como ferramenta de análise. Guias incluem especificação, AGENTS.md, documento de arquitetura e convenções do projeto. Sensores incluem testes automatizados, compiladores, linters, verificação de tipos e análise de segurança.

Componente — Quando atua — Exemplos — Função no harness — n — --- — --- — --- — --- — n — Guias — Antes da ação — AGENTS.md, especificação, documento de arquitetura — Reduzir ambiguidade e orientar a execução — n — Sensores — Depois da ação — Testes, linter, compilador, verificação de tipos — Gerar sinal para o agente corrigir o próprio erro

Um agente sem sensores depende de você para descobrir que a solução está errada. Um agente com sensores consegue testar, identificar a falha e tentar de novo dentro do próprio ciclo. Essa diferença é o que separa um agente que executa de um agente que entrega.

Vale lembrar que o seu código também faz parte do harness. Ele entra no contexto que o agente consome, e um projeto organizado, com padrões claros, facilita o trabalho do modelo. Boas práticas de codificação continuam valendo justamente porque o código é parte da entrada.

Como diagnosticar um agente que errou, em três camadas

Antes de trocar de modelo, verifique três camadas na ordem, porque cada uma elimina uma classe de problema. A primeira é a instrução. A instrução estava clara ou tinha lacunas que o modelo preencheu por conta própria?

A segunda camada é o contexto. O projeto está estruturado de forma que o agente encontra a informação que precisa? O AGENTS.md está enxuto e apontando para os lugares certos? Existem artefatos desatualizados enviesando o trabalho do agente? Artefato velho é fonte comum de erro silencioso.

A terceira camada são ferramentas e validação. O agente tem o suficiente para testar, compilar e executar o projeto? Ele sabe qual é o critério de conclusão da tarefa? Existe diferença entre corrigir o problema e provar que nada quebrou, e essa diferença precisa estar explícita.

Para começar hoje, o primeiro passo é criar um AGENTS.md com as regras iniciais do seu projeto. Para evoluir, separe o contexto em artefatos por área, adicione sensores que rodem automaticamente e defina critérios de conclusão que o agente consiga verificar sozinho.

FAQ sobre harness engineering

• O que é harness engineering em uma frase? É a engenharia do sistema que cerca o modelo de linguagem: contexto, ferramentas, permissões, regras e critérios de validação. O agente é o modelo somado a esse harness.

• Harness engineering substitui prompt engineering? Não. O prompt continua definindo o que você quer naquele momento, mas passa a ser uma peça dentro de uma estrutura maior. Contexto, ferramentas e validação não são resolvidos por texto de instrução.

• Por que um AGENTS.md muito grande pode piorar o resultado? Porque contexto é um recurso finito. Informações irrelevantes competem com as relevantes, aumentam o consumo de tokens e podem levar o modelo a inferir soluções erradas.

• O que entra em um AGENTS.md enxuto? O mapa do repositório, as regras principais, as restrições de arquitetura e os ponteiros para onde buscar informação detalhada. Ele funciona como índice, não como documentação completa.

• O que são guias e sensores no harness? Guias atuam antes da ação e fornecem contexto, como especificação e AGENTS.md. Sensores atuam depois, como testes, linter e compilador, e geram o sinal que permite ao agente corrigir o próprio erro.

• Preciso trocar de modelo para melhorar meu agente? Nem sempre. Se o gargalo está em instrução ambígua, contexto desorganizado ou ausência de validação, trocar o modelo não resolve o problema.

• Harness engineering vale só para programação? Não. Qualquer fluxo em que um agente precisa executar etapas, usar ferramentas e validar resultado se beneficia da mesma estrutura, inclusive em produto e análise de dados.

• O que o DeepSeek Harness mudou? Ele mostrou uma infraestrutura de harness organizada em plugins, com modelo, ferramenta e armazenamento como peças substituíveis. O valor está em separar o harness do modelo, não em eleger o melhor agente de código.

• Qual o primeiro passo para aplicar isso no meu projeto? Crie um AGENTS.md com as regras iniciais, adicione pelo menos um sensor automatizado e defina um critério de conclusão que o agente consiga verificar sem depender de você.

Do vídeo ao artigo: transforme o que você já sabe em texto

O ponto central deste guia é que o resultado de um agente depende menos do modelo isolado e mais da estrutura que você constrói em volta dele. O mesmo vale para conteúdo: muita gente tem uma explicação boa gravada em vídeo e nunca a transforma em algo pesquisável.

Se você tem aulas, entrevistas, opiniões ou lições registradas em vídeo, dá para reaproveitar esse material. O fluxo é simples: você cola a URL do YouTube, a ferramenta transcreve o vídeo e gera um artigo estruturado a partir do que já foi dito, sem começar do zero.

Esse é o tipo de trabalho que economiza tempo e mantém a sua voz. Conheça o Skala Blog e veja como transformar seu próximo vídeo em texto. Para quem acompanha o ecossistema de ferramentas do mercado brasileiro, vale também conhecer a Crazystack, referência em TypeScript para quem constrói software com stack moderna, e a comunidade do dev doido que discute arquitetura e IA no dia a dia.

Source video