Harness engineering: pare de trocar o modelo e conserte o harness

Você não mexe nos pesos do modelo. Mas é dono de cada linha de código em volta dele. Esse código é o harness, e é nele que mora quase toda a sua vantagem.

Toda semana alguém me conta que o agente ficou mais inteligente porque trocou para um modelo mais novo. Às vezes é verdade. Na maioria das vezes, a pessoa mexeu na única variável que não controla e deixou intocada a que controla.

Coloco código em produção há 25 anos. No fim de 2025, construí sozinho uma fintech cripto com 13 apps usando agentes de IA, em 70 dias. O estudo de caso tem os números reais. A parte que ninguém coloca na landing page é esta: o modelo que usei era o mesmo que todo mundo tinha. A diferença não estava na inteligência. Estava na estrutura que montei em volta dele. O harness.

Este é um guia para melhorar esse harness. Se você quer a definição direta primeiro, leia o que é um harness de agente. Esta página é a prática de deixar o seu mensuravelmente melhor, de quem roda um harness mínimo todo dia.

Agente é modelo mais harness

Comece pela definição mais limpa que alguém já publicou. A LangChain resumiu em quatro palavras: Agent = Model + Harness. O modelo fornece a inteligência. O harness torna essa inteligência útil.

Desmonte um harness e sobram quatro partes, e todo texto sério chega nas mesmas quatro: um loop do agente que continua chamando o modelo até o trabalho terminar, uma interface de ferramentas pela qual o modelo age, um gerenciamento de contexto que decide o que o modelo vê a cada turno e mecanismos de controle que impedem a coisa toda de despencar de um penhasco.

Repare no que está nessa lista. Nada ali é o modelo. Tudo ali é seu. Quando falam de “prompt engineering”, estão falando de uma mensagem. Quando falam de “context engineering”, estão falando de uma janela. Harness engineering é a camada acima das duas: projeta o sistema que reinicia o contexto, passa o estado de uma sessão para a outra e verifica o resultado antes de ir para produção. É a camada com mais espaço para ganho, e é a camada que quase ninguém está construindo de propósito.

A indústria está melhorando harnesses ao contrário

Este é o reflexo padrão quando um harness rende pouco: adicionar coisa. Pendurar mais um MCP server. Injetar mais instruções no system prompt. Disparar um subagent para ir buscar contexto. Ligar um modo de planejamento, um serviço de memória, um roteador.

Cada uma dessas adições consome o único recurso que o modelo gasta antes de escrever uma linha sequer: o context window.

Mario Zechner, que criou o agente de código pi, resumiu a frustração sem rodeios: os harnesses mais populares ficaram opacos e instáveis porque os system prompts e o contexto injetado viviam mudando pelas costas do usuário. Você não melhora o que não enxerga. E não enxerga um harness que esconde metade do que entrega ao modelo.

A correção contraintuitiva, a que funciona de verdade: deixar o harness menor e mais transparente, em vez de maior e mais esperto.

Um harness que dá para enxergar

Para melhorar um harness, você precisa de um que caiba na sua cabeça. É por isso que uso o pi, um agente de código open source da earendil-works. Não porque ele tem mais funcionalidades. Porque tem o mínimo possível, e não esconde nenhuma.

pi, o harness inteiro de relance

4

ferramentas nativasread, write, edit, bash

~150

palavras de system prompte não milhares de tokens

0

MCP servers por padrãoferramentas de CLI no lugar

BYOK

qualquer provedorClaude, GPT, Gemini, local

O pi dá ao modelo quatro ferramentas: read, write, edit e bash. O system prompt tem umas 150 palavras, partindo da ideia de que um modelo de fronteira treinado em milhões de sessões de programação já sabe ser um agente de código e não precisa de mil tokens lembrando disso. O loop do agente cabe em uma página de lógica: chama o modelo, executa as ferramentas que ele pediu, devolve os resultados, repete até ele parar de pedir. É só isso.

Não é brinquedo. O ponto de um harness transparente é que, quando o agente faz besteira, você vê exatamente qual das quatro partes causou o problema e corrige aquela parte. Tente fazer isso com um harness que injeta contexto que você não tem permissão de ler.

✗

O harness pesado

1. 01System prompt com milhares de tokens de estrutura
2. 02Três MCP servers comem a janela antes de você digitar
3. 03Contexto injetado onde você não consegue inspecionar
4. 04Subagents disparam invisíveis e devolvem um resumo
5. 05Você depura o modelo porque não enxerga o harness

✓

O harness mínimo

1. 01System prompt de 150 palavras que o modelo já entendia
2. 02Zero MCP servers, ferramentas de CLI com help legível
3. 03Cada token na janela é um que você sabe nomear
4. 04Subagents são explícitos: você chama o pi pelo bash e acompanha
5. 05Você depura o harness porque consegue ler tudo

Os três eixos que você controla de verdade

Quando você enxerga o harness, melhorar deixa de ser vago. Toda mudança que vale a pena mexe em exatamente uma de três coisas: o que o modelo vê, o que o modelo pode fazer e o que sobrevive quando a sessão termina. Domine esses três e você fez engenharia no seu harness. Ignore e você só está trocando de modelo e torcendo.

Onde estão os ganhos de verdade

1. 01

   O que o modelo vê

   O context window é um orçamento rígido, não uma sugestão. Cada token gasto com boilerplate, output cru de ferramenta ou um schema de MCP que o modelo nunca usa é um token a menos para o seu problema real. Melhorar o harness começa por defender a janela.

   Corte o system prompt. Filtre o output das ferramentas na origem.
   Tire os MCP servers que você não usa todo dia.

   +
2. 02

   O que o modelo pode fazer

   Ferramentas são as mãos do modelo. Mais ferramentas não significa mais capacidade. Significa mais superfície e mais custo em tokens. Um punhado de ferramentas afiadas e combináveis, mais um shell, ganha de uma parede de ferramentas estreitas. Prefira progressive disclosure a um cardápio maior.

   read, write, edit e bash cobrem a maior parte do trabalho.
   Só adicione uma ferramenta quando bash mais uma CLI realmente não der conta.

   +
3. 03

   O que sobrevive à sessão

   O modelo esquece tudo no momento em que o contexto reinicia. Memória não se compra. Se escreve: um arquivo de instruções, um plano, um log de progresso, commits. O harness que persiste estado de forma limpa é o que entrega trabalho grande.

   AGENTS.md, PLAN.md, um log de progresso, um commit por feature.
   A spec é a memória que o agente não tem.

O resto deste guia é uma seção por eixo, com os movimentos concretos que eu faço.

Eixo um: defenda o context window

O context window é o único recurso de fato escasso no sistema inteiro, e a maioria dos harnesses gasta como se fosse de graça. Os dois maiores vazamentos são o system prompt e o output cru das ferramentas.

O vazamento do system prompt é fácil. Leia o seu. Cada frase que diz a um modelo de fronteira algo que ele já faz certo é uma frase que você paga em todo turno, para sempre. A resposta do pi é um prompt de 150 palavras. O seu não precisa ser tão curto, mas aplique o teste: se apagar uma linha não piora o agente, a linha é ruído. Corte.

O vazamento do output das ferramentas é maior e mais silencioso. Um único git status num repositório movimentado pode dar dois mil tokens. Uma rodada completa de testes pode dar vinte e cinco mil. O modelo não precisa de tudo isso, precisa do sinal, mas um harness ingênuo despeja a enxurrada inteira na janela e chama isso de contexto.

Essa é a mudança de maior retorno que você pode fazer num harness, e quase ninguém faz, porque os tokens vazam num lugar para onde você nunca olha: dentro dos resultados das ferramentas. Coloque um filtro ali e toda sessão, em todo projeto, fica mais barata e mais precisa de uma vez.

Para onde a janela vai de verdade

Quatro vazamentos, quatro correções. Nenhuma exige um modelo mais inteligente. Todas são puro trabalho de harness.

