Engenharia de Harness para Agentes

Problema: Você atualizou o modelo. O desempenho quase não mudou. Você continua vendo os mesmos padrões de falha, sessão após sessão, independente da versão do modelo que usa.

Resultado rápido: Para de ajustar o modelo. Ajuste o harness. Um time reduziu de 15 ferramentas para uma única chamada bash e viu a precisão saltar de 80% para 100%, enquanto o uso de tokens caiu 37%.

Entenda assim: Agente = Modelo + Harness. O modelo cuida do raciocínio. O harness cuida de todo o resto: quais ferramentas o agente pode acessar, que contexto ele recebe, como os erros aparecem, como os resultados são verificados. Na prática, o harness é a restrição real do desempenho no mundo real, não o modelo.

O Que o Harness Realmente É

O harness é a camada de software que envolve um modelo de IA e gerencia tudo, exceto o raciocínio do modelo. Ele chama ferramentas. Gerencia memória. Roteia tarefas. Executa verificações. Decide que contexto chega na janela de prompt e em que forma.

A definição de Martin Fowler é precisa: o harness é tudo em um agente, exceto o modelo em si. Duas direções de controle passam por ele:

• Feedforward (guias): direciona o agente antes de ele agir. Prompts de sistema, injeção de contexto, restrições de ferramentas. Aumentam a probabilidade de que a primeira saída seja correta.
• Feedback (sensores): observam depois que o agente age e permitem autocorreção. Linters, verificadores de tipos, executores de testes, hooks de build. Capturam erros antes de chegarem aos olhos humanos.

Nenhuma das direções sozinha é suficiente. Feedback sem feedforward produz um agente que corrige os mesmos erros repetidamente. Feedforward sem feedback produz um agente que codifica regras, mas nunca aprende quando elas falharam.

Por Que o Design do Harness Supera Upgrades de Modelo

O ranking do SWE-bench deixa isso claro. Em benchmarks de código, o mesmo modelo pode pontuar 42% com um scaffold e 78% com um melhor. O modelo não mudou. O harness mudou.

O caso da Vercel é o exemplo mais claro em circulação. O time deles reduziu um agente de 15+ ferramentas para uma única ferramenta bash. No benchmark deles: a precisão foi de 80% para 100%, os tokens caíram 37%, e a velocidade melhorou 3,5x. Eles não tocaram no modelo. Removeram a complexidade do harness.

O padrão se repete em vários times. O time de IA jurídica da Harvey melhorou a conclusão de tarefas de 40,8% para 87,7% ao melhorar o sistema ao redor do modelo. O time interno de tooling da OpenAI concluiu: "Nossos desafios mais difíceis agora estão no design de ambientes, loops de feedback e sistemas de controle."

O modelo é o motor. O harness é o carro. Fazer upgrade no motor ajuda. Construir um carro melhor costuma ser a jogada de maior alavancagem.

Os Cinco Pontos de Controle

Todo harness é construído a partir do mesmo conjunto de pontos de controle. Usar os certos na ordem certa é onde está a arte.

1. Design de Ferramentas

As ferramentas disponíveis para um agente definem sua superfície de capacidade. Ferramentas demais e o agente desperdiça contexto em desambiguação. De menos e ele recorre a workarounds. O resultado da Vercel é a referência canônica: ferramentas em menor quantidade, mais precisas, superam um toolkit geral amplo.

Projete ferramentas com base em resultados, não capacidades. Uma ferramenta chamada run_tests supera uma chamada execute_command porque o agente não precisa decidir o que executar.

2. Injeção de Contexto

O que o agente sabe antes de agir determina o que ele produz. Injeção de contexto significa colocar a informação certa na janela de prompt no momento certo: docs de arquitetura, padrões de código, erros recentes, a árvore de arquivos atual.

O modo de falha é a super-injeção: inundar a janela com tudo que está disponível. Contexto relevante no momento certo supera um dump grande e indiferenciado.

3. Arquitetura de Memória

Um agente de sessão única esquece tudo quando a janela fecha. Um agente bem harnessado carrega para frente: decisões tomadas, padrões observados, erros vistos antes. A memória pode ser de curto prazo (estado da conversa), médio prazo (logs de sessão) ou longo prazo (arquivos persistentes que o agente lê ao iniciar).

