Agent Harness Engineering na prática

Se você usa agentes para programar, vale internalizar uma ideia simples:

o agente não é modelo.

Na prática, o que chamamos de agente é:

agente = modelo + harness

O modelo pensa e gera texto/código. O harness define o ambiente, as regras, as ferramentas, os limites e os loops de validação.

É justamente esse segundo bloco que mais impacta qualidade, previsibilidade e velocidade em trabalho real.

Este artigo é uma leitura aplicada, em português, baseada nos textos do Addy Osmani, Viv Trivedy e da equipe da Cursor sobre harness engineering na prática.

O que é harness, de forma objetiva

Harness é tudo que existe ao redor do modelo para transformar inferência em entrega:

prompt de sistema e arquivos de regra (AGENTS.md, skills, conventions)
ferramentas (shell, git, browser, linters, testes, MCPs)
contexto e memória (como carrega, resume e persiste conhecimento)
hooks de segurança e qualidade (bloqueios, checks, gates de aprovação)
orquestração (subagentes, handoff, planner x executor x reviewer)
observabilidade (logs, traces, custo, latência, taxa de erro)

Um modelo excelente com harness fraco tende a falhar de formas repetitivas. Um modelo apenas bom com harness forte costuma entregar melhor em produção.

A mudança de mentalidade: de "culpar o modelo" para "melhorar o sistema"

Quando o agente erra, o caminho mais comum é:

"o modelo é ruim, vamos esperar a próxima versão."

Harness engineering propõe outro caminho:

"qual ajuste no sistema evita esse erro daqui pra frente?"

Exemplos práticos:

agente comentou testes ao invés de corrigir -> regra explícita + hook bloqueando .skip(, xit( e afins
agente tentou comando destrutivo -> bloqueio em pre-tool (rm -rf, git push --force, DROP TABLE)
agente se perdeu em tarefa longa -> separação de papéis (planner, executor, evaluator)
agente marcou tarefa como pronta sem validar -> obrigar typecheck/lint/test no loop de feedback

Esse é o ponto mais forte do conceito: cada erro vira especificação.

Efeito catraca: cada falha vira uma proteção permanente

Pense no harness como uma catraca de maturidade.

Toda vez que houver uma falha real:

registrar o padrão do erro
decidir se a prevenção é por prompt, hook, ferramenta ou processo
automatizar a prevenção
medir se a falha desapareceu

Com isso, você para de depender de "memória do time" e passa a depender de sistema.

Componentes mínimos de um bom harness para engenharia de software

Se você quiser sair do zero com algo funcional, começaria assim:

Regras curtas e testáveis AGENTS.md com poucas regras, objetivas e acionáveis. Não faça guia de estilo gigante: faça checklist de voo.
Ferramentas realmente usadas Menos ferramentas, com descrições claras, é melhor do que um menu enorme e confuso.
Feedback automático no loop Editou código? roda validações. Falhou? devolve erro para o agente se autocorrigir. Passou? silencio.
Execução segura Sandbox/isolamento quando possível. Bloqueio explícito para operações destrutivas.
Memória de projeto Convenções, decisões arquiteturais e armadilhas conhecidas persistidas em arquivo versionado.
Observabilidade Sem log de falhas e sem rastreio de decisão, você não melhora o harness de forma consistente.

Contexto longo quebra agente (se você não cuidar)

Outro ponto central: contexto degrada.

Conforme a janela cresce, o agente tende a:

perder foco
degradar raciocínio
encerrar antes da hora
repetir ação sem progresso

Três técnicas ajudam muito:

compaction: resumir e descarregar histórico antigo
offload de saída grande: logs extensos vão para arquivo; no contexto fica só sinal relevante
progressive disclosure: carregar regras/ferramentas sob demanda, não tudo no início

O que a Cursor adiciona de forma muito prática

O texto da Cursor traz um ângulo importante: harness é produto, não configuração estática.

Eles descrevem um ciclo contínuo:

definir visão de experiência ideal do agente
criar hipóteses de melhoria do harness
testar com evals offline + A/B online
manter o que melhora qualidade real

Alguns pontos que valem copiar no dia a dia:

Keep Rate de código gerado: medir quanto do código proposto pelo agente continua no repositório depois de um tempo
satisfação semântica do usuário: inferir se a pessoa ficou satisfeita pela conversa subsequente (seguir fluxo vs voltar com stack trace)
classificação de erros de tool calls: separar erro inesperado (bug de harness) de erro esperado (ex.: argumento inválido, timeout, provider fora)
alerta por anomalia por ferramenta e por modelo: detectar degradação quando desvia da baseline
otimização incremental: ganhos de qualidade costumam vir de pequenas melhorias acumuladas, não só de "silver bullet"

Em outras palavras: melhorar agente de forma consistente exige engenharia de produto, observabilidade e disciplina de experimento.

Não existe harness universal

Outro aprendizado forte da Cursor: o harness precisa ser customizado por modelo.

Exemplo prático:

se o modelo foi mais treinado para edição via patch, ofereça patch como caminho principal
se o modelo performa melhor com substituição de string, ajuste ferramentas e prompts para isso

Isso reduz erro, custo de raciocínio e retrabalho.

A regra geral é:

abstração agnóstica por fora, personalização por modelo por dentro.

Um playbook simples para aplicar esta semana

Se sua equipe já usa agentes de código, você pode fazer isso em poucos passos:

Liste os 5 erros mais caros das ultimas semanas.
Para cada erro, decida um mecanismo de prevenção (regra, hook, validação, fluxo).
Atualize o harness com mudanças pequenas e reversíveis.
Rode por uma semana e compare retrabalho, regressão e tempo de review.
Mantenha só o que gerou melhoria real.

Não é sobre "engessar" o agente. É sobre aumentar taxa de acerto sem depender de sorte.

Fechando

Modelos vão continuar melhorando, mas isso não elimina a necessidade de harness.

Na verdade, quanto mais capacidade o modelo ganha, maior tende a ser o valor de uma boa orquestração:

para manter segurança
para garantir qualidade
para escalar em tarefas longas
para coordenar múltiplos agentes no mesmo objetivo

Se você quer evoluir de uso casual de IA para engenharia assistida por agentes em nível de produção, comece pelo harness.

Ele é o multiplicador que transforma potencial em resultado.