O que carrega	Harness pesado	Harness mínimo
System prompt	milhares de tokens, todo turno	~150 palavras que o modelo já sabia
MCP servers	13k a 18k tokens cada, antes de você digitar	nenhum; ferramentas de CLI com help legível
Output das ferramentas	despejo cru, 2k a 25k tokens por chamada	filtrado na origem, 60 a 90% menor
Turnos antigos	o mesmo arquivo lido cinco vezes	compactados periodicamente, só o delta

Quando a janela enche mesmo assim, a compactação é a sua válvula de escape. O pi roda a compactação automaticamente quando a janela se aproxima do limite, e oferece /compact para gerar sob demanda um resumo dos turnos mais antigos, mantendo os recentes intactos. O histórico completo fica no disco em JSONL, então nada se perde, só o conjunto de trabalho encolhe. Essa é a diferença entre compactação e amnésia.

Eixo dois: menos ferramentas, mais afiadas

O instinto de adicionar ferramentas é o instinto que estraga harnesses. Cada ferramenta registrada custa tokens pela definição em todo turno e dilui a escolha do modelo com mais uma opção para ele errar. A pergunta nunca é “que ferramenta eu poderia adicionar”. É “que ferramenta precisa existir porque o shell realmente não dá conta”.

A resposta do pi é direta e quase sempre certa: read, write, edit e bash bastam para um agente de código eficaz. O bash é a chave mestra. Não é uma ferramenta. É toda ferramenta de linha de comando que você já instalou, embrulhada numa documentação que o modelo lê sob demanda. Isso é progressive disclosure bem feito. O modelo não carrega mil schemas de ferramentas na janela. Ele roda --help quando precisa.

Isso não quer dizer que MCP está errado. Quer dizer que MCP é um custo, e custo precisa se pagar. Se um server é essencial no seu trabalho diário, mantenha. Se está carregado “por via das dúvidas”, é um imposto que você paga em todo turno por uma capacidade que quase não usa. Aqui, melhorar o harness é basicamente subtração: audite suas ferramentas, fique com as que o bash não substitui e corte o resto.

Essa ferramenta merece estar no harness?

• ✗Anti-pattern:
  Bash mais uma CLI instalada já fazem isso?Então a ferramenta é redundante. Apague e deixe o modelo usar o shell. O help da CLI é o schema dela, carregado sob demanda.
• ✓Obrigatório:
  Eu uso essa capacidade na maioria das sessões?Se sim, uma ferramenta dedicada ou um MCP server paga o próprio custo em tokens. Se não, é um imposto por via das dúvidas em todo turno.
• ✓Obrigatório:
  A descrição da ferramenta é curta e sem ambiguidade?Uma ferramenta que o modelo interpreta errado é pior que nenhuma. Nomes precisos e descrições de uma linha ganham de schemas enormes.
• ✓Obrigatório:
  Quando ela roda, consigo ver exatamente o que fez?Uma ferramenta cujos efeitos você não consegue inspecionar é um beco sem saída na hora de depurar. Prefira explícito e visível a mágico e escondido.

Quando você precisa mesmo estender o pi, faz isso do jeito transparente: um arquivo de extensão que registra uma ferramenta que você consegue ler, ou chamando o próprio pi pelo bash como subagent explícito, para ver ele trabalhando em vez de confiar no resumo de um escondido. Foi por esse caminho que adicionei o único controle de que sentia falta do OpenCode: roteamento de modelo por fase. Um pacote pequeno que escrevi lê um modelo e um nível de raciocínio de cada skill e troca para eles no momento em que a skill carrega, então a exploração roda num modelo barato e a construção num preciso. É o que o OpenCode chama de modes, adicionado como um pacote que consigo ler em vez de uma feature que fico esperando. O guia do pi tem o setup. A regra do Zechner ficou comigo: recorrer a um subagent no meio da sessão para ir buscar contexto geralmente é sinal de que você não planejou o contexto antes.

Eixo três: dê uma memória ao agente

