IA e Automações · 18 de novembro de 2026 · 5 min
Subagentes no Claude Code: o que aprendi rodando dezenas em paralelo
Subagente é um agente com contexto próprio que o Claude Code dispara para uma parte do trabalho. Quando usar e as regras que nasceram dos meus erros.
- O problema
- Você quer rodar vários agentes ao mesmo tempo e tem medo de perder trabalho, ou já perdeu e não entendeu onde.
- Para aplicar
- Divida uma tarefa em três partes independentes, escreva uma seção por agente num arquivo de tarefas, mande cada um gravar antes de revisar e confira os três resultados você mesmo.
Subagente é um agente que o Claude Code dispara para cuidar de uma parte do trabalho, com contexto próprio, e que devolve só o resultado. O agente principal continua com a cabeça limpa, e várias partes podem andar ao mesmo tempo. Você define um subagente num arquivo markdown dentro de .claude/agents/, com nome, descrição de quando usar, ferramentas permitidas e as instruções.
Eu uso subagente para quase tudo que é grande: escrever e revisar uma leva de posts de blog, auditar sites, organizar arquivos. Já rodei dezenas numa sessão só. O que segue é o que deu errado nessas levas e a regra que nasceu de cada erro.
Quando vale usar subagente?
- Quando a tarefa se divide em partes que não dependem umas das outras, como dez posts ou cinco sites.
- Quando a busca vai ler muito arquivo e você só quer a conclusão.
- Quando você quer uma revisão que não carregue o raciocínio de quem escreveu.
Quando não vale: tarefa pequena, que você resolveria em três passos. Subagente custa caro de outro jeito, porque ele só sabe o que está no briefing, e você só vê o resumo que ele devolve.
Como eu organizei os meus
Até agosto eu tinha 17 agentes, quase um por cliente. Em 19 de agosto juntei em cinco, separados pelo tipo de trabalho: um produz peça de conteúdo para qualquer marca, um cuida de negócio, um mexe em código, um mexe no próprio sistema e um traz pesquisa de fora. O cliente virou parâmetro, e o agente de conteúdo lê o arquivo daquele cliente antes de escrever. Conto o desenho em Agentes de IA para agência de marketing.
Grave o arquivo cedo
Em 27 de agosto rodei uma leva grande para escrever e revisar posts do blog da Kaleidos. O limite de sessão estourou no meio e matou 19 dos 20 agentes que estavam trabalhando. Os posts estavam prontos, só que na cabeça deles: nada tinha sido salvo em disco, e trabalho que vive no contexto do agente morre com ele.
Acrescentei uma linha no briefing: "grave o arquivo cedo, depois refine". No estouro seguinte, 23 de 30 sobreviveram. Uma frase levou a sobrevivência da leva de 5% para 77%.
Dois agentes, um arquivo: o último apaga o outro
Em 16 e 17 de setembro o diário do dia foi apagado duas vezes. Cada agente, ao terminar, abria o diário, acrescentava a sua linha e gravava o arquivo inteiro de volta. Quem gravava por último apagava o que os outros tinham escrito entre a leitura e a gravação dele. Num dos casos, o agente que perdeu a linha tinha acabado de conferir que ela estava lá.
O conserto foi um script que só acrescenta. Ele trava o arquivo, insere a linha e se recusa a gravar se qualquer linha que existia antes fosse sumir. Desde então, nenhum agente escreve o diário de outro jeito.
O mesmo aconteceu com arquivo temporário: dois agentes criaram um script com o mesmo nome na mesma pasta de rascunho, e um sobrescreveu o do outro no meio da execução. Hoje todo briefing de leva paralela exige uma subpasta com o nome do agente.
Quem apaga é um só
Edição concorrente se resolve dando território separado para cada agente. Remoção, não. Quem decide o que sai precisa enxergar o conjunto inteiro, e dois agentes limpando ao mesmo tempo nunca enxergam o mesmo conjunto.
Em setembro, enquanto um agente limpava pastas de trabalho com cuidado, outro processo limpou várias em paralelo, inclusive algumas criadas naquele mesmo dia. Nada se perdeu, mas por sorte. Faxina virou tarefa de um agente só.
"Verifiquei" não é verificação
Agente relata com a mesma confiança quando acerta e quando erra. Já recebi "conferido" de revisão que tinha contado errado e de deploy que não tinha subido. A regra aqui: a checagem final que importa (abrir a página, rodar o teste, contar o arquivo) é feita por quem recebe o trabalho, não por quem entrega.
O computador também cansa
Hoje, 18 de novembro, o Mac travou com vários agentes rodando build e teste ao mesmo tempo. O peso não vem do agente pensar, vem do comando pesado que ele dispara. A saída foi uma fila única: todo comando pesado de qualquer agente espera a vez e roda com prioridade baixa, e servidor local de teste sobe e desce dentro do mesmo comando.
Checklist para a sua primeira leva
- Tarefa em arquivo, uma seção por agente. Se um morrer, relançar custa uma linha.
- Mande gravar cedo.
- Uma pasta própria para cada um.
- Arquivo compartilhado só por acréscimo, nunca regravado inteiro.
- Nada de apagar em paralelo.
- Confira você mesmo o que importa.
O que fazer amanhã
Pegue uma tarefa que se divide em três partes independentes e rode com três subagentes, cada um com uma seção própria num arquivo de tarefas e a instrução de gravar o resultado antes de revisar. No fim, confira os três arquivos você mesmo, antes de ler o resumo deles.