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.

Nota

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

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.
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.
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.

Aviso

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 Збільшити

Arquitetura de lançamento de subagentes do Claude Code e agregação de resultados na sessão principal

Ciclo de vida da execução paralela

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).
Formação de contextos filhos: São criados subagentes separados, cada um recebendo uma tarefa personalizada e o caminho para o arquivo alvo.
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.
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 Збільшити

Contexto compartilhado e isolado dos subagentes: o que está disponível para todos os agentes e o que permanece privado

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)

Importante

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

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 &.

Dica

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

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".
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.
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.
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: