Claude Code Dynamic Workflows: Como Orquestrar 1.000 Subagentes Num Codebase Real

Os dynamic workflows do Claude Code são um sistema de orquestração multi-agente onde o Claude escreve um script JavaScript que distribui o trabalho por até 1.000 subagentes em paralelo, mantém todos os resultados intermédios em variáveis do script em vez da janela de contexto do modelo, e devolve à tua sessão apenas a resposta final já verificada. Lançados a 28 de maio de 2026, em conjunto com o Claude Opus 4.8, exigem a CLI v2.1.154 ou superior.

Este post cobre a arquitetura, os seis primitivos do script, casos de uso reais, contas honestas sobre custos e as armadilhas com que os programadores se têm deparado nas primeiras semanas da research preview.

Índice

1. O Que É o Sistema de Dynamic Workflows do Claude Code?
2. Como Funcionam os Workflows do Claude Code: Arquitetura
3. Casos de Uso Reais para os Workflows do Claude Code
4. Custos, Limites e Eficiência dos Workflows do Claude Code
5. Avisos e Armadilhas Que os Programadores Encontram
6. Workflows do Claude Code vs LangGraph, Temporal e Outros
7. Boas Práticas para os Workflows do Claude Code
8. Perguntas Frequentes

O Que É o Sistema de Dynamic Workflows do Claude Code?

Antes dos dynamic workflows do Claude Code, cada subagente que o Claude despachava devolvia o seu resultado para a janela de contexto da conversa principal. Isto significava que uma execução de 50 agentes acumulava 50 blocos de texto intermédio, o contexto enchia-se e a qualidade degradava-se muito antes de a tarefa terminar. O limite de agentes não era propriamente um limite rígido, mas sim uma barreira suave onde o modelo ficava sem memória de trabalho útil.

Os dynamic workflows resolvem isto retirando a orquestração da conversa por completo. O Claude escreve um script JavaScript para a tarefa específica que lhe deres. Esse script corre num runtime em segundo plano. A lógica de orquestração (que agentes lançar, quantos, por que ordem, quando verificar) vive em variáveis do script. A janela de contexto do modelo só recebe o resultado final sintetizado.

Os seis primitivos disponíveis num script de workflow:

• agent(prompt, opts?) — lança um único subagente e devolve o seu texto final ou JSON validado
• parallel(thunks) — corre um array de tarefas em simultâneo, com uma barreira de sincronização
• pipeline(items, ...stages) — faz fluir os itens pelas várias etapas sem barreira entre elas
• workflow(nameOrRef, args?) — invoca um workflow guardado como sub-passo (no máximo um nível de aninhamento)
• phase(title) — dá nome a um grupo de progresso no painel de monitorização /workflows
• log(msg) — emite uma linha narrada na saída do workflow

A palavra "dynamic" tem aqui um significado específico. O Claude decide a decomposição da tarefa, o número de agentes, a estratégia de fases e a abordagem de verificação em tempo real, para a tarefa concreta que descreveste. Não há dois scripts de workflow iguais. Isto é diferente das Routines (que são prompts agendados estaticamente, que defines uma vez) e diferente do antigo primitivo ScheduleWakeup usado nas sessões /loop.

Esta é a estrutura mínima de um script de workflow válido:

export const meta = {
  name: 'security-audit',
  description: 'Parallel security scan across auth, DB, and input layers',
  whenToUse: 'When you need a full security sweep before shipping',
  phases: [
    { title: 'Scan', detail: 'Three specialized agents run in parallel' },
    { title: 'Synthesize', detail: 'One agent compiles a prioritized report' },
  ]
}

phase('Scan')
const [auth, db, input] = await parallel([
  () => agent('Audit authentication flows for bypass vulnerabilities', { label: 'auth-scanner' }),
  () => agent('Check all database queries for injection risks', { label: 'db-scanner' }),
  () => agent('Review input validation and sanitization', { label: 'input-scanner' }),
])

phase('Synthesize')
const report = await agent(
  `Compile a prioritized security report from these three findings:\n\nAuth: ${auth}\n\nDB: ${db}\n\nInput: ${input}`,
  { label: 'synthesizer' }
)

return report

Como Funcionam os Workflows do Claude Code: Arquitetura

Quando despoletas um workflow, esta é a sequência de eventos:

