Roteamento de Sub-Agentes

Problema: A sua sessão principal do Claude Code cria sub-agentes o dia todo. Mas ela não tem sentido de quando executá-los lado a lado, quando encadeá-los ou quando mandá-los para segundo plano. Sem regras de roteamento no CLAUDE.md, ela simplesmente escolhe um. E muitas vezes escolhe mal.

Solução rápida: Adicione este bloco de roteamento ao seu CLAUDE.md:

## Sub-Agent Routing Rules
 
**Parallel dispatch** (ALL conditions must be met):
 
- 3+ unrelated tasks or independent domains
- No shared state between tasks
- Clear file boundaries with no overlap
 
**Sequential dispatch** (ANY condition triggers):
 
- Tasks have dependencies (B needs output from A)
- Shared files or state (merge conflict risk)
- Unclear scope (need to understand before proceeding)
 
**Background dispatch**:
 
- Research or analysis tasks (not file modifications)
- Results aren't blocking your current work

A thread principal lê o bloco e começa a fazer distribuições mais inteligentes por conta própria.

A Sua Thread Principal é o Roteador

Aqui está o ponto que a maioria das pessoas não percebe. O Claude Code não é um modelo só. É uma pequena equipa, e o seu chat principal é o líder. Esse líder distribui trabalho a sub-agentes especialistas. Tudo o que vem a seguir só funciona tão bem quanto você ensinou o líder a distribuir trabalho.

Existem três modos de execução na ferramenta Task. Cada um serve um tipo diferente de trabalho:

Sem as regras, o seu líder cai de volta na execução lenta, cuidadosa, um-de-cada-vez. Seguro. Também lento.

Paralelo: Dividir por Domínio

O despacho paralelo serve para trabalho que abrange cantos separados da base de código. Coloque o mapa de domínios no CLAUDE.md para que o líder saiba onde estão as fronteiras:

## Domain Parallel Patterns
 
When implementing features across domains, spawn parallel agents:
 
- **Frontend agent**: React components, UI state, forms
- **Backend agent**: API routes, server actions, business logic
- **Database agent**: Schema, migrations, queries
 
Each agent owns their domain. No file overlap.

A regra rígida: paralelo só funciona quando os agentes tocam ficheiros diferentes. O seu líder tem de ver essas fronteiras de domínio para dividir o trabalho de forma limpa.

Sequencial: Cadeias que Dependem Umas das Outras

Algum trabalho só faz sentido em ordem. O passo dois precisa do que o passo um produziu. O líder tem de manter essa linha.

Liste as suas cadeias comuns no CLAUDE.md. Assim o líder identifica-as e para de tentar executar uma cadeia em paralelo.

Segundo Plano: Investigação que Não Bloqueia

Tarefas de investigação devem cair para segundo plano por conta própria, para você poder continuar a trabalhar. Pressione Ctrl+B durante qualquer execução de sub-agente, ou configure a regra desde o início:

## Background Execution Rules
 
Run in background automatically:
 
- Web research and documentation lookups
- Codebase exploration and analysis
- Security audits and performance profiling
- Any task where results aren't immediately needed

Execute /tasks sempre que quiser ver o que está a correr. Os resultados aparecem quando o agente termina. O guia de fluxos de trabalho assíncronos tem a versão completa.

Configurar o Comportamento dos Sub-Agentes

O roteamento é uma camada. O Claude Code também lhe dá controlos diretos sobre como os sub-agentes se comportam.

Escolher o Modelo do Sub-Agente

CLAUDE_CODE_SUBAGENT_MODEL diz ao Claude Code qual modelo usar para sub-agentes. Esta variável move o dial de custo e velocidade mais do que quase qualquer outra coisa:

# Use a lighter model for sub-agents to save tokens
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"

Uma divisão limpa: Opus na thread principal para o pensamento difícil, Sonnet nos sub-agentes para trabalho de acompanhamento focado. O gasto de tokens cai e o trabalho ainda sai bem, porque cada trabalho de sub-agente já está bem delimitado.

Fixar Especialistas em .claude/agents/

Em vez de criar novas chamadas Task de cada vez, mantenha especialistas nomeados como ficheiros Markdown com frontmatter YAML em .claude/agents/. O orquestrador do Claude encontra-os sozinho.

.claude/agents/ contém agentes de projeto que vivem com o repositório e chegam à sua equipa. ~/.claude/agents/ contém agentes de utilizador que o acompanham em todos os projetos.

Os agentes aqui herdam o seu CLAUDE.md, por isso aparecem já a conhecer as suas convenções, regras de código e particularidades do projeto.

Bloquear Agentes com Regras de Permissão

As regras Task(AgentName) no seu ficheiro de permissões decidem quais sub-agentes têm permissão para correr:

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

A flag --disallowedTools faz o mesmo no lançamento:

claude --disallowedTools "Task(Explore)"

Útil para manter o gasto de tokens controlado, ou para bloquear exploração autónoma num repositório de produção.

Invocações Más São o Bug Real

A maioria dos problemas com sub-agentes não é de execução. É a invocação que os desencadeou. O líder envia um sub-agente com instruções vagas, contexto em falta e sem linha de chegada clara. O sub-agente faz o que pode com o que tem.

Má invocação: "Corrige a autenticação"

Boa invocação: "Corrige o loop de redirecionamento OAuth onde um login bem-sucedido redireciona para /login em vez de /dashboard. Veja o middleware de auth em src/lib/auth.ts."

A diferença é contexto. Sub-agentes correm na sua própria janela de curta duração. Eles não podem voltar a meio da execução e perguntar o que quis dizer. O seu líder precisa de regras rígidas para escrever invocações completas à primeira.

É aqui que muitos ficheiros CLAUDE.md param. O roteamento é tratado. A qualidade da invocação não é. Uma configuração sólida cobre os dois: cada despacho carrega contexto completo, instruções claras, ficheiros ligados e uma definição concreta de concluído.

Erros Comuns de Orquestração

Paralelismo excessivo: Dez agentes paralelos para uma funcionalidade pequena consome tokens e adiciona trabalho de coordenação. Agrupe tarefas pequenas relacionadas num único agente.

Paralelismo insuficiente: Quatro passes independentes a correr em sequência quando podiam ter corrido de uma vez. Procure independência de domínio.

Invocações vagas: "Implementa a funcionalidade" sem âmbito, sem ficheiros, sem output esperado.

O Que Fazer a Seguir

Essas regras de roteamento por si só vão melhorar a forma como o seu líder distribui trabalho. Há mais orquestração de nível avançado em cima disso:

• Requisitos de invocação constitucional que forçam cada despacho a carregar os quatro elementos essenciais
• Tabelas de roteamento de agentes que mapeiam tipos de tarefas a agentes especialistas
• Protocolos de transferência de contexto que carregam estado por uma cadeia sequencial
• Coordenação baseada em sessão para acompanhar trabalho de múltiplos passos

Comece pelas regras de roteamento. Cole-as no CLAUDE.md hoje. O líder vai escolher melhores rotas amanhã. Para padrões mais profundos, leia sobre distribuição de tarefas e fundamentos de agentes.