# Subagentes e trabalho paralelo no Claude Code: como executar várias tarefas simultaneamente

> Guia completo sobre paralelização de tarefas no Claude Code: arquitetura de subagentes, contexto compartilhado e isolado, padrões Fan-Out e Swarm, execução via CLI com a flag -p e otimização de tokens.

## 1. O que são subagentes no Claude Code: do pensamento sequencial ao paralelo

Uma sessão de trabalho padrão do **Claude Code** opera em modo estritamente sequencial (single-threaded event loop). O usuário envia uma solicitação, o agente lê o contexto, executa buscas, edita arquivos, roda linters ou testes e só então, após concluir toda a cadeia, passa para a próxima tarefa. Quando o projeto escala e surgem dezenas de tarefas mutuamente independentes, essa abordagem sequencial gera atrasos injustificados e entope rapidamente a janela de contexto.

Para superar essa limitação, a arquitetura do Claude Code integra o conceito de **subagentes** — instâncias isoladas e autônomas do modelo, às quais são delegados fragmentos independentes da tarefa geral.

```mermaid
flowchart TD
    subgraph Sequential ["Послідовний режим (Single Session)"]
        S1["Завдання 1"] --> S2["Завдання 2"] --> S3["Завдання 3"] --> S4["Фінальний результат"]
    end

    subgraph Parallel ["Паралельний режим (Subagent Orchestration)"]
        P_Parent["Батьківська сесія Claude Code"] --> P1["Субагент 1: Auth"]
        P_Parent --> P2["Субагент 2: Validation"]
        P_Parent --> P3["Субагент 3: Formatting"]
        P1 --> P_Join{"Агрегація результатів"}
        P2 --> P_Join
        P3 --> P_Join
        P_Join --> P_Done["Готовий pull request / звіт"]
    end
```

### Características-chave de um subagente autônomo

- **Janela de contexto própria e isolada:** O subagente não carrega o peso do histórico longo da sessão principal, focando exclusivamente na tarefa atribuída.
- **Acesso compartilhado ao sistema de arquivos:** O subagente pode ler a estrutura de diretórios, configurações do projeto e código-fonte com os mesmos privilégios do processo principal.
- **Execução assíncrona:** Vários subagentes trabalham simultaneamente, reduzindo o tempo total de execução (wall-clock time) proporcionalmente ao número de fluxos paralelos.
- **Agregação automática:** Ao concluir o trabalho, o subagente gera um resumo estruturado, retorna-o à sessão pai e libera os recursos alocados.

> [!NOTE]
> A analogia mental mais simples para subagentes é a gestão eficiente de desenvolvimento. Em vez de um Engenheiro Sênior escrever documentação para cinco microsserviços um por um, ele cria 5 tarefas distintas e as distribui para executadores paralelos, revisando apenas o resultado final de cada um.

---

## 2. Critérios de paralelização: quando dividir tarefas e quando trabalhar sequencialmente

A paralelização não é uma panaceia universal. Sua eficácia depende diretamente do grau de independência mútua das tarefas. Tentar executar etapas interdependentes em paralelo inevitavelmente causa race conditions (condições de corrida) e colisões lógicas.

| Cenário de Desenvolvimento | Modo Ótimo | Justificativa da Escolha |
| :--- | :---: | :--- |
| **Geração de unit-tests para utilitários distintos** | Paralelo | Os módulos não dependem uns dos outros; não há dependências compartilhadas |
| **Auditoria multidimensional de segurança, SEO e UI** | Paralelo | Cada direção analisa o sistema sob sua própria perspectiva, apenas lendo dados |
| **Projeto do schema do banco de dados e geração de migrações** | Sequencial | Não é possível escrever a migração antes de finalizar o modelo do banco de dados |
| **Edição do mesmo arquivo de configuração** | Sequencial | Escrita simultânea por múltiplos agentes causa conflitos de merge |
| **Refatoração em lote de componentes independentes** | Paralelo | Cada componente reside em um arquivo separado sem imports cruzados |

### Quando a paralelização é contraindicada

1. **Dependência em cascata de resultados:** Se a etapa B utiliza a saída da etapa A. Exemplo: primeiro auditar o schema do banco, projetar a nova estrutura e só então gerar a migração do Prisma.
2. **Pontos comuns de modificação de arquivos:** Se o Agente 1 e o Agente 2 tentarem alterar simultaneamente o mesmo arquivo `app.ts` ou `package.json`, uma das escritas será sobrescrita ou corrompida.
3. **Tarefas que exigem feedback humano iterativo:** Se os requisitos não estão totalmente definidos e o desenvolvedor precisa ajustar constantemente o curso através de perguntas de esclarecimento, a tarefa deve permanecer em uma sessão interativa única.

> [!WARNING]
> Regra de ouro da paralelização: antes de iniciar um pool de agentes, responda claramente à pergunta: **«Cada agente pode executar sua tarefa do início ao fim sem esperar respostas intermediárias dos outros?»**. Se a resposta for "não" — trabalhe exclusivamente de forma sequencial.

---

## 3. Arquitetura e mecânica de lançamento de subagentes via Task Tool

Dentro do motor do Claude Code, a orquestração de subagentes é realizada através da ferramenta de sistema **Task tool**. Quando o modelo na sessão principal entende que a tarefa consiste em componentes isolados, ele inicia processos filhos em segundo plano.

Normalmente, o usuário não precisa chamar manualmente as instruções JSON do sistema da Task tool — basta formular claramente a decomposição na solicitação ou permitir que o Claude Code desmembre a tarefa automaticamente.

![Arquitetura de lançamento de subagentes do Claude Code e agregação de resultados na sessão principal](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-step-01.webp)

### Ciclo de vida da execução paralela

1. **Dispersão da tarefa:** A sessão principal recebe um prompt complexo (por exemplo, escrever testes para cinco utilitários: `auth.ts`, `validation.ts`, `formatting.ts`, `api-client.ts`, `cache.ts`).
2. **Formação de contextos filhos:** São criados subagentes separados, cada um recebendo uma tarefa personalizada e o caminho para o arquivo alvo.
3. **Trabalho autônomo:** Cada agente lê paralelamente o código-fonte de seu módulo, explora os tipos de dados, gera o conjunto de testes correspondente e verifica sua execução.
4. **Merge reverso (Aggregation):** A sessão principal aguarda a conclusão de todos os fluxos, recebe os status finais de execução e apresenta ao desenvolvedor um relatório consolidado.

---

## 4. Contexto compartilhado vs. isolado: o que os subagentes veem

O erro mais comum entre desenvolvedores iniciantes é assumir que os subagentes possuem conexão telepática entre si ou sabem tudo o que foi discutido no passo 50 do diálogo principal. Na realidade, o modelo segue uma política rígida de segregação de memória.

![Contexto compartilhado e isolado dos subagentes: o que está disponível para todos os agentes e o que permanece privado](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-extra-02.webp)

| Recurso ou Estado do Sistema | Compartilhado para todos os agentes? | Descrição Técnica do Acesso |
| :--- | :---: | :--- |
| **Arquivos do projeto no disco** | **Sim** | Todos os agentes têm acesso de leitura e escrita ao diretório de trabalho |
| **Regras CLAUDE.md** | **Sim** | Cada agente é inicializado automaticamente com as regras do projeto e stack |
| **Histórico do diálogo anterior** | **Não** | Janela isolada; o subagente vê apenas seu próprio prompt imediato |
| **Alterações em arquivos abertos** | **Requer cautela** | Não há mecanismos de bloqueio automático de arquivos; risco de colisão durante escrita |

### Garantindo a segurança da escrita em arquivos (Write Ownership)

Para evitar corrupção da base de código durante o trabalho paralelo, siga o princípio do **único proprietário do arquivo**:

```text
Distribuição correta das zonas de responsabilidade:
Subagente 1 ──► src/utils/auth.test.ts        (cria um novo arquivo de teste)
Subagente 2 ──► src/utils/validation.test.ts  (cria um novo arquivo de teste)
Subagente 3 ──► src/utils/formatting.test.ts  (cria um novo arquivo de teste)

Distribuição inaceitável (colisão):
Subagente 1 ──► src/index.ts  (modifica a linha de exportação)
Subagente 2 ──► src/index.ts  (modifica a linha de exportação)
Subagente 3 ──► src/index.ts  (modifica a linha de exportação)
```

> [!IMPORTANT]
> Se vários agentes paralelos precisarem registrar os módulos criados em um único arquivo índice (`src/index.ts` ou `src/routes.ts`), **não delegue** isso aos subagentes. Deixe que os agentes apenas criem seus arquivos isolados, enquanto a sessão pai realiza o registro dos imports no arquivo índice após o retorno de todos os resultados.

---

## 5. Padrões de formulação de prompts para lançar agentes paralelos

Embora o Claude Code tenha heurísticas para detectar tarefas paralelas, a instrução explícita sobre execução simultânea elimina qualquer ambiguidade e otimiza o tempo de dispersão.

### Exemplos de formulação eficaz de solicitações

:::tabs
@tab Distribuição Básica
```markdown
Execute as seguintes três tarefas em paralelo por meio de subagentes separados:

1. Implemente a validação de campos no componente do formulário de registro (src/components/RegisterForm.tsx).
2. Crie um componente de esqueleto de carregamento para o dashboard (src/components/DashboardSkeleton.tsx).
3. Adicione suporte à paginação no hook de carregamento de usuários (src/hooks/useUsers.ts).

Certifique-se de que cada agente trabalhe apenas com seu próprio arquivo e não modifique configurações compartilhadas.
```
@tab Análise Fan-Out
```markdown
Trabalhe em paralelo por meio de subagentes:

- Agente 1: Pesquise a documentação oficial da API do Stripe sobre o processamento de eventos webhook de assinaturas.
- Agente 2: Analise nossa implementação atual no módulo src/services/billing.ts em busca de vulnerabilidades.
- Agente 3: Projete interfaces TypeScript para os novos objetos DTO de entrada em src/types/stripe.ts.

Após a conclusão, consolide os resultados em um único plano de refatoração na sessão principal.
```
@tab Auditoria em Lote
```markdown
Realize uma auditoria paralela da base de código em quatro frentes:

- Frente A (Segurança): Varredura em busca de vazamento de segredos no histórico do git e análise da segurança das consultas ao banco de dados.
- Frente B (Desempenho): Identificação de consultas N+1 nos controladores e detecção de imports pesados nos bundles do cliente.
- Frente C (Tipagem): Verificação da presença de tipos inseguros "any" e campos obrigatórios ausentes nas interfaces.
- Frente D (Acessibilidade): Auditoria da existência de atributos aria-label e da relação de contraste de cores nas classes Tailwind.
```
:::

---

## 6. Quatro esquemas-chave de trabalho paralelo: padrões prontos

A experiência prática de automação em equipe com o Claude Code permitiu cristalizar quatro padrões arquitetônicos de alta eficiência para orquestração paralela.

```mermaid
flowchart LR
    subgraph P1 ["1. Research Fan-Out"]
        RF_Q["Архітектурне питання"] --> RF1["PostgreSQL"]
        RF_Q --> RF2["MongoDB"]
        RF_Q --> RF3["SQLite"]
        RF1 & RF2 & RF3 --> RF_M["Порівняльна матриця"]
    end

    subgraph P2 ["2. Audit Swarm"]
        AS_Code["Репозиторій"] --> AS1["Security"]
        AS_Code --> AS2["Performance"]
        AS_Code --> AS3["A11y"]
        AS_Code --> AS4["Code Quality"]
        AS1 & AS2 & AS3 & AS4 --> AS_R["Загальний аудит-звіт"]
    end
```

### Research Fan-Out (Pesquisa Paralela)

Usado quando, para tomar uma decisão técnica, é necessário analisar simultaneamente várias bibliotecas alternativas, tecnologias ou abordagens arquiteturais. Cada agente pesquisa uma stack específica usando critérios padronizados (prós, contras, compatibilidade de licença, tamanho do bundle), após o que a sessão principal sintetiza uma matriz comparativa.

### Audit Swarm (Auditoria Multidisciplinar)

Um dos padrões mais econômicos em termos de preservação de tempo. Em vez de um agente ler todo o repositório quatro vezes seguidas para diferentes verificações, quatro agentes especializados estreitos são lançados simultaneamente. Como a auditoria é feita exclusivamente em modo somente-leitura (read-only), o risco de conflitos de escrita em arquivos é totalmente eliminado.

### Batch Processor (Refatoração em Lote)

Aplicável em migrações em larga escala, quando uma transformação idêntica precisa ser aplicada a um grande array de arquivos independentes:
- Conversão de componentes React class antigos para hooks funcionais no diretório `src/components/`.
- Reescrita de testes de Jest para Vitest.
- Atualização de imports de utilitários antigos após movê-los para um monorepo.

### Feature Sprint (Desenvolvimento Paralelo de Features Independentes)

Desenvolvimento simultâneo de vários módulos de UI autocontidos ou endpoints de API. Por exemplo:
- Agente 1 implementa o toggle de tema escuro (`ThemeToggle.tsx` + contexto correspondente).
- Agente 2 desenvolve o formulário de busca global (`SearchBar.tsx` + hook de busca).
- Agente 3 cria o menu dropdown de notificações (`NotificationsDropdown.tsx`).