Passo 1: Planeamento. O Claude analisa o teu pedido e escreve um script de orquestração em JavaScript. O script codifica que fases existem, quantos agentes correm em cada fase, se os itens fluem em paralelo ou por um pipeline, e que lógica de verificação corre antes de devolver os resultados.

Passo 2: Aprovação. Vês as fases planeadas a partir do array meta.phases. Podes correr o workflow, marcá-lo como confiável para este projeto (para nunca mais perguntar), abrir o script JS em bruto com Ctrl+G para o inspecionar, ou cancelar.

Passo 3: Execução. O runtime do workflow corre o script num processo em segundo plano. Os subagentes fazem a leitura de ficheiros, os comandos de shell, os pedidos à web e as chamadas a ferramentas MCP. Cada chamada agent() devolve o seu resultado como um valor JavaScript (uma string, ou JSON validado se tiveres passado um schema). Esses valores acumulam-se em variáveis do script, não no contexto do Claude.

Passo 4: Verificação. A maioria dos workflows gerados pelo Claude inclui uma fase de verificação onde agentes separados tentam refutar ou pôr em causa as conclusões da fase principal. O workflow itera até os resultados convergirem.

Passo 5: Entrega. O valor de retorno do script, a resposta final sintetizada, aterra na tua sessão. É a única coisa que toca na janela de contexto do Claude.

Retoma e cache. O runtime regista no journal o resultado de cada chamada agent() concluída. Se pausares um workflow com a tecla p no painel /workflows, os agentes já concluídos devolvem os seus resultados em cache instantaneamente ao retomar. Isto só funciona dentro da mesma sessão do Claude Code: se fechares a aplicação, o journal é descartado e a sessão seguinte começa do zero.

A cache de prompts e as implicações nos custos. A cache de prompts da Anthropic tem, por omissão, um TTL de 5 minutos. Qualquer chamada agent() que dispare mais de 300 segundos depois da anterior falha a cache por completo, despoletando uma reescrita total a 12,5x o custo de uma leitura de cache. Para workflows com intervalos entre fases superiores a cinco minutos, pede explicitamente a extensão do TTL para 1 hora através de cache_control: { type: 'ephemeral', ttl: '1h' } na configuração inicial. Isto custa 2x o preço de escrita da cache, mas torna os workflows longos muito mais baratos.

O painel de monitorização /workflows (escreve /workflows para o abrir) mostra as fases, a contagem de agentes ativos, os totais de tokens e o tempo decorrido. Navegação: setas para cima/baixo para selecionar fases ou agentes, p para pausar ou retomar, x para parar um agente ou o workflow inteiro, r para reiniciar um agente selecionado, s para guardar a execução como um comando reutilizável.

Casos de Uso Reais para os Workflows do Claude Code

1. Code review em paralelo num PR grande. Divide os ficheiros alterados em lotes, corre um agente por lote para verificar a lógica, os tipos, a segurança e os testes, e depois sintetiza as conclusões num review priorizado. Um programador lançou 90 agentes num único code review com este padrão e atingiu os limites mensais de tokens — sinal de que o padrão funciona, mas precisa de proteções de orçamento.

2. Migração ou reescrita em larga escala. O exemplo canónico é o projeto Bun do Jarred Sumner: cerca de 750.000 linhas de Zig portadas para Rust em 11 dias, com 99,8% da suite de testes existente a passar do primeiro commit ao merge. O padrão é um documento de mapeamento de 600 linhas (cada tipo e idioma de Zig traduzido para o seu equivalente em Rust) mais agentes em paralelo a processar conjuntos de ficheiros que não se sobrepõem, com isolamento por worktree para poderem escrever sem colisões.

3. Auditoria de segurança com verificação cruzada adversarial. Um orquestrador lança três scanners especializados (fluxos de autenticação, queries à base de dados, validação de input) em paralelo, e depois um agente de verificação separado tenta encontrar falsos positivos em cada conclusão antes de compilar um relatório priorizado. A fase de verificação adversarial integrada é o que torna este padrão fiável o suficiente para auditorias antes de pôr em produção.

4. Estrutura de investigação multi-fonte. O comando integrado /deep-research é, ele próprio, um workflow que demonstra o padrão de distribuição: nove agentes recolhem dados de fontes diferentes em simultâneo, as conclusões intermédias reduzem-se a candidatos ordenados, e um agente de síntese compila o relatório final. O mesmo padrão serve para análise competitiva, auditorias de dependências ou resumo de changelogs num monorepo.

