Harness Engineering: os 6 componentes que auditam seu CLAUDE.md em 10 min

Trocar o modelo não conserta seu agente. Eu tentei três vezes: Sonnet 4.6 → GPT-5.3 → Opus 4.7, no mesmo repositório, no mesmo benchmark de 15 tarefas. O ganho maior que vi foi 4 pontos percentuais. Dentro do ruído. No mesmo repositório, cortar meu AGENTS.md de 940 para 118 linhas rendeu +22 pontos. Trocar o modelo custa $200/mês; trocar o ambiente custa uma tarde de leitura fria.

Esse é o pulo do gato de 2026: Prompt Engineering morreu, Context Engineering está morrendo, Harness Engineering é o que resta. Não como slogan — como diagnóstico. 40% dos projetos de agente falham em produção, e quase todos falham pelo mesmo motivo: ninguém desenhou o ambiente em que o agente opera. Só o prompt. Ou só o contexto.

Este artigo é uma checklist auditável. Se você tem um CLAUDE.md (ou AGENTS.md, ou .cursorrules, tanto faz) rodando em produção, dá pra passar por esses 6 componentes em uns 10 minutos. Cada um é uma camada do harness, e cada camada quebra o agente de um jeito diferente quando falta.

Por que 6 componentes, e não 3

A taxonomia vem do artigo “Decode the Buzzword” da Next Signal Prediction, que quebra o harness em seis módulos anatômicos. Não é o único mapa possível — a Anthropic, a OpenAI e a LangChain têm variações. Mas os seis módulos são a divisão mais operacional que achei: cada um mapeia pra um bloco concreto do seu CLAUDE.md ou pra uma configuração real de sandbox.

A ordem importa. Se você audita na sequência de baixo pra cima, cada componente depende do anterior. Fronteira de segurança sem definições de ferramentas não faz sentido. Tracing sem execução também não. Segue o fluxo.

① Gestão de informação — 90 segundos

A camada que controla o que o agente fica sabendo.

Abra seu CLAUDE.md agora. Confira:

• Índice do projeto: as primeiras 20 linhas explicam o que é o repositório, ou começam com “olá! sou seu assistente”? Se for o segundo, apague. O agente já sabe que é assistente.
• Skills concretas: existem arquivos com passos verificáveis (rodar npm test, abrir src/api/router.ts)? Ou só descrições genéricas de “boas práticas”?
• Memória entre sessões: você tem algum mecanismo que sobrevive além do prompt atual — MEMORY.md, arquivo de decisões, log de incidentes? Ou toda sessão começa do zero?

Regra empírica: se seu CLAUDE.md passa de 300 linhas e você não consegue defender cada linha, o agente também não vai defender. Corte pra 118. Eu cortei. Ganhei 22 pp.

② Execução — 60 segundos

A camada que conduz as ações do agente.

• Decomposição: seu agente recebe “implementa a feature X” e sai codando 400 linhas de uma vez? Ou existe uma etapa explícita de plano-antes-de-editar? Anthropic chama isso de plan mode; funciona.
• Orquestração: quem decide a ordem — o modelo (a cada tool call) ou uma máquina de estados externa? Pra tarefas > 5 min, LangGraph ou equivalente compensa. Pra tarefas curtas, deixa o modelo dirigir.
• Retry e timeout: existe um teto de tentativas? Já vi agente rodando 47 iterações no mesmo bug antes de alguém puxar o cabo. Coloque max_iterations: 8 e siga a vida.

③ Verificação de qualidade — 2 minutos

A camada que checa a saída antes do humano ver.

Essa é a que mais move a agulha em codificação. Sem ela, o agente entrega PR que não compila e você vira revisor de coisa quebrada.

• Lint / format automático: ruff, biome, prettier — algum roda antes do agente terminar? Não como sugestão, como gate.
• Type-check strict: TypeScript com strict: true, mypy com --strict, Go com staticcheck. Se o agente pode passar por essa etapa sem rodar, ele vai passar.
• Testes automatizados: o agente roda npm test no fim, ou você que descobre no CI? A diferença entre “IA vira teste em 3 min” e “IA quebra prod em 3 dias” é essa checagem.
• LLM-as-judge ou autoFix: pra correções mecânicas, autoFix. Pra revisão semântica, outro modelo julgando. Um dos dois — não os dois no mesmo passo.

Passei um mês inteiro achando que meu agente era ruim. Era, mas 70% da ruindade sumiu quando eu movi biome check --fix de “após revisão humana” pra “antes do PR abrir”.

