Imagine que você precisa processar 210 arquivos de uma só vez: revisar código, extrair metadados, gerar relatórios. Fazer isso em sequência levaria horas. Com um workflow dinâmico, o orquestrador dispara um subagente por arquivo — todos ao mesmo tempo, cada um na sua janela — e você recebe o consolidado em minutos. O desenho abaixo é o que acontece por baixo.
Conteúdo detalhado
🌐 O que é um workflow dinâmico
No Claude Code, um workflow dinâmico é uma orquestração onde o
número de subagentes não está fixo no prompt — ele é determinado em
tempo de execução pelo orquestrador. O maestro recebe a lista de itens, decide quantos agentes vai precisar
e os dispara todos via Task tool, um para cada item.
O que é
Uma estrutura de execução onde o orquestrador gera dinamicamente N tarefas paralelas com base no input — seja uma lista de arquivos, uma lista de URLs, uma lista de capítulos ou qualquer coleção iterável. Cada item vira um subagente independente.
Por que aprender
Entender workflows dinâmicos é o que permite executar jobs que seriam impossíveis em sequência dentro de uma única sessão. É a diferença entre processar 5 arquivos e processar 200 — com o mesmo esforço de prompt. Sem esse conhecimento, você subutiliza a ferramenta mais poderosa da plataforma.
Conceitos-chave
🚀 O gatilho: de "workflow" a ultracode
A palavra mágica mudou. Durante muito tempo, o prompt-padrão para ativar orquestração massiva era
workflow. Com as versões mais recentes do
Claude Code, o gatilho recomendado virou ultracode.
O comportamento é o mesmo — mas o token mudou. Saber isso evita frustração quando você segue tutoriais antigos.
O que é
ultracode é uma instrução ao orquestrador
para usar a máxima capacidade paralela disponível. Quando você inclui esse token no prompt, o maestro sabe que
pode (e deve) disparar o maior número de subagentes necessário, sem contenção artificial.
Por que aprender
O token certo muda a estratégia de execução do modelo. Sem ele, o Claude pode optar por processar em sequência ou com menos agentes. Com ele, você declara explicitamente: "use orquestração massiva aqui". É o interruptor entre modo normal e modo de escala total.
Conceitos-chave
ultracode
workflow
📈 Escala: dezenas e centenas de agentes
O Claude Code foi projetado para suportar orquestração em escala real. Não estamos falando de 3 a 5 subagentes — estamos falando de dezenas a centenas rodando em paralelo. Cada subagente tem sua própria sessão, usa tokens independentes, e pode ser um modelo diferente do orquestrador.
O que é
A plataforma não impõe limite rígido de subagentes por workflow. O limite prático é a sua conta de API (rate limits), o orçamento disponível e a capacidade de consolidar os resultados sem explodir o contexto do orquestrador. Jobs com 40+ agentes simultâneos são comuns em cenários de auditoria massiva.
Por que aprender
Saber a escala possível muda sua arquitetura de prompt. Se você não sabe que pode disparar 100 agentes, vai continuar projetando soluções sequenciais para problemas paralelizáveis. Conhecer o teto real permite projetar workflows corretos desde o início.
Conceitos-chave
💸 Custo e limite de sessão
Workflows dinâmicos são caros por design. Cada subagente consome tokens independentemente — e o custo de um workflow com 200 agentes é aproximadamente 200× o custo de um único agente rodando a mesma tarefa. Além do custo financeiro, há o limite de sessão: o orquestrador ainda precisa de contexto suficiente para ler todos os relatórios de volta.
O que é
O custo de um workflow é a soma dos tokens de cada subagente mais os tokens do orquestrador ao consolidar. O orquestrador precisa de contexto para receber os relatórios — se cada agente devolver 500 tokens e você tiver 200 agentes, isso são 100 000 tokens apenas nos relatórios, antes de qualquer análise.
Por que aprender
Planejar o custo antes de executar evita surpresas. Um workflow mal dimensionado pode consumir o orçamento mensal inteiro em minutos. Entender a estrutura de custo permite decidir: vale usar Haiku nos subagentes? Vale pedir resumos ultra-curtos? Vale subdividir em lotes menores?
Conceitos-chave
- • Usar Haiku nos subagentes quando possível
- • Pedir resumo curto (não dump bruto)
- • Processar em lotes de 20–40 por vez
- • Testar com 5 itens antes de escalar
- • Pedir output longo de cada agente
- • Usar Opus em todos os subagentes
- • Disparar 200 agentes sem testar antes
- • Ignorar o custo de consolidação
🔬 O caso real: 41 e 210 subagentes
Dois números viraram referência na comunidade Claude Code para workflows em escala real: 41 subagentes (caso de auditoria de codebase) e 210 subagentes (processamento de documento massivo). Esses não são limites da ferramenta — são casos documentados que provam que a arquitetura suporta escala sem falhas estruturais.
O que é
Cada subagente analisou um módulo diferente. O orquestrador consolidou os achados em um único relatório de segurança.
Cada subagente processou uma seção de um documento grande. Fan-out completo em uma única chamada ao orquestrador.
Por que aprender
Esses casos provam que workflows dinâmicos não são teoria — são prática. Eles também definem uma régua de escala: se seu problema tem menos de 40 itens paralelos, você está bem dentro do conforto. Se tem mais de 100, precisa de planejamento de custo explícito.
Conceitos-chave
✅ Quando vale usar workflows dinâmicos
Não é todo job paralelo que precisa de workflow dinâmico. A regra prática: se o processamento de cada item é independente, a lista tem mais de 10 itens e o contexto explodiria processando em sequência — aí workflows dinâmicos são a escolha certa.
O que é
O critério de decisão tem três dimensões: independência (os itens não dependem uns dos outros), volume (lista longa o suficiente para justificar overhead de orquestração) e risco de contexto (processar tudo no maestro explodiria a janela de contexto).
Por que aprender
O erro mais comum é usar workflow para tudo — incluindo jobs pequenos onde a sequência seria mais eficiente e mais barata. Aprender o critério correto evita desperdício de tokens e complexidade desnecessária.
Conceitos-chave
- • Revisar 20+ arquivos de código
- • Processar seções de documento longo
- • Gerar relatório para N repositórios
- • Analisar N contratos em paralelo
- • Traduzir N páginas simultaneamente
- • Job com 2–3 itens (sequência basta)
- • Itens que dependem uns dos outros
- • Quando custo supera o ganho de tempo
- • Tarefas criativas que precisam de coerência
- • Pipeline com estado compartilhado
⚠️ Cuidados: o que pode dar errado
Orquestração massiva traz riscos que não existem em jobs simples. Os três mais críticos: explosão de contexto no consolidador, custo inesperado e falhas silenciosas — um subagente que retorna vazio sem avisar.
O que é
Cada risco tem uma causa específica: o orquestrador recebe relatórios grandes demais (explosão de contexto); o modelo não tem visão prévia do custo total antes de executar (surpresa financeira); um subagente trava ou retorna erro silencioso, contaminando o consolidado sem que o orquestrador perceba.
Por que aprender
Workflows que falham silenciosamente são os mais perigosos — o orquestrador entrega um relatório incompleto sem sinalizar que 3 dos 40 subagentes não retornaram nada. Saber o risco permite adicionar instruções explícitas de validação no prompt do orquestrador.
Conceitos-chave: mitigações
Exemplo conceitual
Abaixo, o padrão mental de um workflow para processar 15 capítulos de um livro técnico em paralelo. Note como o orquestrador não precisa ler os 15 capítulos — cada agente lê o seu, e devolve apenas o essencial.
ORQUESTRADOR recebe: lista de 15 capítulos
PARA CADA capítulo em paralelo (ultracode):
SUBAGENTE recebe: "Leia capitulo_X.md e me traga:
1. Tese central (1 frase)
2. Principais conceitos (3 bullets)
3. Pontos confusos para revisão (máx 2)
Resposta: máx 100 tokens."
ORQUESTRADOR consolida: 15 resumos → relatório final
→ identifica capítulos com mais pontos confusos
→ sugere ordem de revisão prioritáriaChave do design: cada subagente retorna máximo 100 tokens. Com 15 agentes, o orquestrador recebe ~1 500 tokens de input — gerenciável. Sem esse limite, 15 capítulos longos poderiam devolver 50 000 tokens e explodir o contexto.
Prompts prontos (copie e cole)
Três prompts para ativar workflows dinâmicos com controle de custo. Em todos, repare no padrão: declare o volume, limite o output de cada agente e peça validação no consolidado.
Use ultracode para auditar os arquivos em src/.
Para cada arquivo, abra um subagente com Haiku.
Cada subagente deve retornar APENAS:
- Arquivo: nome
- Problemas: lista de até 3 items
- Severidade: baixa/média/alta
Máximo 80 tokens por resposta.
Ao final, consolide quantos arquivos retornaram
vazio e liste os de severidade alta primeiro.Tenho 80 contratos em /docs/contratos/.
ANTES de rodar, estime quantos subagentes serão
criados e o custo aproximado se cada agente usar
~2 000 tokens.
Se aprovado, use ultracode: abra um subagente por
contrato, extraia só: partes, valor total, cláusula
de rescisão. Resposta máx 60 tokens cada.
Relatório final: tabela resumida.Tenho 200 URLs em urls.txt. Processe em LOTES
de 20 URLs por vez (não todas de uma vez).
Cada lote: use ultracode, abra 20 subagentes em
paralelo, cada um faz: título + resumo em 2 linhas.
Após cada lote, mostre progresso (lote X/10 concluído).
Ao final, consolide tudo em uma lista numerada.Tela simulada: workflow rodando 6 subagentes
Assim aparece um workflow de auditoria no terminal do Claude Code: o orquestrador disparou 6 agentes simultâneos, cada um em sua própria sessão. A status line do orquestrador mostra apenas ~8% do contexto usado — o trabalho pesado ficou nos subagentes.
Exercício: workflow ou sequência?
Para cada cenário abaixo, decida: workflow dinâmico ou processamento sequencial? Justifique com base nos três critérios: independência, volume e risco de contexto.
Revisar 3 arquivos de configuração para verificar se há variáveis de ambiente expostas.
Dica: pense no volume e no overhead de orquestração.
Gerar um resumo de 50 artigos científicos para um survey de literatura. Cada artigo tem ~10 000 palavras.
Dica: o que acontece com o contexto se você processar em sequência?
Refatorar um módulo grande em etapas: primeiro extrair classes, depois renomear variáveis, depois adicionar testes.
Dica: pense na dependência entre as etapas.
Critério de avaliação
A — Sequencial: apenas 3 arquivos, overhead de workflow não se justifica. Custo e complexidade superam o benefício de paralelismo.
B — Workflow dinâmico: 50 artigos independentes, cada um com 10k palavras. Processar em sequência explodiria o contexto. Fan-out de 50 agentes com resumo curto é a solução correta.
C — Sequencial: as etapas são dependentes (não dá para renomear antes de extrair). Paralelismo não se aplica a pipelines com dependência de estado.
✅ Resumo do módulo
- ▸ Workflow dinâmico = orquestrador dispara N subagentes com base no input — N determinado em tempo de execução.
- ▸ O token gatilho atual é
ultracode(era "workflow" nas versões antigas). - ▸ A plataforma suporta dezenas a centenas de agentes simultâneos — o limite prático é o orçamento.
- ▸ Custo = soma dos tokens de todos os subagentes + consolidação. Calcule antes de executar.
- ▸ Casos de referência: 41 agentes (auditoria) e 210 agentes (processamento de documento).
- ▸ Use quando: itens independentes + volume alto + risco de contexto em sequência.
- ▸ Mitigações: output curto por agente, teste com lote pequeno, validação no consolidador.