Harness vs context engineering: a diferença entre harness, engenharia de contexto e engenharia de prompt

Em resumo: três camadas para a mesma tarefa

A engenharia de prompt responde «como pedir», a engenharia de contexto responde «o que o modelo precisa saber agora», e a engenharia de harness responde «em que ambiente o agente trabalha e como ele percebe que errou». Não são três abordagens concorrentes, e sim camadas aninhadas: um bom prompt faz parte de um bom contexto, e um contexto bem desenhado é um dos subsistemas do harness.

A confusão acontece porque as três mudam o comportamento do modelo, mas têm alavancas diferentes. Se o agente não consegue rodar testes, nenhuma formulação de prompt resolve isso. Se ele esquece as decisões de ontem, o problema não está no texto do pedido, e sim em onde o estado é guardado. Entender a diferença entre harness vs context engineering economiza semanas: você deixa de reescrever instruções quando o que está quebrado é o ambiente.

Engenharia de prompt: a formulação de uma requisição

A engenharia de prompt trabalha com o texto do pedido: papel, tarefa, formato de saída, exemplos (few-shot), restrições e ordem dos passos. A unidade de trabalho é uma chamada ao modelo. O resultado é avaliado pela resposta: está correta? no formato certo? o modelo se desviou?

Técnicas comuns:

• descrever explicitamente o formato de saída (esquema JSON, tabela, lista);
• dar de dois a três exemplos «entrada → saída correta»;
• pedir raciocínio passo a passo antes da resposta;
• separar instrução e dados com delimitadores claros;
• listar o que não deve ser feito.

A engenharia de prompt funciona bem em tarefas do tipo «uma entrada, uma saída»: classificação, extração de dados, tradução, geração de texto a partir de um modelo. Seu teto aparece quando o modelo começa a agir: chamar ferramentas, alterar arquivos, executar dezenas de passos seguidos. Aí a qualidade não depende de uma frase, mas de tudo o que cerca o modelo.

Engenharia de contexto: o que entra na janela do modelo

A engenharia de contexto é a gestão do conteúdo da janela de contexto a cada passo. A janela é limitada, e um agente em uma sessão longa acumula saída de comandos, conteúdo de arquivos e histórico de conversa. O objetivo é que, em cada momento, esteja ali o que é necessário e nada além disso.

Ela inclui:

• seleção: quais arquivos, documentos e trechos de código carregar para a tarefa (busca, RAG, leitura sob demanda);
• compressão: resumir o histórico longo, cortar a saída de comandos, compactar a sessão;
• estrutura: o arquivo de instruções como sumário, e os detalhes em documentos separados abertos quando preciso;
• isolamento: enviar uma subtarefa a um subagente com contexto próprio e limpo, para não poluir a conversa principal.

A métrica da engenharia de contexto é: o agente encontrou a regra ou o fato certo no momento certo, e não se afogou no ruído? O sintoma típico do problema é a regra estar escrita no CLAUDE.md e o agente violá-la, porque o arquivo tem cinco páginas e a regra se perdeu entre o tom de voz e as preferências do líder da equipe.

Engenharia de harness: tudo o que cerca o modelo

O harness («arreio») é o ambiente em que o agente trabalha. O modelo é uma peça dele, que entra no circuito uma vez. Todo o resto (instruções, ferramentas, ambiente, estado e feedback) é projetado por engenheiros. A engenharia de harness cuida para que o agente consiga não só escrever código, mas executá-lo, verificá-lo, perceber erros e continuar na sessão seguinte exatamente de onde parou.

Dá para decompor o harness em cinco subsistemas:

A engenharia de contexto vive dentro dos dois primeiros subsistemas, porque decide como as instruções e a saída das ferramentas chegam à janela. O harness acrescenta o que não cabe no contexto: um comando de verificação que funciona, um ambiente reproduzível, um arquivo de estado que sobrevive a reinícios.

Tabela comparativa

Por que prompt e contexto não bastam

A história clássica: a equipe percebe que o agente erra e passa uma semana escrevendo um AGENTS.md de cinco páginas. O agente continua sem rodar o linter antes do commit. O motivo não está no texto: o agente simplesmente não tem acesso a um shell com as permissões certas, e o linter não está instalado na imagem. É um problema de ferramentas e ambiente, mas foi tratado com instruções.

Segunda história: o agente tenta corrigir o mesmo bug pela terceira sessão seguida, porque a cada reinício não lembra o que já tentou. A engenharia de contexto dentro da sessão não ajuda: a janela foi zerada. O que falta é o subsistema de estado: um arquivo em que o agente registra tentativas e decisões, e uma regra que o obriga a lê-lo ao começar.

