Orquestre subagentos em escala com fluxos de trabalho dinâmicos
Fluxos de trabalho dinâmicos orquestram muitos subagentos a partir de um script que Claude escreve e você pode executar novamente. Use-os para auditorias de base de código, grandes migrações e pesquisa com verificação cruzada.
{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}
Um fluxo de trabalho dinâmico é um script JavaScript que orquestra subagentos em escala. Claude escreve o script para a tarefa que você descreve, e um runtime o executa em segundo plano enquanto sua sessão permanece responsiva.
Recorra a um fluxo de trabalho quando uma tarefa precisar de mais agentes do que uma conversa pode coordenar, ou quando você quiser que a orquestração seja codificada como um script que você possa ler e executar novamente. Os exemplos incluem uma varredura de bugs em toda a base de código, uma migração de 500 arquivos, uma pergunta de pesquisa que precisa ter fontes verificadas cruzadamente uma contra a outra, e um plano difícil que vale a pena ser elaborado de vários ângulos independentes antes de você se comprometer com um.
Esta página cobre como:
- Decidir quando usar um fluxo de trabalho em vez de subagentos ou skills
- Executar um fluxo de trabalho agrupado com
/deep-research - Fazer Claude escrever um fluxo de trabalho para sua tarefa e salvá-lo
- Entender como um fluxo de trabalho é executado e gerenciar execuções
Quando usar um fluxo de trabalho
Subagentos, skills, equipes de agentes e fluxos de trabalho podem todos executar uma tarefa com várias etapas. A diferença é quem mantém o plano:
| Subagentos | Skills | Equipes de agentes | Fluxos de trabalho | |
|---|---|---|---|---|
| O que é | Um worker Claude que spawna | Instruções que Claude segue | Um agente líder supervisionando sessões entre pares | Um script que o runtime executa |
| Quem decide o que é executado a seguir | Claude, turno por turno | Claude, seguindo o prompt | O agente líder, turno por turno | O script |
| Onde os resultados intermediários vivem | Janela de contexto de Claude | Janela de contexto de Claude | Uma lista de tarefas compartilhada | Variáveis de script |
| O que é repetível | A definição do worker | As instruções | A definição da equipe | A orquestração em si |
| Escala | Algumas tarefas delegadas por turno | Igual aos subagentos | Um punhado de pares de longa duração | Dezenas a centenas de agentes por execução |
| Interrupção | Reinicia o turno | Reinicia o turno | Os companheiros de equipe continuam executando | Retomável na mesma sessão |
Um fluxo de trabalho move o plano para o código. Com subagentos, skills e equipes de agentes, Claude é o orquestrador: ele decide turno por turno o que spawnar ou atribuir a seguir, e cada resultado chega à janela de contexto. Um script de fluxo de trabalho mantém o loop, a ramificação e os resultados intermediários em si, então o contexto de Claude contém apenas a resposta final.
Mover o plano para o código também permite que um fluxo de trabalho aplique um padrão de qualidade repetível, não apenas execute mais agentes: ele pode ter agentes independentes revisando adversarialmente as descobertas um do outro antes de serem relatadas, ou elaborar um plano de vários ângulos e pesá-los um contra o outro, para que você obtenha um resultado mais confiável do que uma única passagem.
Executar um fluxo de trabalho agrupado
A maneira mais rápida de ver um fluxo de trabalho em ação é executar /deep-research, o fluxo de trabalho integrado que Claude Code inclui para investigar uma pergunta em muitas fontes. Você verá agentes trabalhando através de um conjunto de fases em segundo plano enquanto sua sessão permanece livre, e obterá um relatório no final em vez de uma transcrição turno por turno.
Executar o fluxo de trabalho
Execute /deep-research com uma pergunta que você deseja investigar. Ele distribui buscas na web em vários ângulos, busca e verifica cruzadamente as fontes que encontra, e sintetiza um relatório citado.
/deep-research What changed in the Node.js permission model between v20 and v22?
Permitir fluxos de trabalho
Claude Code pergunta se deve permitir o fluxo de trabalho. Selecione Sim para continuar. O prompt exato depende do seu modo de permissão. Consulte Aprovar o plano antes de ser executado para as opções por modo.
Observar o progresso
A execução começa em segundo plano. Execute /workflows, use as setas para selecionar a execução e pressione Enter para abrir sua visualização de progresso:
/workflows
A visualização mostra cada fase com sua contagem de agentes, total de tokens e tempo decorrido. Aprofunde-se em qualquer fase para ver seus agentes e o que cada um encontrou. Consulte Observar a execução para o conjunto completo de controles.
Você também pode observar no painel de tarefas abaixo da caixa de entrada: um resumo de progresso de uma linha aparece lá enquanto a execução está em andamento. Pressione a seta para baixo para focá-lo e depois Enter para expandir.
Ler o relatório
Quando a execução termina, o relatório chega em sua sessão. Ele cita as fontes de cada afirmação, com afirmações que não sobreviveram à verificação cruzada já filtradas.
Para executar um fluxo de trabalho para sua própria tarefa, faça Claude escrever um, e uma vez que uma execução faça o que você queria, você pode salvá-lo como um comando seu.
Fluxos de trabalho agrupados
Claude Code inclui /deep-research como um fluxo de trabalho integrado:
| Comando | O que faz |
|---|---|
/deep-research <question> |
Distribui buscas na web em uma pergunta em vários ângulos, busca e verifica cruzadamente as fontes que encontra, vota em cada afirmação e retorna um relatório citado com afirmações que não sobreviveram à verificação cruzada filtradas. Requer que a ferramenta WebSearch esteja disponível |
Fluxos de trabalho que você salva você mesmo se tornam comandos da mesma forma e aparecem no autocomplete / junto com os agrupados.
Observar a execução
Fluxos de trabalho são executados em segundo plano, então a sessão permanece responsiva enquanto os agentes trabalham. Execute /workflows a qualquer momento para listar fluxos de trabalho em execução e concluídos, depois selecione um para abrir sua visualização de progresso.
/workflows
A visualização de progresso mostra cada fase com suas contagens de agentes, totais de tokens e tempo decorrido. O rodapé lista a chave para cada ação:
| Chave | Ação |
|---|---|
↑ / ↓ |
Selecionar uma fase ou agente |
Enter ou → |
Aprofundar-se na fase selecionada, depois em um agente para ler seu prompt, chamadas de ferramentas recentes e resultado |
Esc |
Voltar um nível |
j / k |
Rolar dentro do detalhe do agente quando transborda |
p |
Pausar ou retomar a execução |
x |
Parar o agente selecionado, ou parar todo o fluxo de trabalho quando o foco está na execução |
r |
Reiniciar o agente em execução selecionado |
s |
Salvar o script da execução como um comando |
Fazer Claude escrever um fluxo de trabalho
Você pode fazer Claude escrever um fluxo de trabalho para sua tarefa de duas maneiras:
- Peça um fluxo de trabalho em seu prompt, seja com suas próprias palavras ou incluindo a palavra-chave
ultracode, e Claude escreve um para a tarefa. - Deixe Claude decidir com ultracode: defina
/effort ultracodee Claude planeja um fluxo de trabalho para cada tarefa substancial na sessão.
Você também pode executar um comando de fluxo de trabalho que já existe: um fluxo de trabalho agrupado como /deep-research, ou um que você salvou.
Peça um fluxo de trabalho em seu prompt
Para executar uma única tarefa como um fluxo de trabalho sem alterar o nível de esforço da sessão, inclua a palavra-chave ultracode em seu prompt. Pedir com suas próprias palavras, por exemplo "use um fluxo de trabalho" ou "execute um fluxo de trabalho", também funciona: Claude trata uma solicitação direta como o mesmo opt-in. Antes da v2.1.160 a palavra-chave de gatilho literal era workflow; solicitações em linguagem natural funcionam em ambas as versões.
ultracode: audit every API endpoint under src/routes/ for missing auth checks
Claude Code destaca a palavra-chave em sua entrada e Claude escreve um script de fluxo de trabalho para a tarefa em vez de trabalhar através dela turno por turno. Se você não pretendia iniciar um fluxo de trabalho, pressione Option+W no macOS ou Alt+W no Windows e Linux para descartar o destaque para este prompt, ou pressione backspace enquanto o cursor está logo após a palavra-chave destacada. Para impedir que a palavra-chave dispare, desative o gatilho de palavra-chave Ultracode em /config.
Se a execução fez o que você queria, você pode salvá-la como um comando depois.
Se você já tem um orquestrador construído de outra forma, como uma pasta de prompts de subagentos ou uma skill que distribui trabalho, você pode apontar Claude para ele e pedir um fluxo de trabalho que faça a mesma coisa.
Deixe Claude decidir com ultracode
Ultracode é uma configuração de Claude Code que combina xhigh esforço de raciocínio com orquestração automática de fluxo de trabalho. Com ele ativado, Claude planeja um fluxo de trabalho para cada tarefa substancial em vez de esperar você pedir.
/effort ultracode
Com ultracode ativado, Claude decide quando uma tarefa justifica um fluxo de trabalho. Uma única solicitação pode se transformar em vários fluxos de trabalho seguidos: um para entender o código, um para fazer a alteração e um para verificá-la. Isso se aplica a cada tarefa na sessão, então cada solicitação usa mais tokens e leva mais tempo do que em níveis de esforço mais baixos.
Ultracode dura para a sessão atual e é redefinido quando você inicia uma nova. Volte com /effort high quando retornar ao trabalho de rotina. Está disponível em modelos que suportam xhigh esforço; em outros modelos o menu /effort não o oferece.
Aprovar o plano antes de ser executado
Na CLI, o prompt por execução mostra as fases planejadas e estas opções:
- Sim, execute: inicie a execução
- Sim, e não pergunte novamente para
<name>em<path>: inicie e pule este prompt para este fluxo de trabalho neste projeto a partir de agora - Ver script bruto: leia o script antes de decidir
- Não: cancelar
Ctrl+G abre o script em seu editor. Tab permite que você ajuste o prompt antes da execução começar.
Se você vê este prompt depende do seu modo de permissão:
| Modo de permissão | Quando você é solicitado |
|---|---|
| Padrão, aceitar edições | Cada execução, a menos que você tenha selecionado Sim, e não pergunte novamente para esse fluxo de trabalho neste projeto |
| Auto | Apenas no primeiro lançamento. Qualquer Sim registra consentimento em suas configurações de usuário, e lançamentos posteriores começam sem solicitar. Ignorado completamente quando ultracode está ativado |
Contornar permissões, claude -p, Agent SDK |
Nunca. A execução começa imediatamente |
No aplicativo Desktop, um cartão de aprovação mostra o nome do fluxo de trabalho, a lista de fases e um aviso de uso de token, com ações Uma vez, Sempre e Negar. A visualização de progresso aparece no painel de tarefas em segundo plano.
Seu modo de permissão controla apenas o prompt de lançamento acima. Os subagentos que o fluxo de trabalho spawna sempre são executados no modo acceptEdits e herdam sua lista de permissão de ferramentas, independentemente do modo de sua sessão. As edições de arquivo são aprovadas automaticamente.
Comandos shell, buscas na web e ferramentas MCP que não estão em sua lista de permissão ainda podem solicitá-lo durante a execução. Para evitar isso em uma execução longa, adicione os comandos que os agentes precisam à sua lista de permissão antes de começar.
Em claude -p e no Agent SDK não há ninguém para solicitar, então as chamadas de ferramentas seguem suas regras de permissão configuradas sem confirmação interativa.
Salvar o fluxo de trabalho para reutilização
Quando Claude escreve um fluxo de trabalho para uma tarefa que você repetirá, você pode salvar o script dessa execução como um comando. Um processo como uma revisão que você executa em cada branch então executa a mesma orquestração cada vez.
Execute /workflows, selecione a execução que você deseja manter e pressione s. Na caixa de diálogo de salvamento, Tab alterna entre os dois locais de salvamento:
.claude/workflows/em seu projeto: compartilhado com todos que clonam o repositório~/.claude/workflows/em seu diretório inicial: disponível em cada projeto, visível apenas para você
Pressione Enter para salvar. O fluxo de trabalho é executado como /<name> em futuras sessões de qualquer local.
Se um fluxo de trabalho de projeto e um fluxo de trabalho pessoal compartilham um nome, o do projeto é executado.
Passar entrada para um fluxo de trabalho salvo
Um fluxo de trabalho salvo pode aceitar entrada através do parâmetro args. O script o lê como um global nomeado args. Use isso para fornecer uma pergunta de pesquisa, uma lista de caminhos de destino ou um objeto de configuração no momento da invocação em vez de editar o script para cada execução.
O prompt a seguir executa um fluxo de trabalho salvo com uma lista de números de problemas:
> Run /triage-issues on issues 1024, 1025, and 1030
Claude passa a lista como dados estruturados, então o script pode chamar métodos de array e objeto em args diretamente sem analisá-lo primeiro. Se args for omitido, o global é undefined dentro do script.
Como um fluxo de trabalho é executado
O runtime do fluxo de trabalho executa o script em um ambiente isolado, separado de sua conversa. Os resultados intermediários permanecem em variáveis de script em vez de chegar ao contexto de Claude.
Cada execução escreve seu script em um arquivo sob o diretório da sua sessão em ~/.claude/projects/. Claude recebe o caminho quando a execução começa, então você pode pedir por ele. Você pode abrir esse arquivo para ler a orquestração que Claude escreveu, compará-lo com o script de uma execução anterior, ou editá-lo e pedir a Claude para relançar a partir da versão editada.
O runtime rastreia o resultado de cada agente conforme a execução progride, o que é o que torna uma execução retomável dentro da mesma sessão.
Comportamento e limites
O runtime aplica as seguintes restrições:
| Restrição | Por quê |
|---|---|
| Sem entrada do usuário durante a execução | Apenas prompts de permissão de agente podem pausar uma execução. Para aprovação entre estágios, execute cada estágio como seu próprio fluxo de trabalho |
| Sem acesso direto ao sistema de arquivos ou shell do próprio fluxo de trabalho | Agentes leem, escrevem e executam comandos. O script coordena os agentes |
| Até 16 agentes simultâneos, menos em máquinas com núcleos de CPU limitados | Limita o uso de recursos locais |
| 1.000 agentes totais por execução | Previne loops descontrolados |
Gerenciar execuções
Uma vez que uma execução começa, você a gerencia a partir da visualização /workflows, ou expandindo sua linha de progresso no painel de tarefas abaixo da caixa de entrada.
Retomar após uma pausa
Se você parar uma execução, você pode retomá-la: agentes que já foram concluídos retornam seus resultados em cache, e o resto é executado ao vivo. Retome uma execução pausada de /workflows selecionando-a e pressionando p, ou peça a Claude para relançar o fluxo de trabalho com o mesmo script.
Retomar funciona dentro da mesma sessão de Claude Code. Se você sair de Claude Code enquanto um fluxo de trabalho está em execução, a próxima sessão inicia o fluxo de trabalho do zero.
Custo
Um fluxo de trabalho spawna muitos agentes, então uma única execução pode usar significativamente mais tokens do que trabalhar através da mesma tarefa em conversa. As execuções contam para o uso do seu plano e limites de taxa como qualquer outra sessão.
Para avaliar o gasto antes de se comprometer com uma tarefa grande, execute o fluxo de trabalho em um pequeno recorte primeiro: um diretório em vez de todo o repositório, ou uma pergunta estreita em vez de uma ampla. A visualização /workflows mostra o uso de tokens de cada agente conforme a execução progride, e você pode parar a execução lá a qualquer momento sem perder o trabalho concluído. Os limites de agente do runtime limitam quantos agentes uma única execução pode spawnar, o que limita o custo de um script descontrolado.
Cada agente em um fluxo de trabalho usa o modelo de sua sessão a menos que o script rotule um estágio para um diferente. Para controlar o custo do modelo:
- Verifique
/modelantes de uma execução grande se você geralmente muda para um modelo menor para trabalho de rotina - Peça a Claude para usar um modelo menor para estágios que não precisam do mais forte quando você descreve a tarefa
Desativar fluxos de trabalho
Fluxos de trabalho estão disponíveis na CLI, no aplicativo Desktop, nas extensões IDE, modo não interativo com claude -p, e no Agent SDK. As mesmas configurações de desativação se aplicam em cada superfície.
Para desativar fluxos de trabalho para você:
- Alterne Dynamic workflows desativado em
/config. Persiste entre sessões. - Defina
"disableWorkflows": trueem~/.claude/settings.json. Persiste entre sessões. - Defina
CLAUDE_CODE_DISABLE_WORKFLOWS=1. Lido na inicialização, então se aplica onde quer que você o defina.
Para desativar fluxos de trabalho para toda a sua organização, defina "disableWorkflows": true em configurações gerenciadas, ou use o alternador na página configurações de administrador de Claude Code.
Quando fluxos de trabalho estão desativados, os comandos de fluxo de trabalho agrupados não estão disponíveis, a palavra-chave ultracode não dispara mais uma execução, e ultracode é removido do menu /effort.
Recursos relacionados
- Executar agentes em paralelo: comparar subagentos, visualização de agente, equipes de agentes e fluxos de trabalho
- Criar subagentos personalizados: a primitiva de worker que fluxos de trabalho orquestram
- Gerenciar custos: como execuções multi-agente contam para limites de uso