5. Geração de testes em escala. Distribui por todos os módulos de um codebase, com um agente por módulo a escrever testes contra a superfície da API pública, e depois uma fase de convergência verifica sobreposições de cobertura e remove duplicados antes de escrever os ficheiros de teste finais. A opção isolation: 'worktree' em agent() impede que os agentes em paralelo criem conflitos de ficheiros.

Custos, Limites e Eficiência dos Workflows do Claude Code

Limites rígidos (impostos pelo runtime, não negociáveis):

Preço dos tokens (pay-as-you-go):

• Claude Opus 4.8: $5 input / $25 output por milhão de tokens
• Claude Sonnet 4.6: $3 input / $15 output por milhão de tokens
• Leituras de cache: ~10% do preço de input. Escritas de cache: ~25% do preço de input (quando tudo funciona bem).

Contas de custo num workflow real. Uma auditoria de segurança em paralelo com três agentes Sonnet 4.6, a 8.000 tokens de input cada e 2.000 tokens de output cada, custa aproximadamente: (3 × 8.000 × $3/M) + (3 × 2.000 × $15/M) = $0,072 + $0,090 = $0,162. Troca-os por Opus 4.8 e a mesma execução custa $0,42. Correr 90 desses agentes num review de um codebase grande, a preços de Opus, chega a $12,60 só em tokens de output, antes de qualquer overhead — o que explica como um programador consegue esgotar os limites mensais numa única sessão.

Quando os workflows são rentáveis vs. desperdício:

Rentáveis:

• Tarefas em que o paralelismo reduz o tempo real (precisas do resultado depressa, o custo é secundário)
• Migrações grandes onde a execução sequencial demoraria dias
• Tarefas com fronteiras de subtarefa claras e sem dependências entre agentes a meio da execução

Desperdício:

• Edições de rotina num único ficheiro (uma conversa normal é mais rápida e mais barata)
• Tarefas que exigem orientação em tempo real ou ajustes a meio (os workflows correm sem supervisão)
• Pedidos exploratórios ou ambíguos em que a estratégia de decomposição é desconhecida

O precipício da cache aos 5 minutos. Se o teu workflow tiver fases separadas por mais de 300 segundos, cada agente da fase posterior paga o custo total de escrita da cache em vez das leituras baratas. Numa execução de 50 agentes com um orquestrador Opus, isto pode inflacionar os custos 3x a 6x face a uma execução bem cacheada. Passa a flag de TTL de 1 hora no contexto inicial para evitar isto.

Loops com noção do orçamento. A variável global budget nos scripts de workflow expõe o alvo de tokens definido no arranque. Protege sempre os loops sensíveis ao orçamento: if (budget.total && tokensUsed > budget.total * 0.8) break. Sem proteção, os loops correm até ao limite rígido de 1.000 agentes.

Avisos e Armadilhas Que os Programadores Encontram

Os scripts de workflow são JavaScript, não TypeScript. O runtime não tem camada de transpilação de TypeScript. Adicionar anotações de tipo a um script de workflow provoca um erro de parsing. Se quiseres orquestração tipada, escreve um wrapper em TypeScript que chame o workflow em runtime; não metas tipos no próprio script.

Três built-ins não-determinísticos lançam erro dentro dos scripts de workflow. Date.now(), Math.random() e new Date() sem argumentos estão proibidos. A razão é que a cache de retoma regista no journal cada chamada agent() pela sua chave determinística. Valores não-determinísticos gerariam chaves diferentes a cada nova execução, partindo a retoma. Soluções: passa os timestamps via args no arranque, varia os prompts pelo índice do loop em vez de por um valor aleatório.

Sem acesso direto ao sistema de ficheiros ou à shell no script. A camada de orquestração não consegue ler ficheiros nem correr comandos. Todo o I/O passa pelos subagentes. O script é uma camada de coordenação pura.

