Aprendizado@joaoguirunas

Agentes em Paralelo com Claude Code

Guia completo de orquestração com Claude Code. Subagents, Agent Teams e Dynamic Workflows para tarefas complexas.

O que é

Agentes em Paralelo com Claude Code

Agentes em paralelo no Claude Code permitem que múltiplas instâncias Claude trabalhem simultaneamente no mesmo projeto, dividindo o trabalho por domínio ou por fase. Existem dois modelos principais: subagents — workers reutilizáveis definidos como arquivos de configuração em .claude/agents/ — e Agent Teams, onde uma sessão líder spawna teammates independentes que se coordenam por uma task list compartilhada em disco.

A coordenação entre agentes não acontece por mensagens diretas, mas por estado compartilhado. O arquivo tasks.md age como a camada de sincronização: cada agente lê o arquivo, reivindica uma tarefa disponível marcando-a como "in-progress", executa o trabalho e atualiza o status com o resultado. Essa abordagem elimina race conditions sem exigir locks explícitos e mantém a auditabilidade completa do progresso.

Dynamic Workflows vão além: o próprio Claude gera o script de orquestração sob demanda, distribui subtarefas entre subagents em paralelo e valida resultados por convergência antes de entregar. O custo é 3–4× maior que execução sequencial, mas o tempo de conclusão cai proporcionalmente ao número de tarefas independentes — o modelo certo para migrações em escala, auditorias de segurança e análises de performance.

Como funciona

Principais recursos

Subagents — Workers Reutilizáveis

Defina agentes especializados como arquivos .md em .claude/agents/. Cada subagent herda o contexto do projeto e pode ser invocado com escopo e ferramentas específicos.

Agent Teams — Paralelismo Real

Múltiplas sessões Claude rodando simultaneamente e se coordenando por uma task list compartilhada. Um lead spawna teammates que trabalham em paralelo sem bloqueio mútuo.

Coordenação por Estado, Não por Mensagem

Agentes leem e escrevem em um arquivo compartilhado (tasks.md). Cada teammate reivindica uma tarefa atualizando o status para "in-progress" — sem colisão, sem locks explícitos.

Dynamic Workflows — Orquestração sob Demanda

Claude analisa o objetivo, gera o script de orquestração, distribui subtarefas em paralelo e valida resultados antes de entregar. Ideal para migrações, auditorias e análises complexas.

Modelo de Seleção por Tarefa

Configure CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-4-6 para subagents focados enquanto a sessão principal roda Opus 4.8 — otimizando custo sem sacrificar qualidade na orquestração.

Execução Assíncrona em Background

Subagents podem rodar em background enquanto você continua trabalhando com o Claude principal. Use worktrees para isolar mudanças de código entre agentes concorrentes.

Tutorial

Orquestrando Agentes em Paralelo

1. Habilitar Agent Teams

# Via variável de ambiente (sessão atual)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Via settings.json (persistente)
# ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

# Versão mínima necessária: Claude Code v2.1.32+
# Modelo mínimo: Opus 4.6+

2. Definir Subagents Reutilizáveis

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Audita o código por vulnerabilidades de segurança
tools: [Read, Bash, WebSearch]
---

Você é um revisor de segurança especializado.
Analise o código fornecido verificando:
- Injeção SQL e XSS
- Exposição de credenciais
- Validação de entrada
- Autenticação e autorização

Reporte cada vulnerabilidade com: arquivo, linha, severidade e correção sugerida.

3. Spawnar um Time de Agentes em Paralelo

# Prompt para o Claude Code (com Agent Teams habilitado):

"Crie um time de agentes para revisar o sistema de autenticação.
Spawne três teammates em paralelo:

- security-reviewer: audite vulnerabilidades em src/lib/auth.ts
  e src/middleware/. Verifique token handling e session storage.

- performance-analyst: profile os endpoints de login e refresh.
  Identifique queries N+1 e bottlenecks de latência.

- test-coverage: verifique edge cases não cobertos em __tests__/auth/.
  Liste cenários de falha sem teste unitário.

Cada teammate deve reportar findings no shared task list.
Ao concluir, consolide os resultados e peça shutdown a todos."

4. Task List Compartilhada — Coordenação por Estado

# tasks.md — arquivo de coordenação gerado automaticamente

## Tarefas Ativas

| ID  | Tarefa                        | Status      | Agente             | Output |
|-----|-------------------------------|-------------|--------------------|--------|
| T-1 | Audit auth.ts vulnerabilities | in-progress | security-reviewer  | —      |
| T-2 | Profile /api/auth/login       | pending     | —                  | —      |
| T-3 | Check test coverage auth/     | in-progress | test-coverage      | —      |
| T-4 | Consolidar findings           | blocked:T1  | —                  | —      |

# Cada agente:
# 1. Lê o arquivo e encontra uma tarefa "pending"
# 2. Atualiza status para "in-progress" com seu nome
# 3. Executa a tarefa
# 4. Atualiza status para "completed" com resumo do output

5. Otimizar Custo com Modelo por Subagent

# Sessão principal: Opus 4.8 (orquestração e decisões complexas)
# Subagents: Sonnet 4.6 (execução e tarefas focadas)

export CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-4-6

# Ou configure por agente no .claude/agents/meu-agente.md:
---
name: meu-agente
model: claude-sonnet-4-6
description: Agente focado em análise de logs
---

# Navegação entre teammates ativos:
# Shift+Up / Shift+Down  → selecionar teammate
# Ctrl+T                  → ver task list compartilhada
# Enter                   → abrir sessão do teammate
# Escape                  → interromper operação

6. Dynamic Workflows — Orquestração Automática

# Ativar modo ultracode (Claude decide quando usar workflows)
# Em settings.json:
{
  "ultracode": true
}

# Ou acionar explicitamente no prompt:
"Use Dynamic Workflows para migrar todos os endpoints REST
em src/api/ de Express 4 para Hono. O workflow deve:
1. Mapear todos os arquivos com endpoints (paralelo)
2. Converter cada arquivo independente em paralelo
3. Atualizar imports e middleware compartilhado (sequencial)
4. Rodar a suite de testes e validar resultados

Aviso: workflows consomem substancialmente mais tokens
que execução sequencial. Comece com tarefas menores."

Comece agora

Explore o repositório, contribua ou integre na sua operação.

Conhecer Claude Code