O que é Harness Engineering e por que seu Claude Code trava em tarefas longas

Você manda o Claude Code refatorar três módulos. Trinta minutos depois, ele te entrega o primeiro com testes, abre o segundo, perde o fio, repete metade do trabalho do primeiro, declara que "está tudo passando" e cita um arquivo que nunca existiu. Você xinga o modelo.

O modelo não tem culpa.

O que falhou ali tem nome: harness engineering. É a engenharia ao redor do modelo — loop, tools, contexto, memória, verificação. Em 2026 o termo virou consenso entre Anthropic, Martin Fowler e Addy Osmani, e a tese é a mesma: agente que trava em tarefa longa quase nunca trava por limite do modelo. Trava porque o harness é raso.

Neste post você vai sair com a definição do termo, a anatomia mínima de um harness funcional e um diagnóstico honesto do ponto onde a maioria dos devs para de evoluir o setup — e segue culpando a IA.

TL;DR

• O que é: a disciplina de engenharia que cerca um modelo de IA — loop, tools, contexto, memória, verificação.
• De onde vem o termo: consolidado em 2026 por Anthropic, Fowler e Osmani. Não é jargão de vendor.
• Quem precisa saber: qualquer dev que use Claude Code, Cursor, Aider, agente próprio em produção ou pipeline de CI com IA no meio.
• Custo: zero. É arquitetura, não produto.
• Leituras-âncora: Anthropic — Effective harnesses, Fowler — Harness engineering, Osmani — Agent harness engineering.

O termo "harness" não nasceu de marketing

Fowler resume melhor que ninguém: harness engineering é "everything in an AI agent except the model itself". Tudo o que o agente precisa para sair do laboratório e funcionar no mundo real — e que não é o modelo em si.

A definição do awesome-harness-engineering abre isso em camadas: "scaffolding — context delivery, tool interfaces, planning artifacts, verification loops, memory systems, and sandboxes — that surrounds an AI agent and determines whether it succeeds or fails on real tasks".

Osmani fecha a tese com a frase que devia estar tatuada em quem mantém agente em produção: "a decent model with a great harness beats a great model with a bad harness". E vai além — observa que os top coding agents do mercado hoje "look more like each other than their underlying models do". Os modelos são diferentes. Os harnesses convergiram.

Isso muda como você lê uma falha do agente. Quando o Claude Code esquece o que estava fazendo, o problema raramente é "Claude burro hoje". O problema é que o seu harness não tem context bridging. Quando ele alucina um arquivo, o problema é que suas tools não verificam existência antes de retornar. Quando ele declara done sem testar, o problema é que não tem sensor fechando o loop.

O modelo é a peça mais cara do sistema. Mas é a peça que você não controla. O harness é onde a engenharia acontece.

Por que seu Claude Code trava em tarefa longa

Antes de falar de anatomia, vale catalogar os sintomas. Anthropic descreve quatro padrões que aparecem em qualquer agente sem harness sério:

• One-shotting. O agente tenta resolver o projeto inteiro de uma vez, em vez de avançar feature por feature. Resultado: metade fica "feita", nenhuma fica testada.
• Premature completion. Declara o trabalho concluído cedo demais. "Já criei os endpoints" — sem rodar um teste, sem checar contrato, sem validar que o handler está plugado.
• State degradation. Deixa rastros de mudança espalhados, sem documentação nem teste. Você abre o repositório no dia seguinte e não sabe o que está em pé.
• Lost context. Cada nova sessão começa do zero. Sem memória do que foi decidido, sem memória do que falhou.

Os sintomas que você sente como dev são o reflexo disso: agente esquece, agente repete, agente alucina arquivo, agente fecha tarefa que não fechou. Não é falha de inteligência. É falha de engenharia ao redor da inteligência.

Anatomia mínima de um harness

Quatro pilares. Tirando qualquer um, o agente trava em tarefa longa.

Loop

Todo agente precisa de um ciclo explícito. O padrão clássico é ReAct — reason → act → observe → repeat — e a versão da Anthropic para tarefas longas tem três fases: gather context → take action → verify.

Em pseudocódigo o esqueleto é trivial:

while not task.done():
    context = gather_context(task, memory)
    action = model.decide(context, tools)
    result = execute(action)
    memory.append(result)
    if verify(result):
        task.advance()
    else:
        task.retry_with(result.error)

O detalhe que separa um harness amador de um sério é o que entra em gather_context e o que sai de verify. O loop em si é a parte fácil.

Tools

Tools são o sistema nervoso do agente. Se elas mentem, o agente mente junto.

Três regras práticas:

1. Schema estrito, sempre. JSON Schema, Pydantic, Zod — qualquer coisa que valide entrada e saída antes de o modelo ver. Tool com schema frouxo gera alucinação previsível.
2. Foco vence quantidade. Dez tools claras vencem cinquenta tools sobrepostas. Se duas tools fazem quase a mesma coisa, o agente vai escolher errado em metade dos casos.
3. Sucesso silencioso, falha verbosa. Tool que deu certo retorna o mínimo. Tool que falhou retorna a mensagem de erro com instrução de remediação embutida — porque o leitor da mensagem é o modelo, não você.

