Todo mundo está falando sobre loops. Quase ninguém está falando sobre o que o loop executa. 9 em cada 10 desenvolvedores rodam o Claude Code no harness padrão — sem regras, sem subagentes, sem hooks, sem memória.
Depois se perguntam por que seu loop produz lixo. A verdade é simples: um loop só é tão bom quanto o harness que o sustenta. Este é o roteiro de 14 passos para o harness — de um agente a um sistema que se autoaperfeiçoa.
Siga meu Substack para receber novidades sobre AI alpha:
Engenharia de loops — construir um sistema que instrui seu agente em um cronograma — recebeu toda a atenção este mês. Mas Addy Osmani, que escreveu o artigo longo sobre loops, teve o cuidado de apontar o que está por baixo:
"A engenharia de loops fica um andar acima do harness. O harness é o ambiente no qual um único agente opera. O loop é o harness, mas funciona em um temporizador, cria ajudantes e se alimenta sozinho."
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 o que está acima 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 se sustenta.
Parte 1 · O que é Harness
01. Um harness é o ambiente no qual um agente opera.
Tirando o jargão, um harness é quatro coisas: o modelo que pensa, as ferramentas que ele pode acessar, 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.
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, olha 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 ao iniciar. Mesmo modelo, harness diferente, agente completamente diferente.
02. O harness inteiro vive em uma pasta. .claude/
Tudo que molda seu agente fica em um único diretório na raiz do seu projeto. Aprenda esse layout e você pode 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 caminho6│ ├─ 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 andares, não os misture.
A maioria dos problemas de "meu setup de agente é uma bagunça" vem de confundir os três andares. Mantenha-os claros:
- O harness é o ambiente de execução de um agente. Configuração estática: modelo, ferramentas, permissões, contexto. Este artigo.
- O loop instrui o agente em um temporizador, cria ajudantes, alimenta-se. Ele funciona sobre o harness.
- O sistema autoaperfeiçoável é um loop mais memória que se acumula — cada execução deixa a próxima mais afiada.
A versão prática: coloque fatos permanentes no contexto, imposição em hooks, procedimentos em skills e isolamento em subagentes.
Misturar esses — imposição no CLAUDE.md, procedimentos inchando o contexto — é a causa raiz de agentes inconsistentes e caros.
04. O harness padrão. O que você ganha pronto.
Instale o Claude Code, abra uma pasta, e você já tem um harness — apenas um vazio. O padrão oferece um modelo capaz, as ferramentas integradas (ler, escrever, bash, pesquisar) e prompts de aprovação para tudo arriscado. Sem contexto de 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 longe: deixá-lo crescer em um documento gigante de procedimentos que incha toda sessão.
A regra dos profissionais que usam isso diariamente: mantenha o arquivo de memória principal com menos de ~500 tokens. Fatos permanentes vão aqui.
Procedimentos de múltiplos passos vão em skills (passo 8). Comportamentos específicos de caminho vão em arquivos rules/ com escopo para 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 um recurso, primeiro..."), mova-a para uma skill.
Se for uma regra para uma pasta, mova-a 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á olhando e errado quando não está. settings.json é onde você pré-aprova o que é seguro, nega o que é perigoso e escolhe qual modelo executa.
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 o que aprovar automaticamente: se isso der errado, quão difícil é desfazer? Barato de desfazer → aprovação automática.
Caro de desfazer (force-push, deletar arquivos, mexer em segredos) → sempre negue ou pergunte. O meio termo é aceitável para aprovação automática se você registrar em log.
07. Subagentes: contexto isolado para o trabalho sujo.
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 passagem de revisão que precisa de uma perspectiva nova, uma execução de avaliação que produz uma parede de logs — essas pertencem a um subagente para não poluir 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 janela de contexto nova pega o que o escritor se convenceu a fazer. Esta é a divisão escritor-vs-verificador que torna confiável cada loop acima do harness.
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 é executado 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. Isso é uma skill esperando para acontecer. Uma checklist 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, são elas que fazem o harness melhorar ao longo do tempo: cada vez que o procedimento falha de uma maneira nova, 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 shell que dispara em um ponto fixo do ciclo de vida do agente — antes de uma ferramenta ser executada, 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 imposição, 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. Código de saída 2 interrompe a chamada antes que aconteça. O modelo não consegue argumentar para passar.
- 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 = bloqueia a chamada antes dela executar6 }],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, auditoria de logs.
Não os use para decisões de julgamento; para isso serve o modelo. Um bom harness tem um ou dois hooks precisos, não vinte.
Parte 3 · Faça com que se Acumule
10. Adicione um loop. Agora o harness funciona em um temporizador.
Um harness configurado ainda espera você digitar. Um loop o faz funcionar 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 Todos os testes passam e o lint está limpo.2 Triagem de novas falhas, rascunho de correções em branches claude/.34▲ Claude usa o harness que você construiu:5 - rules/ para convenções6 - subagente reviewer para verificar cada correção7 - hook PreToolUse bloqueia pushes para a main8✓ Looping. Avaliador independente decide "pronto."
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 JavaScript em tempo real.
Isso é um fluxo de trabalho dinâmico: agent() para gerar, parallel() para distribuir, pipeline() para transmitir. 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 só é 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 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, extraído de como os agentes mais fortes a usam:
- Escreva antes de sair. Cada execução termina atualizando o arquivo de estado — lições aprendidas, fatos verificados, o que vem a seguir.
- Leia no início. Cada execução começa lendo o arquivo de estado e 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 se forma do arquivo de estado para uma skill, onde se aplica a todo projeto futuro.
1# Memória do projeto23## Fatos verificados # pare de adivinhar sobre estes4- prc está em dólares, não em centavos (verificado via SELECT MIN/MAX)5- ordem do middleware de autenticação: rate_limit -> jwt -> rbac67## Lições aprendidas # destile as gerais em skills8- Executores CI do Windows falham TLS 1.2 no PowerShell — use bash9- Migrações em tabelas >1M linhas devem ser em lote de 10k chunks1011## Última sessão # retome, não reinicie122026-06-11 · 3 correções mescladas, 2 escaladas. Próximo: verificar correção de limite de taxa.
13. Feche o loop. Saída → lição → skill → saída melhor.
Aqui é onde os três andares se encaixam em algo que se aperfeiçoa. Cada execução produz 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 autoaperfeiçoável completo, e observe que ele é construído inteiramente a partir de partes do harness:
- Subagente avalia o trabalho — verificação objetiva, contexto novo.
- Memória registra o veredito — sobrevive entre execuções.
- Skills armazenam o conhecimento — acumulam a cada ciclo.
- 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 "autoaperfeiçoável" significa honestamente — 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 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.
- Imposição no CLAUDE.md em vez de hooks. O modelo pode ignorar uma sugestão. Não pode ignorar um hook que sai com código 2.
- Um agente escrevendo e avaliando seu próprio trabalho. Adicione um subagente revisor com uma janela de contexto nova.
- Sem memória. Toda execução recomeça do zero. O arquivo de estado é o que faz amanhã retomar.
- Envolver um loop em torno de um harness ruim. O loop apenas produz lixo mais rápido. Construa a base primeiro.
- Vinte hooks. Um ou dois precisos vencem 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.
Engenharia de loops é a parte empolgante — o agente se instruindo, funcionando enquanto você dorme. Mas um loop é apenas um harness em um temporizador.
Tudo que decide se a saída é boa ou lixo vive um andar abaixo, no modelo que você escolheu, nas ferramentas que permitiu, no contexto que escreveu, no revisor que adicionou, na memória que manteve.
Construa bem esse andar 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.
Autoaperfeiçoamento 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.
