Projetando fluxos de trabalho de agentes: de conversas avulsas à automação de várias etapas · Lição 3 de 6

Lição 3: Decompondo uma tarefa complexa em um fluxo de trabalho

Objetivos de aprendizado:

Dominar as três estratégias de decomposição de tarefas

Identificar dependências entre tarefas

Transformar uma decomposição em um fluxo de trabalho executável

Pré-requisitos: Lição 2: Blocos de construção de um fluxo de trabalho: passos, estado, ramificações e loops | Próxima: Lição 4 >>

De “não sei por onde começar” a passos claros

Uma tarefa cai na sua mesa: “Divida nossa aplicação Rails monolítica em uma arquitetura de microsserviços.” Essa é uma tarefa complexa. Você não sabe por onde começar, quantos passos ela leva nem o que cada passo faz.

Decomposição de tarefas é como você pega uma tarefa vaga e grande demais e a quebra em passos pequenos e claros.¹

Uma boa decomposição atende a três critérios:

Cada subtarefa é pequena o bastante para terminar em uma única chamada de agente ou função.
As dependências entre subtarefas são explícitas — você sabe quais precisam rodar em ordem e quais podem rodar em paralelo.
Cada subtarefa tem entradas e saídas claras — a saída de um passo pode alimentar diretamente o próximo.

Decomponha bem e escrever o fluxo de trabalho vira montar Lego. Decomponha mal e você vai descobrir, no meio da execução, que faltam passos, que a ordem está errada ou que os dados não fluem.²

Estratégia 1: decomposição sequencial

Quando usar: a tarefa tem uma ordem clara do início ao fim, e cada passo depende do resultado do anterior.

Como: trabalhe de trás para frente, a partir do fim. Pergunte “de que entrada este passo precisa? De onde vem essa entrada?”

Exemplo: gerar documentação técnica

Tarefa: gerar documentação voltada ao usuário para uma API.

Decomposição de trás para frente:

Saída final: documentação em Markdown  ↑ precisa do quê?Passo 4: renderizar o Markdown (precisa de: conteúdo estruturado do documento)  ↑ vem de onde?Passo 3: organizar o conteúdo (precisa de: lista de endpoints + código de exemplo + descrições)  ↑ vem de onde?Passo 2: gerar um exemplo por endpoint (precisa de: lista de endpoints)  ↑ vem de onde?Passo 1: extrair a lista de endpoints do código (precisa de: código-fonte)  ↑Início: diretório de origem

Saída final: documentação em Markdown  ↑ precisa do quê?Passo 4: renderizar o Markdown (precisa de: conteúdo estruturado do documento)  ↑ vem de onde?Passo 3: organizar o conteúdo (precisa de: lista de endpoints + código de exemplo + descrições)  ↑ vem de onde?Passo 2: gerar um exemplo por endpoint (precisa de: lista de endpoints)  ↑ vem de onde?Passo 1: extrair a lista de endpoints do código (precisa de: código-fonte)  ↑Início: diretório de origem

Transformada em um fluxo de trabalho:

JAVASCRIPT

async function generateAPIDocsWorkflow(sourceDir) {
  // Passo 1: extrair os endpoints
  const endpoints = await extractEndpoints(sourceDir);
  
  // Passo 2: gerar exemplos (depende do passo 1)
  const examples = await Promise.all(
    endpoints.map(ep => generateExample(ep))
  );
  
  // Passo 3: organizar o conteúdo (depende dos passos 1 e 2)
  const content = await agent({
    task: 'Organize a estrutura do documento',
    prompt: 'Organize os endpoints e os exemplos em uma estrutura de documento amigável ao usuário',
    context: { endpoints, examples }
  });
  
  // Passo 4: renderizar o Markdown (depende do passo 3)
  const markdown = await renderMarkdown(content);
  
  return markdown;
}

Cadeia de dependências:

O passo 2 pode rodar em paralelo com o passo 1? Não — o passo 2 precisa dos endpoints do passo 1.

O passo 3 pode rodar em paralelo com o passo 2? Não — o passo 3 precisa dos examples do passo 2.

Como é a decomposição sequencial: uma longa cadeia de dependências, poucas chances de paralelizar, mas com lógica clara.³

Estratégia 2: decomposição paralela

Quando usar: a tarefa se divide em várias subtarefas independentes que não dependem umas das outras.

Como: identifique o padrão “faça Y para cada X” — cada X pode ser processado em paralelo.

Exemplo: auditoria de segurança de uma base de código