Este é o eixo que separa uma demo de um sistema. O modelo não tem estado. Esquece tudo no instante em que a sessão termina. A Anthropic tem a analogia que deixa isso concreto.

Imagine um projeto de software tocado por engenheiros que trabalham em turnos, em que cada novo engenheiro chega sem nenhuma memória do que aconteceu no turno anterior.

Esse é o seu agente em toda tarefa longa. A solução não é um context window maior nem um produto de memória mais sofisticado. São arquivos deliberados, chatos e duráveis que o próximo turno lê primeiro. O sistema de arquivos, como diz a LangChain, é a primitiva mais fundamental de um harness, e memória é só o harness usando isso de propósito.

Quatro artefatos seguram a carga:

• Um arquivo de instruções que o harness carrega em toda sessão. O pi lê automaticamente o AGENTS.md do projeto e dos diretórios pais. Mantenha enxuto: o que é o projeto, as convenções que não são óbvias e ponteiros para todo o resto. Se remover uma linha não causa erros, corte.
• Um plano que vive no disco, não na cabeça do modelo. O pi deliberadamente não tem um modo de planejamento escondido. O planejamento vai num PLAN.md ou TODO.md que sobrevive à sessão, fica visível e continua editável por você. Um plano que o modelo não consegue perder é um plano em que dá para confiar.
• Um log de progresso que o agente atualiza antes de a sessão terminar e lê quando ela começa. A receita da Anthropic para agentes de longa duração é exatamente isso: ler as notas de progresso e o git log, rodar os testes end-to-end e então pegar a próxima parte inacabada. Chato. Confiável.
• Commits como memória. Um commit limpo por feature não é higiene. É estado. Dá ao próximo turno um histórico legível e dá a você um rollback quando um turno dá errado.

O stack que eu rodo

Princípio é barato. Este é o sistema que uso para torná-los reais: três camadas, cada uma matando um tipo diferente de desperdício de tokens, mapeadas direto nos três eixos.

Três camadas, três tipos de desperdício

1. L1

   RTK, a camada de ferramentas

   Um proxy de CLI que comprime o output dos comandos antes que ele chegue ao modelo. É a camada em produção, essencial, que rodo todo dia. É a correção do eixo um na fronteira das ferramentas: menos output inútil, 60 a 90 por cento a menos nos comandos do dia a dia.

   git status  → um punhado de tokens
   rodada de testes → as falhas que importam

   +
2. L2

   Compressão, a camada da conversa

   Entre os turnos, colapsar o que não mudou: o mesmo arquivo lido cinco vezes, o mesmo erro impresso três vezes, o plano repetido em cada passo. O modelo vê o delta, e não a transcrição inteira de novo. Eixo um, um nível acima das ferramentas.

   Deduplique leituras. Reduza sucessos a uma linha.
   Mantenha só o que mudou.

   +
3. L3

   Memória, a camada de conhecimento

   Contexto persistente do projeto carregado no início da sessão, para você nunca mais reexplicar o stack, as convenções, as decisões. É o eixo três ligado ao harness em vez de aos seus dedos: o agente começa sabendo, não perguntando.

   Carregue decisões e convenções automaticamente.
   A próxima sessão começa onde a última terminou.

O RTK é real e eu uso hoje. As camadas de compressão e memória são as que estou construindo num único proxy local-first que fica entre qualquer agente e o modelo, para o stack inteiro ir comigo no pi, no Claude Code ou em qualquer coisa que fale com um endpoint compatível com OpenAI. A arquitetura completa e a conta dos tokens estão no mergulho sobre custo de tokens. O ponto por ora é menor e difícil de contestar: os maiores ganhos num harness não são espertos, são encanamento. Coloque o filtro onde os tokens vazam e toda sessão fica mais barata de uma vez.

O loop é a última milha

Contexto, ferramentas e memória equipam uma única execução do agente. O loop do agente é o que transforma essas execuções em trabalho terminado. Mantenha simples e faça ele verificar.

Um loop de harness que termina de verdade

Entrada

