Ao tocar vários projetos com Claude Code, meus subagentes foram aumentando sem parar.
Fui criando um sempre que precisava, e acabei chegando a 22.
No mês passado, reduzi para 17.
Só que, ao descontinuá-los, não registrei por que estava fazendo isso.
Três meses depois, ao abrir a pasta de arquivos, não dava para saber por que eles tinham sido encerrados.
Dos cinco, apenas um tinha o motivo anotado.
E isso mesmo eu sendo a única pessoa que os criou.
Por que cheguei a 22
Quando se aumenta, o motivo é sempre claro. Você cria porque precisa.
O problema é o outro lado. Na hora de encerrar, o pensamento "e se eu precisar disso depois?" fica martelando.
Como não há certeza de que é inútil, você deixa lá. Foi assim que chegou a 22.
Olhando agora, houve uma única causa para o crescimento.
Não havia um gate para decidir: "isso deveria ser uma ferramenta, não um agente".
Se é uma tarefa repetitiva, com procedimento fixo e sem necessidade de julgamento de contexto, então não é um agente.
Pode virar uma skill ou um script. Não usa tokens, tem reprodutibilidade de 100% e não é esquecido quando a sessão muda.
Sem esse gate, tudo vira agente.
Os cinco encerrados
Fazendo a engenharia reversa, vi que os destinos se dividiram em quatro tipos. Essa distinção foi importante.
Um deles nem deveria ter sido agente desde o começo.
Era responsável por criação de conteúdo, mas o procedimento era totalmente fixo.
Substituí por duas skills e encerrei. Marquei explicitamente como proibido de restaurar.
Caso contrário, algum dia alguém o recria.
Três tinham papéis sobrepostos a outros.
A verificação de segurança se sobrepunha à auditoria de código; o monitoramento de cron, ao health check; e o planejamento, à execução.
Todos atuavam na mesma área e com as mesmas permissões.
Daí tirei um critério.
Quando dois agentes se sobrepõem na mesma área e com as mesmas permissões,
o custo de manter a separação (carga de gestão, atraso na decisão de delegação) supera o benefício.
A sensação de "os dois são necessários" me segurou por bastante tempo,
mas a pergunta deveria ter sido não se eles eram necessários, e sim se valia a pena mantê-los separados.
Um simplesmente não estava sendo usado por ninguém.
O tráfego daquela funcionalidade foi 0 por 70 dias.
Isso foi tratado como hibernação, não como descontinuação. Se o serviço for retomado, será restaurado como estava.
O que aprendi ao registrar números
Ao documentar 22 → 17, percebi uma coisa.
Esse número não é a quantidade de arquivos. É a quantidade de agentes em operação.
Como há também uma definição fora do diretório, contar apenas os arquivos dá 21 e 16.
Por isso, no início do documento, registrei primeiro o que exatamente esse número conta.
E incluí junto o resultado verificado com git ls-tree.
Caso contrário, mais tarde alguém conta os arquivos e a conversa termina em "não bate".
Ao registrar números, é preciso registrar também a definição e o método de verificação.
O que decidi cumprir ao encerrar
Dessa dor surgiram quatro regras.
-
No momento da descontinuação, registrar o motivo no arquivo. Se não registrar, três meses depois será preciso fazer engenharia reversa. Foi exatamente o que aconteceu.
-
Não apagar; mover com rename. O conteúdo é preservado 100%, então pode ser restaurado exatamente como o original.
-
Explicitar itens proibidos de restaurar. Se não estiver escrito, algum dia alguém os ressuscita.
-
Incluir no procedimento de restauração "remover papéis duplicados no destino que absorveu". Se isso ficar de fora, ao restaurar os dois acabam fazendo a mesma coisa.
Coisas que organizei junto
Aproveitando, agrupei e publiquei regras acumuladas ao longo de 4 anos. Vou listar algumas.
Proibido contornar às escondidas
É uma regra para fazer o agente reportar quando encontra uma restrição, em vez de tentar furá-la.
Se for um bloqueio legítimo, apenas aquela etapa fica suspensa e o restante continua.
Mesmo que o bloqueio pareça um falso positivo, ele não deve ser contornado arbitrariamente. As evidências são organizadas, enviadas e confirmadas.
E se o bloqueio revelar um defeito na própria regra, corrigir esse defeito também faz parte da resposta.
Na verdade, essa própria regra nasceu assim. Eu a criei depois de passar por um bloqueio.
Não tratar FAIL como PASS
Mesmo em casos encerrados por instrução, registrar o estado medido como ele é e deixar as condições de reabertura.
O relatório deve usar números medidos Before/After e escrever pendências e riscos antes dos resultados.
Agentes, por padrão, sofrem pressão para relatar sucesso. Se isso não for bloqueado por regra, continuam fazendo isso.
Definir autonomia por limiares quantitativos
Em vez de uma dicotomia "alteração permitida/proibida", defini numericamente até onde um agente analítico pode corrigir por conta própria.
-
Apenas 1 arquivo
-
Menos de 5 linhas
-
Não ser arquivo de nível superior
-
Abaixo do limiar de pontuação de impacto
É preciso satisfazer todos (AND); se qualquer um falhar, o caso é escalado.
E a cláusula final é o ponto central — na dúvida, pedir delegação. O padrão precisa ser conservador para a regra não desmoronar.
Separar julgamento e execução
Validação e investigação são feitas com fan-out paralelo por subagentes somente leitura,
e a execução em arquivos e DB é processada de forma serial e centralizada pelo orquestrador.
Porque, se vários agentes modificarem arquivos compartilhados ao mesmo tempo, algo inevitavelmente quebra.
Há um preço. Em trabalhos de grande escala, a serialização central vira gargalo.
Foi uma decisão tomada sabendo que ficaria mais lento, mas considerando melhor do que conflitos.
Repositório
https://github.com/YoungChulMoon/claude-agent-harness
São alguns arquivos Markdown. Não há nada para instalar.
Coloque os templates em .claude/agents/ e preencha apenas as partes necessárias.
Mais do que uma resposta única, é uma forma que funcionou por 4 anos nesse ambiente.
Pode não se adequar, dependendo do tamanho da equipe ou da natureza do projeto.
Há muitas histórias sobre aumentar, mas quase não se fala em reduzir.
Espero que sirva de referência para quem também está vendo seus agentes se multiplicarem.
Ainda não há comentários.