Tarefa: auditar 100 arquivos em busca de problemas de segurança.

Decomposição paralela:

JAVASCRIPT

async function securityAuditWorkflow(files) {
  // Fase 1: auditar cada arquivo em paralelo (sem dependências)
  const audits = await Promise.all(
    files.map(file => auditFile(file))
  );
  
  // Fase 2: agregar os resultados (depende da fase 1)
  const summary = await agent({
    task: 'Resuma a auditoria de segurança',
    prompt: `Analise os resultados da auditoria em ${audits.length} arquivos,
             ordene os problemas por severidade e produza um resumo executivo`,
    context: audits
  });
  
  return summary;
}

async function auditFile(file) {
  return await agent({
    task: `Audite ${file.path}`,
    prompt: `Cheque injeção de SQL, XSS, segredos hardcoded e criptografia fraca.
             Devolva JSON: { file, issues: [{ type, line, severity }] }`
  });
}

Formato:

          ┌─→ auditFile(1) ─┐          ├─→ auditFile(2) ─┤files ───→├─→ auditFile(3) ─┼─→ summary          ├─→   ...         ─┤          └─→ auditFile(100)─┘

          ┌─→ auditFile(1) ─┐          ├─→ auditFile(2) ─┤files ───→├─→ auditFile(3) ─┼─→ summary          ├─→   ...         ─┤          └─→ auditFile(100)─┘

Padrão fan-out-reduce: este é o formato mais comum da decomposição paralela.⁴

Fan out: espalhe a tarefa entre muitos agentes paralelos.
Reduce: junte todos os resultados em uma saída final.

O poder da decomposição paralela: 100 arquivos, 2 minutos para auditar cada um. A execução sequencial leva 200 minutos; a paralela leva 2 (supondo que não haja limites de recursos).

Estratégia 3: decomposição híbrida

Quando usar: na maioria das tarefas reais. Algumas partes rodam em paralelo, outras precisam rodar em ordem.

Como: primeiro encontre as fases de alto nível (que precisam rodar em ordem) e depois encontre as oportunidades de paralelismo dentro de cada fase.

Exemplo: uma refatoração em larga escala

Tarefa: atualizar 50 componentes de Vue 2 para Vue 3.

Decomposição híbrida:

mermaid

graph TD    A[Fase 1: analisar dependências] --> B{Paralelo?}    B -->|Sim| C1[Analisar componentes 1-25]    B -->|Sim| C2[Analisar componentes 26-50]    C1 --> D[Fase 2: montar o plano de migração]    C2 --> D    D --> E{Paralelo?}    E -->|Sim| F1[Migrar componentes 1-25]    E -->|Sim| F2[Migrar componentes 26-50]    F1 --> G[Fase 3: testes de integração]    F2 --> G    G --> H{Testes passaram?}    H -->|Sim| I[Pronto]    H -->|Não| J[Fase 4: corrigir componentes que falharam]    J --> G

graph TD    A[Fase 1: analisar dependências] --> B{Paralelo?}    B -->|Sim| C1[Analisar componentes 1-25]    B -->|Sim| C2[Analisar componentes 26-50]    C1 --> D[Fase 2: montar o plano de migração]    C2 --> D    D --> E{Paralelo?}    E -->|Sim| F1[Migrar componentes 1-25]    E -->|Sim| F2[Migrar componentes 26-50]    F1 --> G[Fase 3: testes de integração]    F2 --> G    G --> H{Testes passaram?}    H -->|Sim| I[Pronto]    H -->|Não| J[Fase 4: corrigir componentes que falharam]    J --> G

Transformada em um fluxo de trabalho:

JAVASCRIPT

async function vue2to3MigrationWorkflow(components) {
  // Fase 1: analisar todos os componentes em paralelo
  const analyses = await Promise.all(
    components.map(c => analyzeComponent(c))
  );
  
  // Fase 2: montar o plano de migração em ordem (depende da fase 1)
  const plan = await agent({
    task: 'Monte o plano de migração',
    prompt: 'Com base na análise, defina a ordem de migração e sinalize conflitos em potencial',
    context: analyses
  });
  
  // Fase 3: migrar os componentes em paralelo, seguindo o plano
  const migrated = await Promise.all(
    plan.batches.map(batch => 
      Promise.all(batch.map(c => migrateComponent(c)))
    )
  );
  
  // Fase 4: rodar os testes de integração em ordem
  let testResult = await runIntegrationTests();
  
  // Fase 5: se os testes falharem, corrigir e testar de novo (loop)
  let attempts = 0;
  while (!testResult.passed && attempts < 3) {
    const failures = testResult.failures;
    await Promise.all(
      failures.map(f => fixComponent(f))
    );
    testResult = await runIntegrationTests();
    attempts++;
  }
  
  if (!testResult.passed) {
    throw new Error('Migração falhou: as 3 tentativas de correção falharam nos testes');
  }
  
  return { plan, migrated, testResult };
}

