Todo mundo fala sobre loops. Quase ninguém fala sobre o que o loop executa. 9 em cada 10 desenvolvedores rodam o Claude Code no ambiente padrão - sem regras, sem subagentes, sem hooks, sem memória.
Depois se perguntam por que o loop produz porcaria. A verdade é simples: um loop é tão bom quanto o ambiente de execução (harness) abaixo dele. Este é o roteiro de 14 passos para o ambiente de execução - de um único agente a um sistema que se auto aprimora.
Siga meu Substack para receber dicas frescas de IA:
A engenharia de loops - construir um sistema que agenda prompts para seu agente - recebeu toda a atenção este mês. Mas Addy Osmani, que escreveu o artigo detalhado sobre loops, fez questão de apontar o que está por baixo disso:
“A engenharia de loops fica um andar acima do ambiente de execução (harness). O harness é o ambiente no qual um único agente opera. O loop é o harness, mas executado em um cronômetro, que gera ajudantes e se alimenta.”
A engenharia de harness é projetar esse ambiente: o modelo, as ferramentas, as permissões, o contexto, a memória.
É a camada sem glamour - e é ela que decide se tudo acima dela funciona. Um ótimo loop em um harness ruim é uma maneira rápida de produzir lixo em escala.
14 passos. 3 níveis. A base sobre a qual tudo o mais se sustenta.
Parte 1 · O que é o Harness
01. Um harness é o ambiente onde um único agente opera.
Deixando o jargão de lado, um harness é composto por quatro coisas: o modelo que pensa, as ferramentas que ele pode usar, as permissões dessas ferramentas e o contexto que ele lê no início de cada execução.
Essa é a superfície completa. Todo o resto - subagentes, hooks, memória - é uma forma de moldar um desses quatro elementos.
A razão pela qual o harness importa mais do que as pessoas pensam: o agente é um loop while True que escolhe uma ferramenta, executa-a, observa o resultado e decide o próximo movimento.
O harness define quais ferramentas existem, o que o agente pode fazer e o que ele sabe quando começa. Mesmo modelo, harness diferente, agente completamente diferente.
02. Todo o harness reside em uma única pasta. .claude/
Tudo que molda seu agente fica em um único diretório na raiz do seu projeto. Aprenda essa estrutura e você poderá ler o harness de qualquer pessoa rapidamente:
1.claude/2├─ CLAUDE.md # fatos permanentes — lidos a cada sessão3├─ settings.json # permissões, modelo, hooks4├─ .mcp.json # conexões com ferramentas externas5├─ rules/ # comportamentos por escopo de diretório6│ ├─ tests.md7│ └─ python-types.md8├─ agents/ # definições de subagentes (~30 linhas cada)9│ ├─ reviewer.md10│ └─ eval-runner.md11├─ skills/ # fluxos de trabalho reutilizáveis12│ └─ pr-checklist/13│ └─ SKILL.md14└─ agent-memory/ # o que sobrevive entre execuções15 └─ STATE.md
Uma regra que separa um harness limpo de uma bagunça: mantenha-o pequeno o suficiente para que você possa explicar por que cada arquivo existe. Se você não consegue dizer para que serve uma regra, hook ou subagente, delete-o.
03. Harness vs loop vs sistema. Três níveis, não os misture.
A maioria dos problemas do tipo "meu setup de agente é uma bagunça" vem de confundir os três níveis. Mantenha-os claros:
- O harness é o ambiente de execução onde um agente vive. Configuração estática: modelo, ferramentas, permissões, contexto. Esta edição.
- O loop dá prompts ao agente em um cronômetro, gera ajudantes, se alimenta. Ele executa sobre o harness.
- O sistema auto aprimorável é um loop mais memória que se acumula - cada execução deixa a próxima execução mais afiada.
A versão prática: coloque fatos permanentes no contexto, aplicação de regras em hooks, procedimentos em skills e isolamento em subagentes.
Misturar essas coisas - colocar aplicação de regras no CLAUDE.md, procedimentos que incham o contexto - é a causa raiz de agentes inconsistentes e caros.
04. O harness padrão. O que você obtém pronto para uso.
Instale o Claude Code, abra uma pasta, e você já tem um harness - apenas um vazio. O padrão te dá um modelo capaz, as ferramentas integradas (ler, escrever, bash, pesquisar) e prompts de aprovação para tudo que é arriscado. Sem contexto do projeto, sem subagentes personalizados, sem memória.
Para uma tarefa única, o padrão é suficiente. Para qualquer coisa que você faça mais de uma vez, o padrão faz o agente redescobrir seu projeto do zero a cada sessão, pedir permissão para operações seguras e esquecer tudo quando você fecha o terminal.
Os próximos dez passos são sobre fechar essa lacuna.
05. CLAUDE.md: fatos permanentes, mantidos curtos.
O CLAUDE.md é lido no início de cada sessão. É o conhecimento permanente do agente sobre seu projeto - convenções, arquitetura, o "não fazemos assim por causa daquele incidente."
O erro mais comum de todos: deixá-lo crescer até se tornar um documento gigante de procedimentos que incha cada sessão.
A regra dos praticantes que usam isso diariamente: mantenha o arquivo de memória principal com menos de ~500 tokens. Fatos permanentes vão aqui.
Procedimentos de múltiplas etapas vão em skills (passo 8). Comportamentos específicos de diretório vão em arquivos rules/ com escopo onde se aplicam. Se uma seção do CLAUDE.md se tornou um procedimento em vez de um fato, ela pertence a outro lugar.
Leia seu CLAUDE.md em voz alta. Cada linha deve ser um
fato
que o agente precisa em toda sessão (“usamos pnpm, não npm”). Se uma linha é um
procedimento
(“para adicionar uma funcionalidade, primeiro…”), mova-o para uma skill.
Se for uma regra para uma pasta específica, mova para rules/.
06. settings.json: permissões e modelo, configurados uma vez.
O harness padrão pergunta antes de cada ação arriscada. Isso é certo quando você está observando e errado quando não está. O settings.json é onde você pré-aprova o que é seguro, nega o que é perigoso e escolhe qual modelo será executado.
1{2 "model": "claude-sonnet-4-6",3 "permissions": {4 "autoApprove": [5 "Read(*)", "Grep(*)",6 "Bash(npm test)", "Bash(git status)"7 ],8 "deny": [9 "Bash(rm -rf*)", "Bash(git push*)",10 "Edit(.env*)", "Edit(secrets/*)"11 ]12 }13}
O teste para saber o que auto-aprovar: se isso der errado, qual a dificuldade de desfazer? Barato de desfazer → auto-aprovar.
Caro de desfazer (force-push, deletar arquivos, mexer em segredos) → sempre negar ou perguntar. O meio-termo é ok para auto-aprovar se você registrar em log.
07. Subagentes: contexto isolado para o trabalho pesado.
Um subagente é uma sessão independente do Claude iniciada a partir da principal - sua própria janela de contexto, sua própria lista de ferramentas. O objetivo não é paralelismo por si só. É manter o ruído fora do contexto principal.
Uma tarefa de pesquisa que lê 40 arquivos, uma revisão que precisa de uma perspectiva nova, uma execução de avaliação que produz um monte de logs - essas coisas pertencem a um subagente para não poluírem o thread principal.
GIF
O subagente mais valioso em qualquer harness é aquele que verifica o trabalho que o agente principal fez. Um modelo revisando sua própria produção é muito complacente consigo mesmo;
Um revisor separado com uma nova janela de contexto pega o que o escritor se convenceu a fazer. Esta é a divisão escritor-vs-revisor que torna todo loop acima do harness confiável.
08. Skills: procedimentos que o agente reutiliza.
Uma Skill é um arquivo SKILL.md que o agente executa - seja quando você o chama com /skill-name ou automaticamente quando a tarefa corresponde à sua descrição.
Diferente de um subagente, ele executa na mesma janela de contexto. São apenas instruções reutilizáveis que se tornam parte da sessão.
O gatilho para criar uma: você percebe que está colando as mesmas instruções em toda nova conversa. Essa é uma skill esperando para acontecer. Uma lista de verificação de PR, um procedimento de avaliação, um processo de release - escrito uma vez, invocado para sempre.
E porque skills são a unidade reutilizável, elas são o que faz o harness melhorar com o tempo: cada vez que o procedimento falha de uma nova maneira, você adiciona a lição à skill, e a próxima execução a herda.
09. Hooks: regras determinísticas que o modelo não pode alucinar.
Tudo até agora depende do modelo entender suas instruções. Hooks não dependem.
Um hook é um comando de shell que é disparado em um ponto fixo do ciclo de vida do agente - antes de uma ferramenta ser usada, depois que um arquivo muda, quando a sessão termina - e seu código de saída pode bloquear a ação. Hooks são aplicação de regras, CLAUDE.md é sugestão.
Dois hooks merecem lugar em quase todo harness:
- Uma barreira PreToolUse que bloqueia comandos perigosos deterministicamente — rm -rf, ler .env, fazer push para a main. O código de saída 2 interrompe a chamada antes que ela aconteça. O modelo não consegue argumentar para passar por ela.
- Um formatador PostToolUse que executa seu linter ou formatador após cada edição. O agente nunca envia código não formatado porque o harness o formata automaticamente.
1"hooks": {2 "PreToolUse": [{3 "matcher": "Bash",4 "command": "./.claude/hooks/block-dangerous.sh"5 // exit 2 = block the call before it runs6 }],7 "PostToolUse": [{8 "matcher": "Edit|Write",9 "command": "prettier --write \"$CLAUDE_FILE_PATH\""10 }]11}
Use hooks para qualquer coisa que deve acontecer ou nunca deve acontecer - segurança, formatação, registro de auditoria.
Não os use para decisões subjetivas; para isso serve o modelo. Um bom harness tem um ou dois hooks precisos, não vinte.
Parte 3 · Faça Isso se Acumular
10. Adicione um loop. Agora o harness executa em um cronômetro.
Um harness configurado ainda espera você digitar. Um loop o faz executar sozinho. A versão mais simples é /loop no Claude Code - um prompt recorrente em uma cadência.
Combine com /goal e o loop continua até que uma condição objetiva seja verdadeira, verificada por um avaliador independente, em vez do próprio agente se avaliar.
1> /loop 30m /goal All tests pass and lint is clean.2 Triage new failures, draft fixes in claude/ branches.34▲ Claude uses the harness you built:5 - rules/ for conventions6 - reviewer subagent to check each fix7 - PreToolUse hook blocks pushes to main8✓ Looping. Independent grader decides "done."
Observe o que acabou de acontecer: o loop não adicionou inteligência. Ele reutilizou tudo no harness - as regras, o subagente revisor, o hook de segurança. Um bom harness torna um loop trivial. Esse é o objetivo de construir a base primeiro.
11. Adicione fluxos de trabalho dinâmicos. O harness escreve sua própria orquestração.
Para tarefas complexas demais para um único loop - massivamente paralelas, altamente estruturadas, adversarial - o Claude pode escrever seu próprio harness em JavaScript dinamicamente.
Isso é um fluxo de trabalho dinâmico: agent() para gerar, parallel() para distribuir, pipeline() para encadear. Ele compõe os subagentes que seu harness define em padrões como distribuir-e-sintetizar ou verificação adversarial.
A conexão com a engenharia de harness: um fluxo de trabalho dinâmico é tão bom quanto os subagentes e skills que ele pode chamar.
Se seu harness tem um subagente revisor afiado e uma skill de avaliação bem escrita, o fluxo de trabalho tem boas peças para orquestrar. Se o harness está vazio, o fluxo de trabalho não tem nada com que trabalhar.
O fluxo de trabalho é o maestro, seu harness é a orquestra.
12. Adicione memória. O que o agente esquece, o harness lembra.
Este é o passo que transforma um harness configurado em um sistema que realmente melhora. O agente esquece tudo entre as execuções. O harness não precisa.
Um arquivo de estado - um arquivo markdown em agent-memory/, ou um quadro do Linear - registra o que foi tentado, o que funcionou, o que falhou, quais reguras sobreviveram.
O padrão que faz a memória se acumular, tirado de como os agentes mais fortes a usam:
- Escreva antes de se afastar. Toda execução termina atualizando o arquivo de estado - lições aprendidas, fatos verificados, o que vem a seguir.
- Leia no início. Toda execução começa lendo o arquivo de estado e as skills relevantes, para que ela retome em vez de reiniciar.
- Destile em skills. Quando uma lição é geral (“executores Windows precisam de bash, não PowerShell”), ela é promovida do arquivo de estado para uma skill, onde se aplica a todo projeto futuro.
1# Project memory23## Verified facts # stop guessing about these4- prc is in dollars, not cents (checked via SELECT MIN/MAX)5- auth middleware order: rate_limit -> jwt -> rbac67## Lessons learned # distill the general ones into skills8- Windows CI runners fail TLS 1.2 in PowerShell — use bash9- Migrations on tables >1M rows must batch in 10k chunks1011## Last session # resume, don’t restart122026-06-11 · 3 fixes merged, 2 escalated. Next: verify rate-limit fix.
13. Feche o loop. Saída → lição → skill → saída melhor.
Aqui é onde os três níveis se encaixam em algo que se auto aprimora. Cada execução produz uma saída. O subagente revisor (passo 7) a verifica.
O resultado - o que passou, o que falhou, o que foi aprendido - é escrito na memória (passo 12). As lições gerais são destiladas em skills (passo 8).
A próxima execução herda skills mais afiadas e memória mais rica.
Esse é o loop de auto aprimoramento completo, e observe que ele é construído inteiramente com peças do harness:
- Subagente avalia o trabalho - verificação objetiva, contexto novo.
- Memória registra o veredito - sobrevive entre execuções.
- Skills armazenam as lições - acessíveis por todo projeto.
- O loop executa novamente - agora com tudo que a última execução aprendeu.
O modelo nunca mudou. O harness ao redor dele ficou mais afiado. É isso que "auto aprimorável" realmente significa - não um modelo que aprende, mas um harness que acumula.
14. Distribua o harness. Empacote-o. Compartilhe-o. Reutilize-o.
Um harness que funciona em um projeto é um ativo.
Empacote as skills, subagentes e regras em um plugin e toda sua equipe instala a mesma configuração em um passo - mesmas convenções, mesmos hooks de segurança, mesmo revisor.
O harness deixa de ser sua configuração pessoal e se torna infraestrutura compartilhada.
A ordem para construir, uma última vez, porque a ordem é a lição: torne uma execução manual confiável em um harness limpo.
Adicione o contexto e as permissões. Adicione um subagente revisor. Adicione memória. Então, e somente então, envolva-o em um loop. Um loop em um bom harness se acumula. Um loop em um harness ruim apenas sangra mais rápido.
§ Os erros de harness que pioram todo loop
- Executar no padrão. Sem contexto, sem regras, sem memória - o agente redescobre seu projeto a cada sessão.
- Um CLAUDE.md inchado. Procedimentos enfiados no contexto permanente, inchando toda execução. Mova-os para skills.
- Aplicação de regras no CLAUDE.md em vez de hooks. O modelo pode ignorar uma sugestão. Ele não pode ignorar um hook que sai com código 2.
- Um único agente escrevendo e avaliando seu próprio trabalho. Adicione um subagente revisor com uma nova janela de contexto.
- Sem memória. Toda execução recomeça do zero. O arquivo de estado é o que faz o amanhã retomar.
- Envolver um loop em torno de um harness ruim. O loop apenas produz porcaria mais rápido. Construa a base primeiro.
- Vinte hooks. Um ou dois precisos valem mais que uma pilha que ninguém entende.
- Distribuir um harness sem escaneá-lo. Segredos vazados e permissões excessivamente amplas se espalham para todos que o instalam.
Conclusão:
O loop recebe a glória. O harness faz o trabalho.
A engenharia de loops é a parte empolgante - o agente dando prompts a si mesmo, executando enquanto você dorme. Mas um loop é apenas um harness com um cronômetro.
Tudo que decide se a saída é boa ou lixo está um andar abaixo, no modelo que você escolheu, nas ferramentas que você permitiu, no contexto que você escreveu, no revisor que você adicionou, na memória que você manteve.
Construa esse andar bem e tudo acima dele se acumula: o loop reutiliza seus subagentes, o fluxo de trabalho orquestra suas skills, a memória torna cada execução mais afiada que a anterior.
O auto aprimoramento nunca foi uma propriedade do modelo. É uma propriedade do harness que você constrói ao redor dele.
Escolha uma coisa que você não está fazendo - provavelmente um subagente revisor, um hook de segurança ou um arquivo de estado - e adicione hoje. Mantenha o harness pequeno o suficiente para explicar. Então coloque um loop em cima, e veja a base fazer o trabalho.