Confusão entre parallel() e pipeline(). O parallel() é uma barreira de sincronização: espera por cada thunk antes de devolver. O pipeline() não tem barreira: o item A pode estar na etapa 3 enquanto o item B ainda está na etapa 1. Por omissão, usa pipeline() para processamento de itens independentes. Usa parallel() apenas quando uma etapa a jusante precisa do conjunto completo de todos os resultados anteriores de uma só vez (deduplicação, ordenação cruzada, review adversarial do conjunto inteiro). Um thunk que falha dentro de parallel() resolve para null em vez de rejeitar, por isso faz sempre .filter(Boolean) ao array de resultados.

O modo acceptEdits aplica alterações de ficheiros automaticamente. Os subagentes que correm dentro de um workflow operam em modo acceptEdits por omissão. As edições de ficheiros aplicam-se sem prompts de revisão individuais. Numa execução de 50 agentes a mexer em centenas de ficheiros, isto significa que entram alterações não revistas em escala. Revê o script de workflow gerado (Ctrl+G no prompt de aprovação) antes de correr em branches de produção.

Quando não usar dynamic workflows:

• Qualquer tarefa onde precises de orientar ou ajustar a meio da execução
• Debugging exploratório em que o passo seguinte depende do que acabaste de ver
• Tarefas que exigem uma única resposta focada em menos de 10 minutos
• Ambientes sensíveis ao custo sem proteções de orçamento por execução

O bug do scope de push em .github/workflows/. Se um subagente editar ficheiros em .github/workflows/, a edição é bem-sucedida localmente mas falha no momento do push, porque a credencial OAuth do Claude Code não tem o scope workflow. O erro surge depois de já se ter gasto todo o orçamento da sessão. Verifica no script de workflow se há escritas em .github/workflows/ antes de aprovar.

Workflows do Claude Code vs LangGraph, Temporal e Outros

Estas ferramentas ocupam camadas diferentes da stack e não são intermutáveis. A pergunta certa é qual a camada que estás a resolver.

Claude Code vs LangGraph. Não são concorrentes. O Claude Code é uma ferramenta de tempo de desenvolvimento. O LangGraph é uma framework de aplicação em runtime para workflows com estado que correm em produção. Usa o Claude Code para construir aplicações LangGraph. A restrição importante: o Claude Code está preso aos modelos Claude da Anthropic. O LangGraph é agnóstico ao modelo, via integrações LangChain.

Claude Code vs Temporal. O Temporal envolve qualquer execução (incluindo agentes movidos a Claude) numa durabilidade à prova de crashes. O Claude Code não tem persistência de estado entre sessões, não tem semântica exactly-once, nem histórico de execução auditável. Se o teu agente mexe em dinheiro, registos legais ou qualquer operação irreversível, o Temporal tem lugar na stack.

A arquitetura complementar para agentes de IA em produção: o Claude Agent SDK trata do raciocínio da IA e do loop de uso de ferramentas. O Temporal envolve-o para tolerância a falhas. Tanto o OpenAI Codex como o Replit Agent 3 escolheram esta divisão.

Boas Práticas para os Workflows do Claude Code

Por omissão, usa pipeline(), não parallel(). O pipeline() começa a processar o item N+1 assim que o item N termina a primeira etapa, eliminando intervalos parados. Só recorre ao parallel() quando uma etapa precisa genuinamente de todos os resultados anteriores de uma só vez.

Usa schema para output estruturado sempre que precisares de fazer parsing dos resultados dos agentes. Passar um JSON Schema ao agent() força o subagente a uma chamada de ferramenta com output estruturado e retry automático em caso de incompatibilidade. Isto tira o parsing de texto frágil da tua lógica de orquestração.

Define o TTL de cache de 1 hora em workflows longos. Para execuções com fases separadas por mais do que uns minutos, o TTL de cache de 5 minutos por omissão vai custar-te 3x a 6x mais do que o necessário. A flag de TTL de 1 hora custa 2x o preço de escrita mas poupa muito mais nas leituras em execuções multi-fase.

Protege os loops sensíveis ao orçamento. Todos os loops infinitos-até-convergir deviam verificar budget.total antes de iterar: if (budget.total && estimatedTokensUsed > budget.total * 0.8) { log('approaching budget, stopping early'); break }. Sem isto, o loop corre até ao limite de 1.000 agentes.

Usa phase() e log() com generosidade. Fases bem rotuladas e linhas narradas no painel /workflows tornam possível pausar uma execução que está a descarrilar antes de terminar. Um workflow sem rótulos de fase é uma caixa preta até acabar.