Uma feature a construir, descrita como um comportamento que o sistema precisa ter

↓

1. READCarregar a memória

   A sessão abre lendo o arquivo de instruções, o plano, o log de progresso e o histórico do git. O novo turno aprende o que o turno anterior fez antes de tocar em qualquer coisa.

   ↓
2. LOOPChamar, agir, devolver

   O modelo chama ferramentas, o harness executa e devolve os resultados filtrados, e repete até o modelo parar de pedir. Sem limite arbitrário de passos. O trabalho pronto é a condição de parada.

   ↓
3. VERIFYProvar de ponta a ponta

   Não confie no que o agente diz sobre si mesmo. Rode os testes. A Anthropic descobriu que os agentes verificam features de forma confiável quando recebem a instrução explícita de rodar checagens end-to-end reais, incluindo automação de browser, em vez de só bater o olho no diff.

   ↓
4. PERSISTCommitar e registrar

   Um commit limpo para a feature, o log de progresso atualizado, o plano avançado. Agora a janela pode reiniciar sem perda nenhuma, porque o estado vive no disco, e não no contexto.

↓

Saída

Uma sessão que termina deixando para a próxima tudo o que ela precisa para continuar

A armadilha nessa etapa é deixar o loop declarar vitória pela própria palavra. Um harness que pergunta ao modelo “funcionou?” recebe a resposta que o modelo quer dar. Um harness que roda a suíte de testes e lê o exit code recebe a verdade. Verificação não é um extra pendurado no final. É o mecanismo de controle que torna seguro deixar o loop rodando sozinho.

A AWS chegou à mesma conclusão na escala de um ciclo de desenvolvimento inteiro. No AI-DLC 2, quem decide o que roda depois é um motor determinístico, não o modelo, e uma Unit de trabalho só conta como verificada por um comando de checagem que uma pessoa aprovou e por um recibo que a própria ferramenta escreve. A palavra do modelo não é prova. Destrinchei esse desenho em AI-DLC 2: o que mudou.

O veredito: o mínimo ganha

Coloque as duas filosofias lado a lado e dê nota pelo que importa de verdade para quem opera o agente, e não para quem vende.

Harness pesado vs harness mínimo

Harness pesado vs harness mínimo. Winner: Harness mínimo with a weighted score of 53. Scale 1-5 (5 = best).

Critério (peso)	Harness que faz de tudo	Harness mínimo
Transparência (3)	2	5
Custo em tokens (3)	2	5
Controle (2)	2	5
Verificabilidade (2)	3	4
Portabilidade (1)	2	5
Pontuação ponderada	24	53

Scale 1-5 (5 = best). Highlighted column: winner by weighted score.

O harness que faz de tudo não foi feito para ser melhorado. Foi feito para impressionar na primeira execução e para você não olhar de perto depois. O harness mínimo é o oposto. Ele parte do princípio de que você vai querer mudá-lo, então mostra tudo e quase não custa nada para entender. O jogo é esse.

Faça isto no seu harness esta semana

Você não precisa reconstruir nada. Escolha os vazamentos e tape na ordem de retorno.

Revisão do harness, maior retorno primeiro

• ✓Obrigatório:
  Coloque um filtro de compressão no output das ferramentasO maior ganho isolado. O output cru dos comandos é onde a janela morre em silêncio. Filtre no shell antes que chegue ao modelo e recupere de 60 a 90 por cento nos comandos do dia a dia.
• ✓Obrigatório:
  Leia seu system prompt e corte toda linha que o modelo já obedeceVocê paga por ele em todo turno. Se apagar uma linha não piora o agente, era ruído.
• ✓Obrigatório:
  Audite seus MCP servers e tire os que estão lá por via das dúvidasFique só com o que você usa na maioria das sessões. O resto é um imposto por turno para um retorno raro. Troque por uma CLI que o modelo roda pelo bash.
• ✓Obrigatório:
  Escreva os quatro artefatos de memóriaUm arquivo de instruções, um plano no disco, um log de progresso e um commit por feature. É isso que deixa o agente sobreviver a um reset de contexto sem perder o fio.