---

## 7. Execução paralela via CLI: Modo Headless e flag -p

Além da sessão interativa do Claude Code, existe uma ferramenta poderosa de automação sistêmica — rodar o Claude em **modo headless (não interativo)** usando a flag `-p` (`--print`). Nesse modo, o agente recebe o prompt como argumento de linha de comando, executa a tarefa em um processo terminal isolado e imprime o resultado.

Isso abre a possibilidade de usar os recursos padrão de execução em segundo plano de processos em shells Unix-like (`&`) e a utilidade de sincronização `wait`.

```bash
# Одночасний запуск трьох фонових процесів Claude Code у bash/zsh
claude -p "Write unit tests for src/utils/auth.ts using Vitest" &
PID_AUTH=$!

claude -p "Write unit tests for src/utils/validation.ts using Vitest" &
PID_VAL=$!

claude -p "Write unit tests for src/utils/formatting.ts using Vitest" &
PID_FMT=$!

# Очікуємо завершення всіх паралельних фонових завдань
echo "Запущено фонові агенти з PID: $PID_AUTH, $PID_VAL, $PID_FMT. Очікування..."
wait $PID_AUTH $PID_VAL $PID_FMT

echo "Всі тести згенеровано успішно! Запуск перевірки..."
npm test
```

### Vantagens da paralelização via CLI

- **Zero supervisão humana:** Ideal para scripts noturnos de CI/CD, preparação de conjuntos de testes ou pré-geração de documentação.
- **Isolamento real do SO:** Cada processo `claude` roda em um espaço de endereçamento separado do sistema operacional.
- **Logging em arquivos:** A saída de cada processo pode ser facilmente redirecionada para seu próprio log-file: `claude -p "..." > logs/auth.log 2>&1 &`.

> [!TIP]
> No terminal, o operador `&` ao final do comando envia o processo para background, liberando o terminal para iniciar imediatamente o próximo comando. O comando integrado `wait` bloqueia a execução do script até que todos os PIDs em segundo plano especificados terminem o trabalho e retornem o código de saída.

---

## 8. Economia de tokens, limites de API e otimização de custos

O trabalho paralelo economiza drasticamente o tempo do engenheiro, mas exige controle financeiro rigoroso. Cada subagente cria sua própria janela de contexto, portanto, o lançamento paralelo de $N$ agentes aumenta o consumo de tokens aproximadamente $N$ vezes.

```text
Sessão sequencial (1 janela de contexto):
[Prompt do sistema] + [Tarefa 1] ──► [Tarefa 2] ──► [Tarefa 3]
Total de tokens: Contexto base + ΔT1 + ΔT2 + ΔT3

Subagentes paralelos (3 janelas de contexto independentes):
Subagente 1: [Contexto base + Tarefa 1]
Subagente 2: [Contexto base + Tarefa 2]
Subagente 3: [Contexto base + Tarefa 3]
Total de tokens: (3 × Contexto base) + ΔT1 + ΔT2 + ΔT3
```

### Quatro regras para controle do orçamento de tokens

1. **Escopo bem definido:** Não dê ao agente uma incumbência vaga como "Arrume os testes do projeto". Formule especificamente: "Escreva 3 unit-tests para a função parseJwt em src/utils/auth.ts".
2. **Filtragem de arquivos:** Se o projeto contiver grandes diretórios (ex.: tipos gerados ou mocks), certifique-se de que estejam adicionados ao `.gitignore` ou `.claudeignore`, para que os subagentes não leiam megabytes desnecessários de texto.
3. **Uso de `-p` para tarefas triviais:** A execução não interativa evita o acúmulo de histórico de conversa e imprime o resultado sem lixo dialógico supérfluo.
4. **Agrupação de tarefas muito pequenas:** Criar um subagente separado para mudar uma linha no CSS é inviável — os overheads de inicialização da sessão excederão o trabalho útil.

---

## 9. Workshop prático: implementação passo a passo, de testes a Audit Swarm

Vamos consolidar os conhecimentos adquiridos em um workshop prático com execução passo a passo.

### Passo 1. Seleção de módulos isolados e preparação

Escolha em seu repositório três módulos utilitários que não tenham imports cíclicos ou mútuos:
- `src/utils/auth.ts`
- `src/utils/validation.ts`
- `src/utils/formatting.ts`