O arquivo CLAUDE.md do Claude Code é um ponto de controle de memória de longo prazo. O agente o lê no início de cada sessão. O que você coloca lá molda todas as sessões que vêm depois.

4. Loops de Verificação

O harness executa verificações que o agente não pode pular. Verificadores de tipos, linters, comandos de build, suites de testes. Quando esses rodam como sensores automáticos após cada ação do agente, os erros aparecem na mesma sessão que os criou. O custo da correção cai.

O princípio: mantenha as verificações de qualidade o mais à esquerda possível. Um erro de tipo capturado antes do commit custa segundos. O mesmo erro capturado em uma revisão custa uma hora.

5. Design de Restrições

O que o agente não pode fazer importa tanto quanto o que ele pode. Restringir acesso de escrita a configs de produção, bloquear certas chamadas de ferramentas, limitar quais arquivos um agente pode tocar são todos pontos de controle de restrição. O objetivo não é paralisar o agente, mas eliminar a classe de erros que as restrições tornam impossível.

O Paradoxo das Restrições

Adicionar mais regras a um agente não produz, de forma confiável, um comportamento melhor. Esse é o paradoxo das restrições: um harness sobrecarregado de instruções pode degradar o desempenho abaixo do que o agente alcança com orientação mínima.

O mecanismo é simples. Cada restrição ocupa contexto. Regras contraditórias criam ruído que o agente precisa navegar. Um conjunto longo de instruções que cobre cada caso limite frequentemente performa pior do que um curto e claro que cobre os cinco mais importantes.

A resolução prática é a priorização. Identifique os modos de falha que realmente se repetem. Escreva restrições para esses. Deixe todo o resto para o julgamento do modelo. O harness deve eliminar as falhas que acontecem com frequência, não tentar enumerar todos os resultados ruins possíveis.

Controles Computacionais vs. Inferenciais

Os controles do harness se dividem em dois tipos.

Controles computacionais são determinísticos e rápidos. Verificadores de tipos, linters, executores de testes, sistemas de build. Rodam em milissegundos a segundos. Os resultados são confiáveis e baratos o suficiente para rodar em cada ação do agente.

Controles inferenciais usam um modelo como juiz. Agentes de revisão de código, verificações de qualidade semântica, padrões "LLM-como-avaliador". São mais lentos, mais caros e não determinísticos. Capturam o que os controles computacionais perdem: duplicação semântica, padrões mal aplicados, instruções mal entendidas.

A divisão prática: execute controles computacionais em cada mudança, automaticamente. Execute controles inferenciais seletivamente, em mudanças de maior risco ou pós-integração. As duas camadas são complementares, não competitivas.

Três Categorias de Harness

Um harness regula diferentes dimensões da saída do agente. Distinguir entre elas ajuda porque os controles certos diferem por categoria.

Harness de manutenibilidade: guias e sensores em torno da qualidade do código, estilo e estrutura. É a categoria mais fácil de construir. O tooling existente (linters, verificadores de tipos, ferramentas de cobertura) se encaixa diretamente. A maioria dos times começa aqui.

Harness de fitness arquitetural: guias e sensores que impõem restrições estruturais. Limites de módulos, regras de dependência, orçamentos de desempenho. As funções de fitness rodam como verificações automatizadas. A deriva arquitetural é capturada em vez de descoberta meses depois em uma revisão.

Harness de comportamento: guias e sensores em torno da correção funcional. É a categoria mais difícil. Suites de testes geradas por IA ainda não são confiáveis o suficiente para substituir completamente o comportamento especificado. A maioria dos times atualmente combina documentos de especificação (feedforward) com testes gerados por IA mais verificação manual seletiva (feedback). O problema em aberto é construir confiança suficiente nos testes gerados pelo agente para reduzir a supervisão manual.

Pontos de Partida para Claude Code

Claude Code expõe vários pontos de controle do harness diretamente.

CLAUDE.md é o seu controle feedforward principal. Decisões de arquitetura, convenções de nomenclatura, padrões a seguir ou evitar, regras explícitas sobre o que o agente não deve fazer. Esse arquivo carrega no início de cada sessão. O que você coloca aqui molda o comportamento padrão do agente sem qualquer prompt.

.claude/agents/ as definições de especialistas permitem restringir o escopo por agente. Um agente de banco de dados que só pode tocar em arquivos de migração não pode acidentalmente modificar componentes de frontend. A restrição de escopo é uma das restrições mais baratas de adicionar.

Hooks permitem conectar sensores computacionais ao loop do agente. Um hook pós-edição que roda o verificador de tipos significa que cada mudança de arquivo é validada antes de o agente passar para a próxima tarefa.

Regras de permissão em settings.json definem quais ferramentas o agente pode acessar. Começar com menos ferramentas e expandir é melhor do que começar com tudo e tentar restringir depois.

O bom harness não tem como objetivo eliminar totalmente a intervenção humana. Ele direciona a atenção humana para onde ela importa mais: as decisões que os sensores não conseguem capturar e que o julgamento, não as regras, deve resolver.

Perguntas Comuns

O que é engenharia de harness para agentes?

Engenharia de harness para agentes é a prática de projetar tudo ao redor de um modelo de IA, exceto o modelo em si. Isso inclui seleção de ferramentas, injeção de contexto, arquitetura de memória, loops de verificação e design de restrições. O harness determina que informação o agente recebe, que ações ele pode tomar e como os erros são detectados e corrigidos antes de chegarem à revisão humana.

Por que o harness importa mais do que o modelo?

Nos benchmarks de código SWE-bench, o mesmo modelo pontua 42% com um scaffold e 78% com um melhor. A Vercel removeu 80% das ferramentas do agente e viu a precisão saltar de 80% para 100%, com 37% menos tokens usados. O raciocínio do modelo é fixo. O harness determina quanto dessa capacidade de raciocínio realmente chega à tarefa.

O que é um scaffold de agente de IA?

Um scaffold é a camada estrutural construída ao redor de um modelo de IA para permitir tarefas complexas de múltiplos passos. Ele fornece ao agente ferramentas para chamar, memória para ler e escrever, um loop para reexecutar após erros e sinais de feedback para autocorrigir. Scaffold e harness são usados de forma intercambiável na maioria dos contextos. A distinção, quando feita, é que um harness enfatiza controle e governança, enquanto um scaffold enfatiza estrutura e habilitação.

Como construo um bom harness para agentes?

Comece pelos cinco pontos de controle na ordem: design de ferramentas primeiro, depois injeção de contexto, depois memória, depois loops de verificação, depois restrições. Para cada ponto, identifique os modos de falha que você realmente observa, não os teóricos. Construa o controle mais simples que previne cada falha. Execute verificações computacionais (verificador de tipos, linter, testes) automaticamente após cada ação do agente. Adicione controles inferenciais apenas onde os computacionais não conseguem chegar.

O que é o paradoxo das restrições em agentes de IA?

Adicionar mais restrições não melhora, de forma confiável, o comportamento do agente. Um conjunto longo e exaustivo de regras frequentemente performa pior do que um curto e claro porque cada restrição consome contexto e regras contraditórias criam ruído. A resolução é a priorização: identifique os modos de falha que se repetem com mais frequência e escreva restrições apenas para esses. Deixe todo o resto para o julgamento do modelo.

Por que a Vercel cortou de 15+ ferramentas para uma?

O time da Vercel descobriu que um conjunto amplo de ferramentas forçava o agente a gastar contexto em desambiguação, decidindo qual ferramenta chamar em vez de como resolver o problema. Cortar para uma única ferramenta bash removeu esse overhead. A precisão foi de 80% para 100%, os tokens caíram 37%, e a velocidade melhorou 3,5x no benchmark deles. O princípio: ferramentas em menor quantidade e mais precisas superam um toolkit geral amplo.

Explore Mais Conceitos de Agentes:

• Padrões de Agentes: Formatos de orquestração para trabalho com múltiplos agentes
• Fundamentos de Agentes: Sub-agentes, slash commands e personas no CLAUDE.md
• Design de Sub-Agentes: Padrões de arquitetura para coordenar múltiplos agentes
• Orquestração de Times: Loops de construtor e validador na prática
• Agentes Customizados: Escrevendo definições de agentes especialistas