# Harness e Loop: A Arquitetura de 2 Camadas dos Agentes em 2026 > Entenda a arquitetura harness + loop que define como agentes de codificação funcionam em 2026 — e por que sua IDE é metade da equação. Source: https://agentify.ia.br/blog/harness-e-loop-arquitetura-agentes/ > **TL;DR** — Todo agente de codificação que você usa é, na verdade, duas coisas: um **harness** (o ambiente que controla, limita e observa) e um **loop** (o ciclo interno de raciocínio, ação e memória). Sua IDE é o harness. O modelo + skills formam o loop. Entender essa separação muda como você configura, avalia e tira proveito de qualquer agente. --- ## Um carro não é só motor Pega um Civic na concessionária. O motor é brutal — VTEC, 200cv, resposta limpa. Mas o carro não anda só com motor. Tem o chassi que define os limites estruturais. A suspensão que absorve buracos. O painel que te dá informação. O câmbio que decide quando trocar marcha. Os freios que impedem você de morrer. Motor sem chassi é uma bancada de teste. Chassi sem motor é uma escultura de aço. Agentes de codificação funcionam exatamente assim. O modelo de linguagem — Claude, GPT, Gemini — é o motor. Potente, rápido, capaz de gerar código que resolve problemas reais. Mas ele não opera sozinho. Precisa de um chassi: algo que defina quais ferramentas estão disponíveis, quais arquivos ele pode tocar, quando parar, como se recuperar de erros, e quem está olhando o que ele faz. Esse chassi tem nome: **harness**. O motor em ciclo de execução tem nome: **loop**. E em 2026, essa separação virou a lente principal para entender — e melhorar — qualquer agente de codificação. --- ## De onde vem essa conversa? O termo “harness engineering” explodiu entre março e junho de 2026. Não veio de um paper acadêmico. Veio da prática. Em março, a Anthropic publicou documentação técnica sobre harness design para sessões longas de codificação autônoma. Em abril, a OpenAI publicou um post chamado “Harness engineering: leveraging Codex in an agent-first world”. Nessa mesma janela, a comunidade no Reddit e Hacker News começou a debater: “o que você espera de um agent harness?” virou thread com dezenas de comentários. A tese central é simples e poderosa: **os modelos de fronteira convergem em capacidade — o que diferencia resultados é o harness ao redor deles**. Ou, nas palavras de um post que viralizou no Medium: “70% da performance do seu agente vive fora do modelo.” Não é exagero. Mesma engine, harness diferente, resultado completamente diferente. A Anthropic demonstrou isso: Claude Opus rodando solo por 20 minutos produziu um app com bugs críticos. O mesmo modelo dentro de um harness com planner + evaluator + QA rodou por 6 horas e entregou um app funcional — com bugs menores, sim, mas funcional. --- ## O que é o Harness? O harness é **tudo que não é o modelo pensando**. É a infraestrutura determinística que envolve, controla e sustenta o agente durante a execução. Pense assim: quando você abre o Claude Code no terminal e digita um comando, quem decide que o agente pode ler arquivos do seu projeto? Quem define que ele não pode fazer `rm -rf /`? Quem escolhe quais [ferramentas (tools)](/blog/ferramentas-tools-e-mcp-servers) estão disponíveis? Quem compacta o contexto quando fica grande demais? Quem loga cada ação para você auditar depois? O harness. Componentes típicos de um harness: - **Ferramentas disponíveis e roteamento** — quais tools o agente pode chamar, com quais credenciais - **Guardrails e permissões** — o que o agente *não pode* fazer (deletar branches, push em main, acessar secrets) - **Gestão de contexto e memória** — como o histórico é compactado, quando rolar reset, o que persiste entre sessões - **Observabilidade** — logs, traces, histórico de tool calls, custo por execução - **Tratamento de erros** — retries, fallbacks, limites de iteração - **Pipeline de input/output** — como a tarefa chega ao agente e como o resultado é entregue ### Harness na prática: 3 exemplos que você já usa **[Claude Code](/blog/claude-code)** — O terminal é o harness. Ele decide quais comandos o agente pode executar, gerencia o contexto (compactação automática), aplica permissões (arquivo `.claude/settings.json`), e disponibiliza ferramentas via [MCP servers](/blog/ferramentas-tools-e-mcp-servers). Quando o código-fonte do Claude Code vazou em março de 2026, a comunidade pôde ver pela primeira vez: o harness era mais código que o próprio loop. **[Cursor](/blog/cursor)** — A IDE é o harness. Ela fornece o codebase indexado, controla quais arquivos entram no contexto, disponibiliza actions (apply, accept, reject), e adiciona ferramentas como terminal, browser, e file search. O modelo de linguagem é intercambiável — você troca entre Claude, GPT, Gemini — mas o harness permanece. **[Kiro](/blog/kiro-ide-cli)** — As specs são o harness. O diferencial do Kiro não é o modelo (usa Claude por baixo). É o fato de que specs, design docs e steering files definem *o que o agente deve construir* antes dele começar a codar. O harness aqui é arquitetural: ele constrange o agente via especificação, não só via permissões. Percebe o padrão? Cada um desses produtos é, na essência, um harness diferente embalando modelos similares. A competição em 2026 não é “quem tem o melhor modelo”. É “quem tem o melhor harness.” --- ## O que é o Loop? O loop é o ciclo interno que o agente executa repetidamente até concluir a tarefa. Raciocinar → agir → observar → raciocinar de novo. Continuar até uma condição de parada ser atingida. Se o harness é o chassi do carro, o loop é o motor em rotação: pistões subindo e descendo, combustão, força transferida às rodas. Cada ciclo produz trabalho. A cadência, eficiência e critério de parada definem a qualidade do resultado. Um loop típico de agente de codificação: - **Montar contexto** — juntar prompt do usuário, arquivos relevantes, histórico, regras de projeto - **Invocar o modelo** — o LLM raciocina sobre o próximo passo - **Executar ação** — chamar uma tool (editar arquivo, rodar comando, buscar na web) - **Observar resultado** — inspecionar o output da tool - **Decidir** — concluiu? Precisa de outra iteração? Encontrou erro? - **Repetir** até a condição de parada É o pattern ReAct (Reasoning + Acting) que a maioria dos agentes de codificação implementa. Mas o loop não é só o ciclo mecânico. Ele inclui: - **Raciocínio** — como o modelo decide o próximo passo (chain-of-thought, planning) - **Uso de ferramentas** — seleção e execução de tools - **Memória de curto prazo** — o que aconteceu nas iterações anteriores dessa sessão - **Critério de parada** — quando o agente decide que terminou - **Auto-correção** — capacidade de avaliar o próprio output e revisar ### O que faz um loop ser bom? O problema mais difícil de loop engineering não é fazer o agente começar. É fazer ele **parar no momento certo**. Um loop mal calibrado faz uma de duas coisas: para cedo demais (declara sucesso antes de resolver o problema) ou roda indefinidamente (queimando tokens sem convergir). Ambos são falhas de critério de parada. As [skills](/blog/o-que-sao-skills-e-como-especializar-agentes) que você configura no agente moldam diretamente o loop. Uma skill bem escrita não só diz *o que fazer* — ela define critérios explícitos de conclusão. “A task está pronta quando: testes passam, lint sem erros, build compila.” Isso é engenharia de loop disfarçada de documentação. --- ## Como Harness e Loop se conectam? Eles não são independentes — são complementares. O harness define o espaço de possibilidades. O loop opera dentro desse espaço. Pense numa pista de corrida (harness) e no piloto (loop). A pista tem curvas, limites, brita, muro. O piloto toma decisões a cada momento — acelerar, frear, trocar marcha. A qualidade da corrida depende dos dois: uma pista mal projetada limita até o melhor piloto, e o melhor circuito não salva um piloto que não sabe frear. Na prática: Harness fornece Loop consome Lista de ferramentas disponíveis Decide qual tool chamar a cada iteração Regras de permissão Opera dentro dos limites definidos Contexto do projeto (arquivos, specs) Usa como base para raciocinar Limite máximo de iterações Decide quando parar (ou é forçado a parar) Logs e traces Produz os eventos que são logados A comunicação entre harness e loop é bidirecional. O harness alimenta o loop com contexto e restrições. O loop sinaliza ao harness quando precisa de mais ferramentas, quando encontrou um erro, ou quando concluiu. É por isso que trocar de [IDE](/blog/ide-vs-cli-dois-modelos-de-agente) muda tão radicalmente o resultado mesmo usando o mesmo modelo. Você não trocou o motor — trocou o chassi, a suspensão, os freios. O carro inteiro se comporta diferente. --- ## Por que essa separação importa para você? Três razões práticas. ### 1. Diagnóstico mais rápido Quando um agente falha, você precisa saber *onde* está o problema. Com o modelo mental harness/loop, o diagnóstico fica binário: - O agente não teve acesso à ferramenta que precisava? → **Problema de harness.** Configure o MCP server, ajuste permissões. - O agente teve tudo que precisava mas tomou decisões ruins? → **Problema de loop.** Melhore o prompt, ajuste skills, troque de modelo. - O agente rodou infinitamente sem convergir? → **Problema de loop** (critério de parada). Defina limites, melhore as instruções de conclusão. - O agente parou porque deu timeout ou erro de API? → **Problema de harness** (error handling). Configure retries, fallbacks. Sem essa separação, “o agente não funciona” é uma caixa preta. Com ela, você sabe exatamente onde mexer. ### 2. Otimização direcionada Já ficou frustrado porque trocou de modelo e o resultado não melhorou? Provavelmente o gargalo era o harness, não o loop. A pesquisa de 2026 deixou isso claro: passado um limiar de capacidade do modelo, melhorar o harness dá mais retorno que trocar o motor. É o equivalente a colocar um motor V8 num Fusca — a potência sobra, mas o chassi não aguenta. Se você quer resultados melhores do seu agente de codificação, antes de pagar pelo modelo mais caro, pergunte: - As regras de projeto estão claras? (harness) - O contexto certo está chegando ao modelo? (harness) - As ferramentas certas estão disponíveis? (harness) - As skills definem critérios de conclusão? (loop) ### 3. Comparação honesta entre ferramentas Quando alguém diz “Cursor é melhor que Claude Code”, o que estão comparando? Na maioria das vezes, estão comparando harnesses — não modelos. Cursor e Claude Code podem rodar o mesmo Claude Sonnet por baixo, mas a experiência é completamente diferente porque o harness é diferente. Entender isso te liberta de guerras de ferramenta. A pergunta certa não é “qual é melhor?” É: “qual harness se encaixa no meu workflow?” Se você prefere [terminal e automação](/blog/ide-vs-cli-dois-modelos-de-agente) → Claude Code. Se você prefere IDE visual com apply/reject → Cursor. Se você prefere spec-first com autonomia longa → Kiro. Todas são escolhas de harness. O motor é quase o mesmo. --- ## O nível de maturidade: in the loop, on the loop, out of the loop Um framework que apareceu na CheesecakeLabs em 2026 — atribuído a Kief Morris — classifica a maturidade da relação dev/agente em três estágios: **In the loop** — Você revisa cada diff manualmente. O agente sugere, você aceita ou rejeita. É o [modo assistente](/blog/modo-agente-vs-modo-assistente) tradicional. **On the loop** — Você não revisa cada linha. Em vez disso, constrói o harness: define specs, configura testes, cria guardrails. O agente roda com autonomia, mas dentro dos limites que você projetou. Você monitora de longe. **Out of the loop** — O agente opera sem supervisão humana. A confiança vem inteiramente do harness: testes, linters, CI/CD, observabilidade. Se o pipeline verde, o código vai. A maioria dos devs em 2026 está no estágio 1, migrando para o 2. O salto de “in the loop” para “on the loop” é, literalmente, passar de *escrever código* para *projetar harnesses*. É a mudança de papel que define a engenharia com agentes. --- ## Na prática: anatomia de uma sessão Vamos desmontar uma sessão real para ver harness e loop em ação. Você está no Claude Code. Digita: “refatore o módulo de autenticação para usar JWT em vez de sessions.” **O harness entra em ação:** - Coleta os arquivos relevantes do projeto (file search) - Carrega as regras de projeto (AGENTS.md, CLAUDE.md) - Verifica permissões — pode editar src/auth/? Pode rodar testes? - Disponibiliza ferramentas: file edit, terminal, grep - Monta o contexto inicial e envia ao modelo **O loop começa:** - Modelo raciocina: “preciso entender a implementação atual” - Chama tool: grep por “session” nos arquivos de auth - Observa resultado: 4 arquivos relevantes encontrados - Raciocina: “vou ler cada um para entender a estrutura” - Chama tool: read files - Raciocina: “agora vou planejar as mudanças” - Chama tool: edit file (modifica auth.ts) - Chama tool: run tests - Observa: 2 testes falharam - Raciocina: “preciso atualizar os mocks” - Chama tool: edit file (modifica auth.test.ts) - Chama tool: run tests - Observa: todos passam - Decide: “tarefa concluída” **O harness finaliza:** - Loga toda a sessão (custo, tempo, tool calls) - Apresenta diff para aprovação - Aguarda input humano Repare: o harness não tomou nenhuma decisão criativa. O loop não gerenciou nenhuma infraestrutura. Cada um fez o seu trabalho. --- ## O que muda daqui pra frente Alguns palpites — e aqui falo com opinião mesmo. O harness vai ser o diferencial competitivo das ferramentas de agente pelos próximos 2 anos, pelo menos. Modelos vão continuar melhorando, mas a curva está achatando. O que separa uma experiência mágica de uma frustrante é cada vez menos o modelo e cada vez mais o harness. Para devs, isso significa uma coisa: **aprenda a projetar harnesses**. Isso inclui escrever specs boas, configurar regras de projeto, definir guardrails claros, e escolher ferramentas que deem visibilidade sobre o que o agente está fazendo. As skills que você escreve para seus agentes? São parte do loop — mas também configuram o harness quando definem permissões e limites. Ler sobre [como skills funcionam](/blog/o-que-sao-skills-e-como-especializar-agentes) é diretamente relevante aqui. E para a comunidade: parar de comparar ferramentas pelo modelo e começar a comparar pelo harness seria um avanço enorme na qualidade das discussões. “Cursor é bom pra mim porque o harness dele combina com como eu trabalho” é uma declaração infinitamente mais útil que “Cursor é o melhor.” --- ## Próximos passos Se esse conceito fez sentido, aqui estão os caminhos naturais: - **Entenda os dois modelos de harness** — IDE gráfica vs CLI terminal: [IDE vs CLI: dois modelos de agente](/blog/ide-vs-cli-dois-modelos-de-agente) - **Explore a diferença prática** entre ser servido pelo agente vs trabalhar com ele: [Modo agente vs modo assistente](/blog/modo-agente-vs-modo-assistente) - **Mergulhe nas ferramentas** que seu harness disponibiliza: [Ferramentas (tools) e MCP Servers](/blog/ferramentas-tools-e-mcp-servers) - **Aprenda a configurar o loop** via skills: [O que são skills e como especializar agentes](/blog/o-que-sao-skills-e-como-especializar-agentes) O modelo mental harness/loop não é uma teoria acadêmica. É a lente que eu uso todo dia para decidir onde investir tempo quando um agente não está performando. E 9 em cada 10 vezes, o problema é o harness. Melhore o chassi. O motor já é bom o suficiente. -->