Grafo de dependências do híbrido:

Fase 1 (paralela)       Fase 2 (sequencial)analyze(1..50) ────→ generatePlan                              ↓Fase 3 (paralela)            ↓migrate(1..50) ←────────────┘       ↓Fase 4 (sequencial)runTests ←───────┐   ↓             │   ├─passa→ Feito │   └─falha→ Fase 5 (paralela + loop)          fix(failures) ─┘

Fase 1 (paralela)       Fase 2 (sequencial)analyze(1..50) ────→ generatePlan                              ↓Fase 3 (paralela)            ↓migrate(1..50) ←────────────┘       ↓Fase 4 (sequencial)runTests ←───────┐   ↓             │   ├─passa→ Feito │   └─falha→ Fase 5 (paralela + loop)          fix(failures) ─┘

O coração da decomposição híbrida: mantenha a ordem de que você realmente precisa, extraindo ao mesmo tempo toda chance de paralelizar.³

Usando um LLM para ajudar a decompor

Você também pode entregar a decomposição a um LLM. Três caminhos funcionam: prompting zero-shot, prompting chain-of-thought e prompting few-shot (guiado por exemplos).¹

Zero-shot

Tarefa: atualizar a documentação de uma API REST, cobrindo 100 endpoints, de Swagger 2.0 para OpenAPI 3.0
Quebre esta tarefa em 5 a 8 passos claros. Para cada passo, informe:1. O que ele faz2. De que entrada ele precisa3. O que ele produz de saída4. Se ele pode rodar em paralelo

Tarefa: atualizar a documentação de uma API REST, cobrindo 100 endpoints, de Swagger 2.0 para OpenAPI 3.0
Quebre esta tarefa em 5 a 8 passos claros. Para cada passo, informe:1. O que ele faz2. De que entrada ele precisa3. O que ele produz de saída4. Se ele pode rodar em paralelo

Chain-of-thought

Tarefa: refatorar uma classe Python de 5000 linhas, dividindo-a em várias classes menores
Vamos pensar passo a passo em como decompor isso:
O que o primeiro passo deve fazer, e por quê?De qual saída do primeiro passo o segundo passo depende?Quais passos podem rodar em paralelo?Como verificamos que cada passo terminou corretamente?
Dê uma decomposição detalhada.

Tarefa: refatorar uma classe Python de 5000 linhas, dividindo-a em várias classes menores
Vamos pensar passo a passo em como decompor isso:
O que o primeiro passo deve fazer, e por quê?De qual saída do primeiro passo o segundo passo depende?Quais passos podem rodar em paralelo?Como verificamos que cada passo terminou corretamente?
Dê uma decomposição detalhada.

Few-shot