Certifique-se de que os arquivos de teste correspondentes estejam ausentes ou necessitem de atualização.

### Passo 2. Formulação e lançamento do prompt paralelo

Abra uma sessão interativa do Claude Code no terminal do projeto e insira uma solicitação estruturada:

```markdown
Gere testes modulares para os seguintes três arquivos em paralelo por meio de subagentes:

1. src/utils/auth.ts -> salve os testes em src/utils/auth.test.ts
2. src/utils/validation.ts -> salve os testes em src/utils/validation.test.ts
3. src/utils/formatting.ts -> salve os testes em src/utils/formatting.test.ts

Requisitos dos testes:
- Utilize Vitest e verificações expect avançadas.
- Cubra casos extremos (null, undefined, strings vazias).
- Não modifique os arquivos originais de utilitários.
```

### Passo 3. Monitoramento e verificação dos resultados

Acompanhe a saída no console. Você verá o Claude Code iniciando tarefas filhas, processando o código de cada módulo independentemente e sinalizando a conclusão de cada subprocesso.

Após a conclusão, execute a verificação em seu terminal:

```bash
npm run test:run
```

Todos os três novos conjuntos de testes devem passar na validação com sucesso, sem conflitos na base de código.

### Passo 4. Lançamento do Audit Swarm para avaliação de qualidade

O próximo passo é testar o padrão analítico Audit Swarm. Envie a solicitação:

```markdown
Realize uma auditoria abrangente do repositório por meio de quatro subagentes em paralelo:

- Agente de Segurança: verificação de XSS, CSRF, pacotes npm vulneráveis e segredos codificados diretamente no código (hardcoded).
- Agente de Desempenho: análise do tamanho do bundle, re-renders desnecessários e bibliotecas pesadas.
- Agente de Acessibilidade (a11y): verificação de tags HTML semânticas, armadilhas de foco (focus traps) e atributos ARIA.
- Agente de Qualidade de Código: identificação de código morto, duplicações e uso injustificado de `any`.

Gere um relatório consolidado com prioridades de correção (Alta / Média / Baixa).
```

---

## 10. Resumo final e checklist de prontidão para paralelização

Salve este checklist antes de iniciar pipelines paralelos em larga escala no Claude Code.

### Checklist de prontidão para lançamento paralelo

- [ ] **Independência das tarefas:** Nenhuma tarefa espera por um artefato intermediário de outro agente paralelo.
- [ ] **Isolamento da escrita em arquivos:** Cada agente escreve dados em seu próprio arquivo novo ou isolado; não há disputa por arquivos de configuração compartilhados.
- [ ] **Formulação estreita dos prompts:** Arquivos de entrada e saída, stack tecnológico e critérios de sucesso estão claramente definidos.
- [ ] **Justificativa econômica:** O benefício da redução do tempo de execução supera os custos da duplicação do contexto base.
- [ ] **Preparação do ambiente:** Todos os diretórios pesados de terceiros foram excluídos do contexto via `.claudeignore`.

### Matriz rápida de seleção de ferramenta

| Tarefa | Abordagem Recomendada | Comando / Método |
| :--- | :--- | :--- |
| **Testes homogêneos em 5+ módulos** | Claude Code Interativo ou CLI `-p` | `claude -p "..." &` |
| **Auditoria multidisciplinar do projeto** | Audit Swarm na sessão | Prompt interativo com 4 agentes |
| **Comparação de bibliotecas/tecnologias** | Research Fan-Out | Consolidação em tabela final |
| **Refatoração profunda do núcleo do sistema** | Sessão Sequencial (Single Session) | Sessão interativa padrão com humano |

---

## 11. Materiais recomendados para próximos passos

Para aprofundar seus conhecimentos sobre o ecossistema Claude e automação de processos, recomendamos nossos novos guias:

- 🚀 [Projetos do Claude Code: como uma IA coordena uma equipe de agentes autônomos →](/uk/guides/ai_agents/claude-code-projects-multi-agent)
- 📊 [Claude + Excel para logística: 10 cenários prontos de auditoria de tarifas e custos →](/uk/guides/ai_base/claude-excel-logistics-playbook)
- ⚡ [Claude + Notion para negócios: automação de CRM e tarefas em 30 minutos →](/uk/guides/ai_base/claude-notion-business-automation)
- 🤖 [Operador de IA Autônomo no Telegram 24/7: arquitetura e 10 cenários de trabalho →](/uk/guides/ai_base/telegram-ai-operator-24-7)