④ Tracing e observabilidade — 90 segundos

A camada que torna visível o comportamento do agente.

Sem tracing, otimização vira chute. Você não sabe se o agente gastou 47k tokens porque a task era complexa ou porque ficou em loop.

• Log de execução: cada tool call é gravada em algum lugar? Não precisa ser LangSmith — arquivo .jsonl local já resolve pro primeiro mês.
• Uso de tokens por task: você sabe quanto custou a última PR aberta? Se não sabe, você não tem controle de custo, tem esperança de custo.
• Tempo por passo: qual etapa está lenta? Type-check? RAG? Se você não mede, otimiza a etapa errada.

Ferramentas: LangSmith (paga, completa), Arize (paga, mais focada em produção), ou um decorator custom que grava .jsonl (grátis, resolve 80%).

⑤ Fronteira de segurança — 2 minutos

A camada que confina o agente numa faixa segura.

Essa é a que separa “agente rodando localmente” de “agente que pode ir pra prod sem tirar o Slack do sono do time”.

• allowedTools: seu agente tem lista explícita de ferramentas permitidas, ou tem acesso a tudo por default? Claude Code aceita --disallowedTools Bash(*rm*). Use.
• Sandbox de filesystem: git worktree, container efêmero, ou pelo menos chroot — existe algo? Ou o agente pode escrever em /etc/hosts porque o processo tem permissão?
• Sandbox de rede: chamadas de API externa passam por um proxy que você controla, ou o agente pode chamar qualquer endpoint? Já vi agente vazando token da AWS porque baixou um script sem verificar host.
• Approval gates: operações destrutivas (git push --force, rm -rf, alterar produção) exigem confirmação humana, ou o agente decide sozinho?

Regra que uso: por default, negar. Habilitar por ferramenta. É chato nos primeiros dois dias e salva sua semana no terceiro.

⑥ Definições de ferramentas — 90 segundos

A camada que dá capacidades ao agente — e determina se ele vai usar direito.

• Schemas de função com descrição real: description: "Faz stuff" não é descrição. description: "Roda ruff format no arquivo especificado. Retorna diff. Use antes de committar." é.
• MCP servers relevantes: você tem MCP conectado ao que o agente realmente precisa (Postgres, Sentry, sua doc interna)? Ou o agente ainda usa curl pra tudo?
• Operações de arquivo: as permissões batem com o que o agente deveria fazer? Agente que só edita src/ não precisa de acesso a .env.

Quando a descrição da ferramenta é preguiçosa, a escolha da ferramenta também é. “Me passa aquela ferramenta” — era martelo ou chave de fenda? Se o schema não diz, o agente vai chutar.

Somando: 10 minutos, 6 componentes, 1 diagnóstico

• ① Gestão de informação — 90s
• ② Execução — 60s
• ③ Verificação de qualidade — 2 min
• ④ Tracing — 90s
• ⑤ Fronteira de segurança — 2 min
• ⑥ Definições de ferramentas — 90s

Total: 8 min 30s. Deixei uma margem porque na primeira vez você para em algum item e pensa “espera, eu tenho isso?”. Marque o item como faltando e siga. A auditoria não é pra consertar tudo hoje. É pra saber o que está faltando.

Meu ranking pessoal, depois de auditar uns 15 harnesses (meus e de clientes): o componente ③ (verificação de qualidade) é o que mais move a agulha em codificação. O ⑤ (fronteira de segurança) é o que mais evita incêndio. Os outros são combustível — importam, mas o motor não pega sem 3 e 5.

O ponto de virada

Se um único componente estiver com nota zero, o modelo está fazendo o trabalho do harness. E o modelo é péssimo em fazer o trabalho do harness. Ele não lembra da sessão passada (isso é ①), não roda seus testes (isso é ③), não confina suas ações destrutivas (isso é ⑤). Trocar Sonnet por Opus não conserta nenhum desses três.

O que conserta é montar a camada faltante. Uma sessão de 2 horas de audit + fix costuma valer mais que um upgrade de plano de $20 pra $200. Eu fiz a conta com dados reais no capítulo 2 do meu livro, e o retorno em completion rate por real gasto foi 18x maior no lado do harness.

Roda a checklist. Vê o que falta. Escolhe um componente por semana pra consertar. Em 6 semanas você tem um agente que sobrevive em produção. Em 6 meses trocando de modelo, você tem 6 modelos e o mesmo agente quebrado.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews