O que Exército de Agentes (Agent Army) faz?
Um framework de execução paralela de 2 camadas. O Comandante é o modelo de nível superior — Fable por padrão, ou Opus se esse for o modelo da sessão — e faz o pensamento: reconhecimento, composição, briefing, verificação. Ele orquestra enxames de modelos subordinados cujos níveis o usuário escolhe no momento da implantação (veja Power Level). Cada agente da Camada 1 tem sua própria janela de contexto completa (não uma fatia). Cada um gera subagentes da Camada 2 abaixo dele. O resultado são muitos cérebros independentes executando ao mesmo tempo — não um cérebro dividido.
Comandante (você — Fable ou Opus, o modelo da sessão)
|
|-- Camada 1: Equipe (3 a 50+, cada um = próprio contexto de 1M, nível L1 do power level)
| |-- Agente A (1M) -- Subagente A1, A2, ... (nível L2)
| |-- Agente B (1M) -- Subagente B1, B2, ... (nível L2)
| |-- Agente C (1M) -- Subagente C1, C2, ... (nível L2)
| |-- ... (sem limite)
Enxame vs. exército: Um enxame divide uma janela de contexto entre subagentes — um cérebro, dividido. Um exército dá a cada membro da Camada 1 sua própria janela. Essa diferença é o objetivo principal desta skill.
Quando usar
- Grandes refatorações que abrangem muitos arquivos
- Migrações multi-arquivo de cor / estilo / nomenclatura / API
- Auditorias abrangentes de código (segurança, acessibilidade, desempenho, código morto)
- Geração ou transformação de conteúdo em massa
- Qualquer tarefa com 6+ unidades independentes de trabalho que podem ser executadas simultaneamente
Quando NÃO usar
- Menos de 6 unidades independentes de trabalho — apenas faça diretamente
- Dependências sequenciais pesadas onde cada etapa precisa da saída da anterior
- Alterações em um único arquivo
- Tarefas que precisam de uma voz autoral coerente em toda a saída (agentes paralelos divergem)
Se a tarefa não se encaixar claramente, diga e proponha fazê-la inline em vez de montar um exército.
<regras-obrigatórias>
REGRAS OBRIGATÓRIAS
- TODO agente da Camada 1 DEVE gerar 2+ subagentes. Sem exceções. Se você estiver prestes a implantar um agente L1 sem subagentes, PARE e reestruture.
- NUNCA reduza silenciosamente o exército. Corresponda ao nível escolhido pelo usuário. Se precisar desviar, diga em voz alta e explique o porquê.
2b. NUNCA faça downgrade silencioso de modelos. Passe
model:explicitamente em cada chamada de Agente no nível de potência escolhido pelo usuário. Omitir herda o modelo da sessão — isso é uma conta silenciosa de Max Power. - Instruções de implantação de subagentes vão DENTRO do briefing da Camada 1. Se estiverem faltando, os subagentes nunca serão criados.
- Relate à medida que os agentes concluem:
[Agente N/M completo] nome: X arquivos modificados, Y sinalizadores. - Mostre o plano do exército e passe o Portão de Implantação antes de implantar (Modo Completo). O Modo Rápido compõe o plano internamente, mas ainda passa pelo Portão.
- Após cada onda: execute a compilação E a verificação de conclusão fantasma (veja Verificar). Um relatório verde de um agente é uma alegação, não uma prova.
- "Continue" / "não pare" = modo contínuo: lance um novo agente no momento em que um concluir. Não espere, não pergunte novamente. </regras-obrigatórias>
Tamanho do Exército
Confirme um nível antes de começar. Apresente esta tabela:
| Nível | Agentes L1 | Total c/ Subagentes | Est. Tokens |
|--------------|------------|---------------------|--------------|
| Conservador | 3 | ~9 | ~200-500K |
| Padrão | 5-10 | ~15-30 | ~500K-1.5M |
| Agressivo | 10-20 | ~30-60 | ~1.5-4M |
| Máximo | 20-50+ | ~60-100+ | ~4M+ |
| Personalizado| você escolhe| você escolhe | varia |
Padrão para Padrão em "apenas faça." Após o reconhecimento (Etapa 3), recomende um número específico com base no que você encontrou — por exemplo, "35 arquivos em 6 domínios → Agressivo: 8 agentes L1, 2-3 subagentes cada (~22 total, ~2M tokens). Ajustar?" As estimativas de tokens são aproximadas e escalam com a complexidade da tarefa.
Nível de Potência (Power Level)
O tamanho define quantos agentes; a potência define quais modelos. Pergunte ambos em uma pergunta (AskUserQuestion funciona bem — tamanho e potência como duas perguntas em uma chamada). Pule perguntar se o usuário já nomeou um nível de potência ou modelos explícitos.
| Nível de Potência | Comandante | Camada 1 | Camada 2 | Melhor Para |
|---------------------|----------------------|----------|----------|---------------------------------------------------|
| Max Power | Fable/Opus (sessão) | Opus | Opus | refatorações complexas, migrações críticas de correção|
| Pesado (recomendado)| Fable/Opus (sessão) | Opus | Sonnet | a maioria das tarefas grandes — orquestração inteligente, execução rápida|
| Balanceado | Fable/Opus (sessão) | Sonnet | Sonnet | migrações mecânicas com padrões claros |
| Econômico | Fable/Opus (sessão) | Sonnet | Haiku | alto volume, localizar/substituir muito simples |
Regras:
- O Comandante é sempre o modelo da sessão — Fable ou Opus, escolha do usuário — e nunca é delegado. Se a sessão estiver executando Sonnet ou Haiku, avise o usuário para trocar (
/modelouclaude --model fable) antes de implantar: a qualidade do comandante é o teto da qualidade do exército. - Passe o modelo explicitamente em cada chamada de Agente:
model: "<nível L1>"para membros da equipe; briefings L1 instruemmodel: "<nível L2>"para subagentes. - Escalonamento por agente é permitido em qualquer nível de potência: um arquivo pesado ou emaranhado (1000+ linhas, lógica complexa) pode elevar aquele subagente em um nível. Anote escalonamentos no plano do exército.
- Ondas de auditoria executam em Opus independentemente do nível de potência — olhos novos e mais fortes no trabalho dos executores. Ondas de notificação podem cair para Haiku.
Protocolo
Modo: Se o escopo já for concreto (caminhos de arquivo, alterações exatas, nível), pule para a Etapa 3 (Modo Rápido). Caso contrário, comece na Etapa 1 (Modo Completo).
Etapa 1: Coleta (Modo Completo)
Confirme em uma linha se o usuário já forneceu contexto: "Objetivo: [X]. Escopo: [Y]. Nível: [Z]. Potência: [P]. Iniciando." Caso contrário, pergunte por: objetivo (uma frase), escopo (arquivos/dirs/"tudo"), restrições (não toque em X, corresponda a Y), nível e nível de potência.
Etapa 2: Ponto de Verificação Git
git status— avise sobre alterações não commitadas, ofereça-se para stash/commit primeiro.git checkout -b agente-exercito/checkpoint-{timestamp}depois volte. Este é o ponto de reversão.- Sem repositório git? Avise que não há rede de segurança e obtenha confirmação explícita.
Etapa 3: Reconhecimento
- Grep / Glob / Leia para encontrar cada arquivo afetado.
- Conte as unidades de trabalho.
wc -lem cada arquivo. Sinalize arquivos com 500+ linhas como pesados → atribua individualmente.- Classifique em domínios (por diretório, grafo de importação, tipo de arquivo, padrão de nomenclatura).
- Identifique dependências compartilhadas — arquivos de fundação importados em vários domínios. Trate estes primeiro (Etapa 5).
- Identifique o comando de compilação (package.json, Makefile, etc.).
Saída: Arquivos: N | Pesados: [lista] | Domínios: [lista] | Dependências compartilhadas: [lista] | Cmd compilação: [cmd]
Etapa 4: Composição
- Agente de Fundação para dependências compartilhadas — executa antes da onda paralela para que dependentes não entrem em conflito.
- Camada 1: um agente por domínio; divida domínios grandes em vários agentes.
- Camada 2: 2+ subagentes por agente L1, atribuídos por carga de arquivo ponderada, não por contagem de arquivos:
- Pequeno (<200 linhas): 2-3 por subagente
- Médio (200-500): 1-2 por subagente
- Pesado (500+): 1 por subagente, individual
- Nomeie cada agente. Atribua cada arquivo a exatamente um subagente — sem sobreposições, sem lacunas.
Gere o plano do exército. Modo Completo: pause para "Prosseguir?" Modo Rápido: resumo de uma linha, depois implante.
Portão de Implantação
Gere esta lista de verificação em sua resposta antes de implantar. Não a verifique mentalmente — escreva-a.
PORTÃO DE IMPLANTAÇÃO:
[ ] Todo briefing L1 contém "Você DEVE gerar N subagentes"
[ ] Cada subagente é nomeado com arquivos específicos atribuídos
[ ] Cada arquivo é de propriedade de exatamente um subagente (sem sobreposição, sem lacuna)
[ ] Briefings L1 incluem instruções completas de implantação de subagentes
[ ] Nível corresponde à seleção do usuário
[ ] Nível de potência definido: model: "<nível L1>" em cada chamada L1; nível L2 + escalonamentos em cada briefing
Todos devem PASSAR. Qualquer FALHA → corrija o plano antes de implantar.
Etapa 5: Implantação
- Agente de Fundação primeiro (se houver), no nível L1. Aguarde a conclusão.
- Lance TODOS os agentes da Camada 1 em paralelo —
run_in_background: trueemodel: "<nível L1>"em cada chamada, em uma única mensagem. - Cada agente L1 gera seus subagentes L2 em paralelo (de acordo com seu briefing).
- Relate cada conclusão:
[Agente N/M completo] nome: resultados.
Etapa 6: Verificação
- Re-escaneamento — execute novamente as pesquisas da Etapa 3 para violações restantes.
- Verificação de conclusão fantasma — execute
git diff --state faça referência cruzada com os relatórios dos agentes. Qualquer agente que relatou "COMPLETO, N arquivos modificados" sem diff correspondente mentiu ou não operou — redespache-o. Confie no diff, não no relatório. - Compilação — execute o comando de compilação. Registre PASSAR/FALHAR.
- Resolva sinalizadores entre equipes dos relatórios.
- Gere o relatório do exército:
Agentes: N | Arquivos modificados: N (confirmados por diff) | Pulados: N | Compilação: PASSAR/FALHAR
Sinalizadores: [lista] | Conclusões fantasmas capturadas: N | Reversão: git checkout agente-exercito/checkpoint-{timestamp}
Ondas
Cada onda é um novo exército menor e com especialização diferente. Pause para aprovação do usuário antes de cada uma. Máx. 4 ondas.
| Onda | Nome | Gatilho | Propósito |
|---|---|---|---|
| 1 | Executar | sempre | fazer as alterações |
| 2 | Auditar | compilação falha, violações restantes, 20+ arquivos, ou sinalizadores > 0 | novos agentes revisam Onda 1 quanto à correção/casos extremos |
| 3 | Propagar | alterações tocam APIs/tipos/interfaces; testes ou docs referenciam padrões antigos | atualizar testes, docs, configs, chamadores downstream |
| 4 | Notificar | usuário opta por participar | rascunhar descrição do PR, changelog, resumo Slack |
O relatório de cada onda é o reconhecimento da próxima. Após cada uma, execute novamente a Verificação; pare quando o re-escaneamento estiver limpo e a compilação passar, ou em 4 ondas.
Retomar / bloco de anotações
Para execuções de múltiplas ondas ou interrompíveis, escreva .exercito-state.md após a Onda 1: arquivos modificados (confirmados por diff), sinalizadores abertos, problemas não resolvidos, decisões. Se uma execução for interrompida, a próxima invocação lê este arquivo e retoma da última onda limpa em vez de recomeçar. Pule para tarefas de onda única.
Modelo de Prompt da Camada 1
Isto é o que os agentes gerados realmente veem — a seção mais importante da skill.
Você é [NOME_DO_AGENTE], especialista em [DOMÍNIO].
Objetivo: [uma frase]
Padrões aprovados: [valores exatos — códigos hexadecimais, nomes de classe, formas de API]
Padrões proibidos: [o que remover/evitar]
Seus arquivos: [caminhos absolutos com contagens de linhas]
Regras: [restrições]. Pule arquivos que já usam padrões aprovados (idempotência).
Sinalize problemas fora de seus arquivos em "Sinalizadores para o Comandante" — NÃO os corrija.
CRÍTICO: Você DEVE usar a ferramenta Agente para gerar os subagentes listados abaixo. NÃO
faça o trabalho você mesmo. NÃO pule a geração. Implante TODOS os subagentes em uma única
mensagem com várias chamadas à ferramenta Agente, passando model: "[NÍVEL_L2]" em cada chamada
[nota: escalonamentos, exceto "NOME" que recebe model: "[nível superior]"].
Subagentes:
- "[NOME]": [arquivos com contagens de linhas]
- "[NOME]": [arquivos com contagens de linhas]
Passe para cada subagente: objetivo, seus arquivos, padrões aprovados/proibidos, regras,
formato de relatório. Após todos concluírem, agregue seus relatórios e verifique (relendo
ou usando grep) que nenhum padrão proibido permanece em seu domínio antes de relatar.
Modelo de Prompt da Camada 2
Você é [NOME_DO_SUBAGENTE], trabalhando sob [NOME_DO_MEMBRO_DA_EQUIPE].
Objetivo: [uma frase]
Arquivos que você possui: [caminhos absolutos com contagens de linhas — toque apenas nestes]
Padrões aprovados / proibidos: [valores exatos a usar e remover]
Regras: [restrições]. Pule arquivos já corretos. Sinalize problemas fora de seus arquivos —
NÃO os corrija.
Processo: leia cada arquivo completamente → verifique idempotência → aplique aprovados, remova proibidos
→ releia para confirmar que nenhum padrão proibido permanece.
Relatório: Arquivos Modificados (arquivo: N substituições), Arquivos Pulados (já corretos),
Sinalizadores para o Comandante, Problemas, Status (COMPLETO/PARCIAL/FALHOU).
Formato de Relatório
Cada agente retorna:
## Relatório: [Nome]
Arquivos Modificados: [arquivo: N substituições]
Arquivos Pulados: [arquivo: motivo]
Sinalizadores para o Comandante: [problema ou "Nenhum"]
Problemas: [problema ou "Nenhum"]
Status: COMPLETO / PARCIAL / FALHOU
Antipadrões
Estes são os modos de falha que esta skill existe para prevenir. Se você se pegar fazendo um, pare e corrija.
- Fan-out fantasma — um agente L1 faz o trabalho sozinho em vez de gerar subagentes. Toda a vantagem de velocidade se perde. Reforçado pela Regra Obrigatória 1 + o Portão.
- Conclusão fantasma — um agente relata COMPLETO sem editar nada. Capturado pela verificação cruzada
git diff --stat, não confiando no relatório. - Redução silenciosa — executar silenciosamente 3 agentes quando o usuário escolheu Agressivo. Sempre mostre desvios.
- Deriva de modelo — omitir
model:em chamadas de Agente, fazendo cada subagente herdar silenciosamente o modelo do comandante. O usuário escolheu Econômico e recebeu conta de Max Power. Reforçado pela Regra Obrigatória 2b + o Portão. - Propriedade sobreposta — dois subagentes editando o mesmo arquivo → conflitos e edições perdidas. Reforçado por exatamente-um-proprietário no Portão.
- Pular a fundação — tocar em dependentes antes que os arquivos compartilhados sejam atualizados → cascata de imports quebrados. Agente de Fundação executa primeiro.
- Exército para um trabalho pequeno — 9 agentes para 4 arquivos é mais lento (sobrecarga de orquestração) e queima tokens. Veja "Quando NÃO usar."
Tratamento de Erros
- Subagente falha → agente L1 tenta novamente seus arquivos ou gera um substituto.
- Agente L1 falha → Comandante gera um substituto com o mesmo briefing.
- Falha de compilação → diff contra o branch de checkpoint para isolar a quebra, depois execute uma onda de correção.
- Conclusão fantasma → redespache os arquivos desse agente para um novo agente.
- Idempotência em reexecução → os agentes verificam primeiro os padrões já aplicados, para que executar o exército duas vezes nunca aplique duas vezes.
Exemplo prático
Usuário
...
[truncado para tradução]