• ✓Obrigatório:
  Faça o loop verificar com testes reais, não com autoavaliaçãoLigue o loop para rodar a suíte e ler o exit code. Um harness que confere o próprio trabalho é o que você pode deixar rodando.
• •Opcional:
  Troque para um harness que você consegue ler de ponta a pontaNão é obrigatório, mas tudo acima fica mais fácil num harness transparente e agnóstico de provedor como o pi. Você não ajusta o que não tem permissão de ver.

O modelo é commodity. O harness é a sua vantagem.

Todo laboratório vai lançar um modelo mais inteligente no próximo trimestre, e todos os seus concorrentes recebem o mesmo upgrade no mesmo dia. A sua vantagem não está aí. Nunca esteve.

A sua vantagem é o harness. É a única parte do sistema que é totalmente sua, a única que acumula com o seu julgamento em vez de zerar com o calendário de lançamentos de outra empresa. Um modelo modesto num harness afiado, transparente e bem alimentado vai entregar mais que um modelo de fronteira num harness inchado, sempre, porque o gargalo nunca foi a inteligência. Foi tudo o que você colocou em volta dela.

Pare de trocar o modelo e torcer. Abra o harness e conserte.

Harness engineering, respostas rápidas

O que é harness engineering?+

Harness engineering é a prática de projetar tudo em volta de um modelo de IA que não é o próprio modelo: o loop do agente, as ferramentas, o gerenciamento de contexto e a lógica de controle e verificação.

Fica acima do prompt engineering, que otimiza uma mensagem, e do context engineering, que faz a curadoria de uma janela. Harness engineering projeta o sistema inteiro que reinicia o contexto, persiste estado entre sessões e confere o resultado.

Harness engineering é a mesma coisa que context engineering?+

Não. Context engineering trata do que o modelo vê dentro de um único context window. Harness engineering é a camada acima.

O gerenciamento de contexto é uma das quatro partes de um harness, ao lado do loop do agente, da interface de ferramentas e dos mecanismos de controle. Então context engineering é um componente de harness engineering, e não um sinônimo.

Como eu melhoro na prática o harness do meu agente de IA de código?+

Trabalhe os três eixos que você controla. Defenda o context window cortando o system prompt e filtrando o output das ferramentas. Mantenha poucas ferramentas e afiadas, apoiando-se no bash em vez de uma parede de MCP servers. Dê ao agente memória durável com um arquivo de instruções, um plano, um log de progresso e commits limpos.

Depois, faça o loop verificar o próprio trabalho com testes reais. Nada disso exige um modelo melhor.

Preciso de MCP servers para construir um bom agente?+

Não. Um MCP server popular pode custar de 13k a 18k tokens de contexto antes de você digitar qualquer coisa, e você paga isso o modelo usando ele ou não. Na maior parte do trabalho de código, deixar o modelo rodar pelo bash as ferramentas de CLI que você já tem é mais barato e mais transparente.

Mantenha os MCP servers que você usa na maioria das sessões. Tire os que estão lá por via das dúvidas.

O que é o pi e por que usar ele como exemplo?+

O pi é um agente de código open source e agnóstico de provedor, da earendil-works. Vem com quatro ferramentas, um system prompt de umas 150 palavras e um loop do agente que dá para ler em uma página.

Ele é o exemplo aqui porque um harness mínimo e transparente é o que você consegue de fato estudar e melhorar. Quando algo dá errado, você vê qual parte causou o problema, o que é impossível num harness que esconde o próprio contexto.

Um harness mínimo rende menos que um cheio de features?+

Não nos eixos que importam. O pi se defende bem no Terminal-Bench 2.0 com quatro ferramentas e um prompt minúsculo, o que sugere que estrutura verbosa entrega menos do que cobra.

Um harness mínimo ganha em transparência, custo em tokens, controle e verificabilidade. São exatamente as propriedades que permitem continuar melhorando o harness, e que um harness opaco e cheio de features tira de você.