Vou te dar uma tarefa complexa. Siga o exemplo para quebrá-la em passos de fluxo de trabalho.
Tarefa de exemplo: processar 50 imagens em lote (redimensionar, adicionar marca d'água)Decomposição de exemplo:1. Ler a lista de imagens (entrada: caminho do diretório, saída: lista de arquivos)2. Processar cada imagem em paralelo:   2a. Redimensionar (entrada: imagem original, saída: imagem redimensionada)   2b. Adicionar marca d'água (entrada: imagem redimensionada, saída: imagem final)3. Salvar os resultados (entrada: lista de imagens processadas, saída: lista de caminhos salvos)
Agora decomponha esta tarefa: gerar um relatório de estatísticas de contribuidores para 20 repositórios Git

Vou te dar uma tarefa complexa. Siga o exemplo para quebrá-la em passos de fluxo de trabalho.
Tarefa de exemplo: processar 50 imagens em lote (redimensionar, adicionar marca d'água)Decomposição de exemplo:1. Ler a lista de imagens (entrada: caminho do diretório, saída: lista de arquivos)2. Processar cada imagem em paralelo:   2a. Redimensionar (entrada: imagem original, saída: imagem redimensionada)   2b. Adicionar marca d'água (entrada: imagem redimensionada, saída: imagem final)3. Salvar os resultados (entrada: lista de imagens processadas, saída: lista de caminhos salvos)
Agora decomponha esta tarefa: gerar um relatório de estatísticas de contribuidores para 20 repositórios Git

A vantagem da decomposição por LLM: ela esboça um primeiro plano rápido e pega passos que você poderia ter esquecido.

A desvantagem da decomposição por LLM: ela pode ficar abstrata demais (dizer “analise os dados” em vez de “calcule a complexidade ciclomática de cada arquivo”), então precisa de um humano para afiar.¹

Dicas práticas para identificar dependências

Dica 1: pergunte “este passo poderia rodar antes do primeiro?”

Se a resposta for “sim”, eles podem rodar em paralelo. Se for “não, ele precisa do resultado do primeiro passo”, existe uma dependência.

Dica 2: desenhe o grafo de dependências

As setas indicam dependência: A → B significa "B depende da saída de A"
Passo 1 → Passo 2 → Passo 4          ↓        Passo 3 ↗

As setas indicam dependência: A → B significa "B depende da saída de A"
Passo 1 → Passo 2 → Passo 4          ↓        Passo 3 ↗

Os passos 2 e 3 podem rodar em paralelo? Sim — ambos dependem apenas do passo 1.

Os passos 3 e 4 podem rodar em paralelo? Não — o passo 4 depende do passo 2.

Um grafo em que as setas indicam dependência e nunca voltam para o início tem nome formal: DAG (grafo acíclico dirigido). O passo 1 não depende de nada, então é uma folha que o grafo pode executar primeiro. Ordenar todos os passos de modo a nunca violar a direção de uma seta se chama ordenação topológica.

Dica 3: cheque o fluxo de dados

Liste a entrada e a saída de cada passo:

Passo	Entrada	Saída
1. Ler arquivo	caminho do arquivo	conteúdo do arquivo
2. Fazer o parse do código	conteúdo do arquivo	AST
3. Extrair funções	AST	lista de funções
4. Gerar documentação	lista de funções	Markdown

Se a entrada do passo X vem da saída do passo Y, então X depende de Y.

Erros comuns de decomposição

Erro 1: passos grandes demais

O que “preparar os dados” abrange? Ler arquivos? Fazer o parse da configuração? Conectar em um banco de dados? Vago demais.

✓ Bom:1. Ler o arquivo de configuração2. Conectar no banco de dados3. Ler a tabela de dados de origem4. Transformar o formato dos dados5. Escrever na tabela de dados de destino6. Rodar uma consulta de verificação

✓ Bom:1. Ler o arquivo de configuração2. Conectar no banco de dados3. Ler a tabela de dados de origem4. Transformar o formato dos dados5. Escrever na tabela de dados de destino6. Rodar uma consulta de verificação

Erro 2: nenhum passo de tratamento de erros

❌ Ruim:1. Fazer o deploy do serviço A2. Fazer o deploy do serviço B3. Atualizar o balanceador de carga

❌ Ruim:1. Fazer o deploy do serviço A2. Fazer o deploy do serviço B3. Atualizar o balanceador de carga

E se o passo 2 falhar? O serviço A já está no ar, mas o B não, e o sistema fica em um estado inconsistente.

✓ Bom:1. Fazer backup da configuração atual2. Fazer o deploy do serviço A3. Fazer a checagem de saúde do serviço A4. Se o passo 3 falhar → reverter o serviço A5. Fazer o deploy do serviço B6. Fazer a checagem de saúde do serviço B7. Se o passo 6 falhar → reverter os serviços A e B8. Atualizar o balanceador de carga

✓ Bom:1. Fazer backup da configuração atual2. Fazer o deploy do serviço A3. Fazer a checagem de saúde do serviço A4. Se o passo 3 falhar → reverter o serviço A5. Fazer o deploy do serviço B6. Fazer a checagem de saúde do serviço B7. Se o passo 6 falhar → reverter os serviços A e B8. Atualizar o balanceador de carga

Erro 3: ignorar oportunidades de paralelismo

❌ Ruim (sequencial):for (const service of services) {  await buildService(service);  await testService(service);  await deployService(service);}

❌ Ruim (sequencial):for (const service of services) {  await buildService(service);  await testService(service);  await deployService(service);}

Isso processa um serviço por vez. Lento.

✓ Bom (paralelo híbrido):// Buildar todos os serviços em paraleloawait Promise.all(services.map(s => buildService(s)));
// Testar todos os serviços em paraleloawait Promise.all(services.map(s => testService(s)));
// Fazer o deploy de todos os serviços em paraleloawait Promise.all(services.map(s => deployService(s)));

✓ Bom (paralelo híbrido):// Buildar todos os serviços em paraleloawait Promise.all(services.map(s => buildService(s)));
// Testar todos os serviços em paraleloawait Promise.all(services.map(s => testService(s)));
// Fazer o deploy de todos os serviços em paraleloawait Promise.all(services.map(s => deployService(s)));

Próxima: Lição 4: Gerenciamento de estado e passagem de contexto — aprenda a passar e gerenciar dados corretamente entre os passos de um fluxo de trabalho.

ApX Machine Learning: Task Decomposition Strategies for LLM Agents — https://apxml.com/courses/agentic-llm-memory-architectures/chapter-4-complex-planning-tool-integration/task-decomposition-strategies ↩ ↩² ↩³
ACONIC paper: Systematic LLM Task Decomposition — https://arxiv.org/html/2510.07772v1 ↩
OneUpTime: How to Create a Task Decomposition — https://oneuptime.com/blog/post/2026-01-30-task-decomposition/view ↩ ↩²
MindStudio: Five Claude Code Agentic Workflow Patterns — https://www.mindstudio.ai/blog/claude-code-agentic-workflow-patterns ↩

Exercícios

Escolha uma das tarefas abaixo e quebre-a em 5 a 8 passos:

Nível 1: Decomponha uma tarefa real

Tarefa A: gerar um relatório de performance de uma aplicação web (tempo de carregamento, tamanho dos recursos, Core Web Vitals)

Tarefa B: limpar um repositório Git (remover dependências não usadas, apagar código morto, atualizar comentários desatualizados)

Requisitos:

Para cada passo, detalhe o que ele faz, sua entrada e sua saída
Marque quais passos podem rodar em paralelo
Desenhe o grafo de dependências (em palavras ou com setas)
Diga se a decomposição é sequencial, paralela ou híbrida

Critérios de conclusão · marcado localmente

A quantidade de passos é razoável (de 5 a 8 passos, não 3 gigantes nem 15 fragmentos)cada passo tem entradas e saídas clarasas oportunidades de paralelismo estão corretamente identificadas (por exemplo, na Tarefa A, tempo de carregamento, tamanho dos recursos e Core Web Vitals podem ser medidos em paralelo)o grafo de dependências está corretoa escolha da estratégia de decomposição é sólida.

Abaixo está uma decomposição para a tarefa “migrar endpoints de API em lote”. Ela tem 3 problemas sérios. Encontre-os e apresente um plano corrigido.

Nível 2: Conserte uma decomposição quebrada

Decomposição original:1. Ler todas as configurações de endpoints da API2. Gerar as novas definições de endpoints3. Fazer o deploy em produção

Decomposição original:1. Ler todas as configurações de endpoints da API2. Gerar as novas definições de endpoints3. Fazer o deploy em produção

Requisitos:

Encontre os 3 problemas (dica: passos grandes demais, sem tratamento de erros, paralelismo ignorado)
Apresente uma decomposição corrigida e completa (de 5 a 8 passos)

Critérios de conclusão · marcado localmente

Identifica corretamente os 3 problemas principais (o passo 2 é vago demais e não diz como gerarnão há passo de teste ou verificaçãonão há reversãomúltiplos endpoints não são processados em paralelo)o plano corrigido tem pelo menos 6 passosinclui um passo de teste ou verificaçãoinclui um passo de tratamento de erros ou de reversãoidentifica a oportunidade de paralelismo.

Lição 3: Decompondo uma tarefa complexa em um fluxo de trabalho

De “não sei por onde começar” a passos claros

Estratégia 1: decomposição sequencial

Exemplo: gerar documentação técnica

Estratégia 2: decomposição paralela

Exemplo: auditoria de segurança de uma base de código

Estratégia 3: decomposição híbrida

Exemplo: uma refatoração em larga escala

Usando um LLM para ajudar a decompor

Zero-shot

Chain-of-thought

Few-shot

Dicas práticas para identificar dependências

Erros comuns de decomposição

Footnotes

Exercícios

Escolha uma das tarefas abaixo e quebre-a em 5 a 8 passos:

Abaixo está uma decomposição para a tarefa “migrar endpoints de API em lote”. Ela tem 3 problemas sérios. Encontre-os e apresente um plano corrigido.