def read_file(path: str) -> ToolResult:
    if not Path(path).exists():
        return ToolResult.error(
            f"File not found: {path}. "
            f"Use list_dir({Path(path).parent}) to inspect available files "
            f"before retrying read_file."
        )
    return ToolResult.ok(Path(path).read_text())

A mensagem de erro é metade da tool. Se ela só diz FileNotFoundError, o agente vai tentar de novo. Se ela diz o que fazer a seguir, o agente corrige sozinho.

Contexto

Contexto é o que o modelo enxerga em cada turno. E contexto é finito.

O padrão que se firmou no mercado é o AGENTS.md (ou CLAUDE.md) na raiz do projeto: convenções, comandos, decisões arquiteturais que o agente lê em todo turno. Osmani cita o caso da HumanLayer, que mantém o arquivo com menos de 60 linhas — e justifica com a frase que define a disciplina toda: "Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong".

Cada linha existe porque algo quebrou. Não é manual de boas-vindas. É memória de incidente comprimida em regra.

Para tarefas longas, contexto sozinho não basta — ele estoura a janela. As três técnicas que funcionam:

• Compaction. O harness comprime turnos antigos antes que estourem o limite.
• Tool-offloading. Em vez de carregar arquivos inteiros no contexto, o agente lê via tool e mantém só o trecho relevante.
• Progressive disclosure. Skills e docs entram no contexto só quando são chamadas, não no boot.

Memória

Loop, tools e contexto resolvem a sessão. Memória resolve o que vem depois dela.

Anthropic é explícita sobre o problema: "agents must work in discrete sessions, and each new session begins with no memory of what came before". A solução proposta é um par simples — claude-progress.txt mais histórico do Git. O progress file vira o "estado da obra"; o Git vira a auditoria do que mudou.

Em harnesses mais maduros, a memória vira multi-tier:

• Core memory — fatos sobre o usuário, o projeto, decisões arquiteturais.
• Archival memory — base vetorial com decisões antigas, reutilizada por busca.
• Recall memory — janela curta de turnos recentes que sobreviveu à compaction.

Não precisa começar com os três. Precisa começar com algum. Agente sem memória persistente não evolui — repete os mesmos erros toda segunda-feira.

Onde a maioria dos devs para de evoluir o setup

Aqui está a parte chata.

A maior parte dos devs que usa Claude Code monta um harness mínimo na primeira semana — instala, cria um CLAUDE.md curto, configura duas tools — e para. Quando o agente erra, abre issue. Quando o agente trava, espera o próximo modelo.

Esse é o ponto onde o setup deixa de evoluir. E é o ponto onde Fowler e Osmani convergem na mesma crítica.

Fowler observa que harness só funciona quando combina feedforward (guides — regras que evitam o erro antes dele acontecer) com feedback (sensors — verificação que detecta o erro depois). E entrega a sentença: "you get either an agent that keeps repeating the same mistakes (feedback-only) or an agent that encodes rules but never finds out whether they worked (feed-forward-only)". Devs costumam parar no feedforward — escrevem regras, mas nunca medem se as regras funcionaram.

Osmani descreve o mesmo travamento como mindset: o dev culpa o modelo, espera versão nova, segue rodando o mesmo setup. A alternativa que ele chama de ratchet principle é dura, mas é a única que escala — cada erro do agente vira uma constraint permanente no harness. Cada falha vira uma linha no AGENTS.md, ou um hook que bloqueia, ou uma tool nova com mensagem de erro melhor.

Os três pontos onde dá pra começar a sair do platô hoje:

1. Hooks que fecham o loop de verificação. Após cada edição, rodar typecheck, lint e teste afetado. Se falhar, o erro volta pro agente como input do próximo turno. Sem hook, sem feedback control.
2. CLAUDE.md rastreável. Cinco a dez regras, cada uma vinda de um erro real que você viu. Se você não consegue contar a história por trás de uma regra, ela sai. Sub-60 linhas é a régua da HumanLayer — e funciona.
3. Progress file para tarefas long-horizon. Para qualquer tarefa que vai durar mais de uma sessão, um arquivo simples com o que foi feito / o que falta / decisões tomadas. O agente lê no início de cada sessão. Custa cinco minutos. Resolve metade dos sintomas de "ele esqueceu o que estava fazendo".

Esse é o tipo de pipeline que dá pra construir do zero em dois dias trabalhando em produto real, e é exatamente o foco do workshop Harness Engineering com Claude Code que vai rolar dias 16 e 17 de maio — em vez de chatbot de demonstração, a galera sai com um agente em Claude Code + Laravel + NativePHP que recebe link de produto, pesquisa alternativas em e-commerces, compara preço e devolve recomendação estruturada, com loop, tools, memória e verificação plugados de verdade.

Conclusão

Harness engineering é o nome novo para uma ideia velha: a engenharia que cerca uma peça não-determinística é o que decide se ela é confiável. O modelo é a fonte de inteligência. O harness é a fonte de previsibilidade.

Quando o seu Claude Code trava em tarefa longa, a pergunta certa não é "qual modelo eu uso agora". É "qual sintoma eu estou vendo, e qual peça do harness está faltando". Loop sem verificação dá premature completion. Tool sem schema dá alucinação. Contexto sem AGENTS.md dá agente que esquece a convenção do projeto. Sessão sem memória dá agente que repete trabalho.

O próximo salto do dev que usa IA não vai vir do modelo. Vai vir do harness em volta dele.