Usa isolation: 'worktree' apenas quando os agentes escrevem genuinamente nos mesmos ficheiros. O isolamento por worktree cria uma worktree git separada por agente, o que está correto para tarefas de escrita de ficheiros em paralelo mas acrescenta um overhead que não precisas em agentes só de leitura.

Guarda os workflows que funcionam. Carrega em s no painel /workflows numa execução concluída e guarda em .claude/workflows/ (partilhado no projeto) ou ~/.claude/workflows/ (pessoal). Um workflow que guardas uma vez torna-se um /command usável em todas as execuções futuras com o mesmo padrão.

Perguntas Frequentes

Quantos agentes consegue o Claude Code correr em paralelo?

Os dynamic workflows do Claude Code limitam a execução concorrente a 16 agentes a correr em simultâneo. A contagem total de agentes ao longo de uma execução inteira está limitada a 1.000. Estes limites são impostos pelo runtime do workflow, independentemente do teu plano de subscrição. O limite de concorrência pode ser inferior em máquinas com poucos núcleos de CPU.

Como despoleto um dynamic workflow do Claude Code?

De três formas: inclui a palavra "workflow" em qualquer ponto de um prompt (o Claude Code destaca a palavra-chave e escreve um script de orquestração), corre o comando /deep-research, ou define /effort ultracode, que planeia automaticamente um workflow para cada tarefa de fundo na sessão. Carrega em alt+w para suprimir o gatilho da palavra-chave num único prompt, sem desativar a funcionalidade globalmente.

Os dynamic workflows estão disponíveis no plano free ou Pro?

Os dynamic workflows estão desativados por omissão no Pro ($20/mês) e têm de ser ativados manualmente via /config. Estão ativados por omissão no Max (escalões de $100/mês e $200/mês) e nos planos Team. Nos planos Enterprise estão desativados por omissão e exigem ativação por um administrador. Todos os planos exigem a CLI v2.1.154 ou superior.

Em que é que o Claude Code é diferente do Cursor para workflows de agentes?

O Claude Code é uma ferramenta agêntica nativa do terminal, desenhada para orquestração multi-agente de longa duração em todo um codebase. Tem Hooks, integrações MCP, Skills, dynamic workflows, e opera inteiramente a partir da linha de comandos, com acesso total ao sistema de ficheiros e à shell. O Cursor está integrado no IDE e otimizado para edição rápida de ficheiros individuais dentro do VS Code. Para edição diária de código num IDE, o Cursor ganha em ergonomia. Para migrações em todo o repo, auditorias de segurança ou builds multi-agente, o sistema de workflows do Claude Code não tem equivalente direto no Cursor.

Para que tarefas reais já foram usados os dynamic workflows do Claude Code?

O exemplo mais citado é a reescrita de Zig para Rust do Bun: cerca de 750.000 linhas portadas em 11 dias, com 99,8% da suite de testes a passar em Linux x64 (PR #30412, mergeado a 14 de maio de 2026). A Rakuten reduziu a entrega de funcionalidades de 24 dias úteis para 5 dias usando sessões do Claude Code em paralelo. A Uber atingiu 84% de adoção do Claude Code em cerca de 5.000 engenheiros, com aproximadamente 70% do código submetido originado por IA em março de 2026.

Para Concluir

Os dynamic workflows do Claude Code deslocam a orquestração da janela de contexto do modelo para um runtime JavaScript, e é essa a mudança estrutural que torna viáveis execuções de 500 e 1.000 agentes sem degradação de qualidade. Os primitivos são pequenos e combináveis. Os custos são reais e exigem proteções. As armadilhas (scripts só em JS, built-ins não-determinísticos proibidos, a aplicação automática do acceptEdits, o precipício da cache aos 5 minutos) são específicas o suficiente para se contornarem, assim que as conheces.

Começa por um caso de uso bem delimitado: um code review em paralelo, uma varredura de documentação ao longo da fronteira de um módulo, ou uma auditoria de segurança numa superfície bem definida. Guarda a execução como um comando. Itera o script. Os workflows que funcionam de forma fiável são aqueles que refinas ao longo de várias execuções, não aqueles que disparas contra uma tarefa de codebase inteiro logo no primeiro dia.

Publicado por @speedy_devv