Terceira história, a mais cara: o agente declara «pronto», os testes unitários estão todos verdes, mas a funcionalidade não funciona. Nem um prompt do tipo «verifique com cuidado», nem mais documentos no contexto, dão ao agente uma verificação independente. Quem dá isso é o feedback de uma máquina: um teste de ponta a ponta, um script de verificação ou um avaliador independente que não vê o raciocínio de quem executou.

Resumindo: prompt e contexto influenciam o que o modelo pensa. O harness influencia o que o modelo consegue fazer e o que ele descobre depois de agir.

Por que trocar de modelo não resolve

A reação comum a um agente instável é escolher um modelo mais forte. Normalmente isso não resolve: o mesmo modelo, em um repositório bem organizado, age como um sênior confiante, e em um repositório sem comandos de verificação nem descrição da stack, se perde. Um modelo mais forte não adivinha as convenções da sua equipe, não acessa um banco ao qual não tem permissão e não percebe que uma migração está quebrada se ninguém a executou.

E o harness não envelhece com o lançamento de novos modelos. Instruções, ambiente reproduzível e verificações são necessários a qualquer modelo. O que muda é quanto microgerenciamento pode ser dispensado: um modelo forte precisa de invariantes («dados são validados na fronteira do domínio»), e não de instruções passo a passo.

Como identificar a camada que precisa de conserto

Diagnosticar pelos sintomas é mais rápido do que qualquer experimento:

Por onde começar a construir o harness

Partindo do zero, a ordem prática é: feedback → instruções → estado → ambiente → ferramentas. O feedback vem primeiro porque, sem ele, não dá para medir o efeito das outras mudanças. Enquanto não houver um comando que responda honestamente «funciona ou não», qualquer melhoria nas instruções é avaliada no achismo.

Um começo mínimo:

# AGENTS.md (trecho)
## Como verificar
- make check   # linter, tipos, testes unitários
- make e2e     # cenários de ponta a ponta
A funcionalidade só está pronta se os dois comandos terminarem com código 0.

## Regras
- MUST: todas as consultas SQL são parametrizadas
- MUST: rodar make check antes do commit
- Detalhes de pagamento: docs/payments.md (ler apenas quando a tarefa envolver pagamento)

Repare na última linha: é a engenharia de contexto dentro do harness. O arquivo de entrada é um mapa, não um livro, e os detalhes são carregados sob a condição «quando».

Como medir a contribuição de cada parte

O harness tem uma métrica que o prompt não tem: a proporção de tarefas que o agente declarou concluídas e que a verificação independente não confirmou. Chama-se verification gap (lacuna de verificação). Pegue 10 tarefas seguidas e, em cada uma, anote se o agente disse «pronto» e se a verificação passou. Você terá um número para comparar as mudanças.

Para descobrir qual subsistema realmente faz diferença, use a ablação: fixe o modelo e o conjunto de tarefas, desligue uma parte do harness por vez e veja quanto a qualidade cai. Dois cuidados. Primeiro, a ablação não é o primeiro passo: comece pelo diário de falhas, que aponta o gargalo, e use a ablação para confirmar. Segundo, cair zero ao remover um componente não prova que ele é inútil: talvez o conjunto de tarefas não o tenha usado.

Erros comuns

• Tratar o harness como um arquivo de prompt.As instruções são um dos cinco subsistemas. Uma prateleira de receitas não é uma cozinha.
• Tentar resolver falta de ferramentas com texto.«Sempre rode os testes» não adianta se os testes não rodam no ambiente do agente.
• Inflar as instruções.Quanto maior o arquivo de entrada, maior a chance de a regra importante não ser lida. Transforme as regras importantes em verificações executáveis.
• Acreditar na autoavaliação do agente.Um modelo que avalia o próprio trabalho tende a superestimá-lo. A verificação deve ser feita por um script ou por um agente independente com contexto limpo.
• Configurar o harness uma vez só.Ele envelhece como código: as regras se afastam da realidade e os comandos mudam. Precisa de revisão periódica.

Conclusão

A engenharia de prompt melhora a formulação, a engenharia de contexto seleciona o que entra na janela do modelo, e a engenharia de harness projeta o ambiente completo do agente, incluindo ferramentas, execução, estado e verificações. Quando o agente trabalha por longos períodos e altera o código sozinho, o harness se torna o mais importante, porque transforma «o agente disse que está pronto» em «o sistema confirmou que funciona». Portanto, harness vs context engineering não é uma escolha de um ou de outro: o contexto faz parte do harness, e o que deve ser consertado é a camada que os sintomas apontam. Esse tema é explicado na prática no curso de harness engineering, em um projeto real de backend de pagamentos.