Subagentes do Claude Code: estrutura, cinco funções e orquestração

O que é um subagente no Claude Code e porque não é «apenas mais uma Skill»?#

A documentação do Claude Code define-o assim:

Em termos que um empresário compreenderia: imagine uma agência imobiliária. Há um diretor, um profissional de marketing, um advogado e gestores comerciais. Um funcionário que alterna entre todas estas funções não é uma equipa; é uma pessoa sobrecarregada. Uma equipa forma-se quando cada pessoa tem o seu próprio contexto e área de responsabilidade, enquanto o diretor apenas atribui tarefas e reúne os resultados.

Os subagentes no Claude Code funcionam da mesma forma. O chat principal é o diretor. Um subagente é um especialista com uma tarefa específica, o seu próprio contexto e conjunto de ferramentas. Quando uma tarefa corresponde à descrição de um especialista, o diretor delega-a — sem se perder nos pormenores.

5 objetivos para os quais a Anthropic criou os subagentes

A documentação da Anthropic enumera exatamente cinco motivos para criar o seu próprio subagente:

O item mais prático desta lista para quem não programa é o controlo de custos. Pode enviar uma tarefa de investigação exigente para o modelo económico Haiku e continuar a conversa principal no Sonnet ou no Opus. A poupança de tokens é diretamente proporcional.

Verifique o suporte de aninhamento na versão instalada

Os modelos deste guia usam uma sessão principal que delega diretamente nos agentes de trabalho. Não trate documentação antiga que diz «subagentes não podem criar subagentes» como regra intemporal: o aninhamento depende da versão instalada e das ferramentas permitidas. O guia separado de subagentes aninhados apresenta uma receita específica de versão. Verifique o suporte na sua instalação antes de planear delegação mais profunda.

Em que difere um subagente de uma Skill, de um comando de barra e de um hook?#

O guia anterior sobre Skills explica que as Skills e os comandos de barra no Claude Code se fundiram, na prática, num único formato. Mas um subagente é uma entidade diferente — não é simplesmente «uma Skill maior».

Tabela-resumo dos quatro mecanismos:

Uma boa forma de resumir isto é: as Skills são receitas; os subagentes são colegas especializados.

Em poucas palavras: as Skills são como receitas; os subagentes são como colegas especializados.

Na prática, funciona assim: as Skills são ativadas automaticamente quando a sua descrição corresponde à tarefa, enquanto os subagentes são invocados explicitamente — ou o chat principal decide delegar, ou chama um deles pelo nome.

Árvore de decisão: «Qual devo escolher?»

Quando pensar «Preciso que o Claude faça X», passe por estas quatro perguntas:

1. É conhecimento que deve estar sempre disponível? Por exemplo, «localizamos para o idioma preferido do utilizador» ou «não usamos travessões». Coloque-o no CLAUDE.md.
2. É uma metodologia acionada que atualmente executa manualmente? Por exemplo, «escrevo um relatório comercial todas as segundas-feiras». Crie uma Skill.
3. É uma tarefa que vai consumir o contexto do chat principal ou que pode ser executada em paralelo? Por exemplo, «investigação aprofundada em 30 fontes» ou «uma auditoria de segurança enquanto escrevo uma nova funcionalidade». Crie um subagente.
4. Precisa de uma resposta automática a um evento no Claude Code? Por exemplo, «executar o linter depois de cada Edit». Escreva um hook.

90% das tarefas de um empresário enquadram-se nas duas primeiras categorias. Os subagentes são uma ferramenta de nível seguinte, para quando se passa de «uma tarefa de cada vez» para a orquestração.

Onde ficam os subagentes e qual deles tem precedência?#

A hierarquia dos subagentes tem cinco níveis, por ordem decrescente de prioridade:

A lógica de prioridade é a mesma que para as Skills e o CLAUDE.md: a organização sobrepõe-se ao CLI, o CLI ao projeto, o projeto às definições pessoais e as definições pessoais ao plugin.

O que deve saber sobre o carregamento

Os subagentes são carregados quando uma sessão do Claude Code é iniciada. Se editar manualmente um ficheiro de agente no disco, as alterações só serão aplicadas depois de reiniciar a sessão. As edições através da interface interativa /agents são aplicadas imediatamente.

Há um ficheiro por subagente e por âmbito. Se .claude/agents/ contiver code-reviewer.md e outro code-reviewer.md ao lado (por exemplo, de uma cópia de segurança antiga), o Claude Code ignorará um deles sem avisar. Não será apresentada qualquer notificação.

Os subagentes de plugins são um caso à parte. Têm restrições de segurança: não suportam os campos hooks, mcpServers e permissionMode. Isto impede que a instalação de um plugin de terceiros lhe dê permissão para executar código arbitrário no seu computador.

Estrutura do ficheiro de um subagente: frontmatter e corpo#

Um exemplo mínimo da documentação oficial — apenas 9 linhas:

---
name: code-reviewer
description: Analisa a qualidade do código e as boas práticas
tools: Read, Glob, Grep
model: sonnet
---

És um revisor de código. Quando fores invocado, analisa o código e fornece
comentários específicos e acionáveis sobre a qualidade, a segurança e as boas práticas.

É suficiente. Se um utilizador disser «analisa o meu PR» no chat principal, o Claude associa «revisor / código / qualidade» à descrição e delega a tarefa ao subagente. O subagente lê o diff, produz comentários e devolve um resumo ao chat principal. O chat principal não fica sobrecarregado com registos e análises intermédias.

Esquema completo do frontmatter

O campo model: haiku representa exatamente aquele «controlo de custos» da lista dos cinco objetivos. Se tiver um agente de investigação que lê 50 páginas de documentação, execute-o com Haiku para poupar 5–7 vezes em comparação com o Opus.

O campo isolation: worktree resolve um problema importante: um subagente faz alterações potencialmente perigosas (refatorização, migração), mas não quer que estas afetem a sua cópia de trabalho. Defina isolation: worktree, e o Claude Code cria uma cópia temporária do projeto em git; o subagente trabalha nessa cópia e devolve um diff para revisão.

O corpo do ficheiro é o prompt de sistema

Depois do frontmatter vem Markdown normal — o prompt de sistema do subagente. Não é necessária uma estrutura especial, mas este padrão é comprovado:

1. Quem és — uma frase: «és um revisor de código», «és um auditor de segurança», «és um responsável pela documentação».
2. Quando és invocado e o que fazes primeiro — as primeiras 2–3 ações depois de receber a tarefa.
3. Uma lista de verificações ou passos — 5–10 pontos que o subagente deve seguir.
4. O que devolves — o formato do relatório final. É essencial: se não especificar um formato, o subagente produzirá um «ensaio» em vez de um resumo estruturado.
5. O que NÃO fazes — limitações explícitas. Sem esta secção, o subagente acaba por improvisar.

Mantenha o corpo do ficheiro entre 200–500 linhas. Se ficar mais longo, transfira as referências extensas para ficheiros separados nas proximidades e indique-os no prompt.

Como escrever uma descrição para que o Claude invoque certamente o seu subagente#

Um problema comum é configurar um subagente para rever código e o Claude acabar por fazer tudo sozinho, sem o utilizar. Normalmente, há um único motivo: a descrição foi escrita como «Ajuda para revisão de código». O Claude não percebe quando deve acioná-lo.

Fórmula para uma descrição eficaz (3 partes)

Parte 1 — o que faz. Uma frase sobre o resultado, não o processo. Não «analisa código», mas «encontra vulnerabilidades no código e devolve uma lista com a respetiva gravidade e uma correção».

Parte 2 — quando o acionar. 3–5 frases entre aspas, tal como os utilizadores realmente fazem os pedidos. Não tente adivinhar — consulte o histórico do chat e a formulação real dos pedidos.

Parte 3 — quando NÃO o acionar. 1–2 frases sobre tarefas semelhantes às quais este subagente não deve responder. Sem esta secção, dois agentes semelhantes estarão constantemente em conflito.

A expressão mágica «Use Proactively»

A documentação oficial da Anthropic faz uma recomendação direta:

Por outras palavras, se a descrição não contiver indicações claras, por predefinição o Claude tende a não invocar um subagente. Acrescente «use proactively» ou «use immediately after writing code» e a ativação aumenta bastante.

Uma boa descrição é assim

description: |
  Especialista em revisão de código. Revê proativamente a qualidade,
  a segurança e a facilidade de manutenção do código. Utilizar imediatamente após escrever ou
  modificar código. Devolve uma lista de problemas ordenada por prioridade, com a gravidade
  e recomendações de correção.
  Não invocar para alterações à documentação, edições do README ou reescrita de mensagens
  de commit — estas são tratadas pelo doc-maintainer.

O que funciona aqui:

• Os verbos «revê» + «devolve» especificam um resultado concreto, não um processo.
• «Proativamente» e «imediatamente após» são acionadores explícitos.
• «Não invocar para...» evita conflitos com um subagente semelhante.
• É comum escrever a descrição em inglês. O Claude associa melhor as expressões em inglês.

5 funções de subagente prontas a usar, que ficam operacionais em 10 minutos#

Cada função abaixo corresponde a um único ficheiro, .claude/agents/<name>.md. Depois de criar o ficheiro, reinicie o Claude Code, abra /agents e confirme que o novo agente aparece na lista. Depois, pode invocá-lo com @agent-name.

1. code-reviewer — rever o código após cada alteração

Este é o exemplo oficial da documentação da Anthropic, adaptado a um processo de trabalho:

---
name: code-reviewer
description: |
  Especialista em revisão de código. Revê proativamente a qualidade,
  a segurança e a facilidade de manutenção do código. Utilizar imediatamente após escrever ou
  modificar código.
tools: Read, Grep, Glob
model: inherit
color: blue
---

És um revisor de código sénior que garante padrões elevados de qualidade do código.

Quando fores invocado:
1. Lê o diff e a lista de ficheiros alterados fornecidos pela sessão principal. Se faltarem, pede à sessão principal que os forneça.
2. Usa Read, Grep e Glob para inspecionar os ficheiros pertinentes.
3. Devolve as conclusões sem alterar ficheiros nem executar comandos de shell.

Lista de verificação:
- O código é claro e legível
- As funções e variáveis têm nomes adequados
- Não há código duplicado
- O tratamento de erros é adequado
- Não há segredos nem chaves de API expostos
- A validação de dados de entrada está implementada
- A cobertura de testes é adequada
- Os aspetos de desempenho foram considerados

Apresenta o feedback por prioridade:
- Problemas críticos (têm de ser corrigidos antes da integração)
- Avisos (devem ser corrigidos)
- Sugestões (ponderar melhorias)

Formato: para cada problema — ficheiro:linha + 1 frase a explicar o problema + correção concreta.

O essencial é tools: Read, Grep, Glob: o revisor tem ferramentas de leitura e pesquisa, sem Bash, Write ou Edit. A sessão principal prepara o diff e entrega-o ao revisor. Dizer a um agente para executar apenas git diff não restringe uma ferramenta Bash concedida por completo.

2. security-auditor — encontrar vulnerabilidades e fugas

Esta função usa opus para raciocínio mais aprofundado e a mesma restrição a Read, Grep e Glob. O modelo só de leitura omite memória persistente, porque ativar a memória do agente também lhe dá capacidade de escrever notas:

---
name: security-auditor
description: |
  Especialista em auditoria de segurança. Utilizar proativamente para encontrar
  vulnerabilidades OWASP Top 10, segredos expostos, riscos de injeção e falhas de autenticação.
  Executar antes de qualquer implementação ou integração na branch main.
tools: Read, Grep, Glob
model: opus
color: red
---

És um auditor de segurança. Procura vulnerabilidades exploráveis, não problemas de estilo.

Lista de verificação:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- Riscos de CSRF / SSRF
- Segredos codificados diretamente (chaves de API, tokens, palavras-passe)
- Falhas de autenticação / gestão de sessões
- Desserialização insegura
- Falta de validação de dados de entrada
- Path traversal
- Redirecionamentos abertos
- Referências diretas inseguras a objetos (IDOR)

Para cada descoberta:
- Gravidade: Critical / High / Medium / Low
- Ficheiro:linha
- Cenário de ataque em 1–2 frases
- Recomendação de correção com exemplo de código

Ignora o ruído do linter e de estilo. Comunica apenas problemas exploráveis.

As ferramentas são apenas de leitura, e model: opus destina-se a verificações complexas, como cadeias de vulnerabilidades.

3. research-agent — investigação aprofundada em 8+ fontes

Este padrão é descrito pela própria Anthropic no seu artigo sobre o sistema de investigação multiagente. O essencial é definir explicitamente o formato de saída e proibir a apresentação de resultados em bruto:

---
name: research-agent
description: |
  Especialista em investigação aprofundada na web. Utilizar proativamente para apurar factos,
  fazer análise da concorrência, recolher documentação externa e comparar
  abordagens em várias fontes.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

És um analista de investigação. Objetivo: síntese, não resultados de pesquisa em bruto.

Processo:
1. Divide a questão em 3–5 consultas secundárias
2. Utiliza WebSearch em cada consulta e obtém as 3–5 principais fontes por consulta
3. Verifica as afirmações em pelo menos 2 fontes independentes
4. Rejeita conteúdos de quintas de SEO e agregadores; dá preferência a fontes primárias
5. Cita literalmente as afirmações específicas e atribui-lhes um URL
6. Devolve: TL;DR (3 tópicos) + Conclusões + Fontes (mínimo de 8 domínios)

Antipadrões a evitar:
- Não cites um facto com base numa única fonte
- Não parafraseies citações como se fossem literais
- Não devolvas ao agente principal listas de resultados de pesquisa em bruto
- Não incluas introduções ou conclusões de enchimento ("Espero que ajude")

maxTurns: 30 é uma salvaguarda contra a investigação entrar em iterações intermináveis. A Anthropic refere este valor no seu sistema multiagente:

Os noventa por cento referem-se a tarefas de referência de investigação. Na prática, o ganho é menor em tarefas empresariais, mas a escala geral é semelhante.

4. doc-maintainer — manter a documentação sincronizada com o código

Esta função utiliza model: haiku — um exemplo típico de «controlo de custos». A documentação não exige o Opus; o Haiku dá conta do trabalho por um terço do preço:

---
name: doc-maintainer
description: |
  Especialista em sincronização da documentação. Atualiza o README, a documentação da API e o
  CHANGELOG após a integração de funcionalidades. Lê os commits recentes, identifica
  alterações não documentadas e atualiza a documentação proativamente.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

Manténs a documentação sincronizada com o código.

Quando fores invocado:
1. Executa `git log --since="last release"` para ver as alterações recentes
2. Lê README.md, docs/, CHANGELOG.md
3. Identifica lacunas: novas funcionalidades sem documentação, APIs removidas ainda
   documentadas e incompatibilidades de versões

Resultado:
- Ficheiros atualizados (utiliza Edit, não Write — preserva a estrutura existente)
- Entrada no CHANGELOG.md no formato Keep-A-Changelog
- Lista das alterações efetuadas (resumo do diff real, não uma paráfrase)

Regras de estilo:
- Voz ativa, presente do indicativo
- Os exemplos de código têm de poder ser copiados e colados
- Sem linguagem de marketing ("powerful", "robust", "seamless")
- Sem enchimento ("Este guia vai ajudar-te...")

5. refactor-agent — refatorização segura através de um worktree

Esta função utiliza isolation: worktree — o subagente trabalha numa cópia separada do repositório e só faz a integração se estiver tudo bem:

---
name: refactor-agent
description: |
  Especialista em refatorização segura. Utilizar para renomeações, extrações e incorporações
  que não devem afetar a cópia de trabalho antes da revisão. Funciona num
  git worktree temporário.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

Refatorizas código sem alterar o seu comportamento.

Regras rigorosas:
1. Os testes têm de passar ANTES e DEPOIS da refatorização.
   Se os testes falharem antes da refatorização, PARA e comunica o problema.
2. Uma refatorização atómica por commit (extração, renomeação, incorporação).
3. Nunca alteres APIs públicas sem instruções explícitas.
4. Nunca alteres testes, exceto se testarem diretamente a implementação refatorizada.

Processo:
- Executa a suite de testes → estado de referência
- Faz uma refatorização atómica
- Executa a suite de testes → verificação
- Cria um commit com uma mensagem convencional: refactor(scope): what

Devolve: resumo das alterações + caminho do worktree para que o utilizador possa comparar e integrar.

Com esta função, o problema mais doloroso da refatorização — «estraguei algo e não sei como reverter» — desaparece: a cópia original permanece intacta e o subagente trabalha isoladamente.

Quer não só copiar subagentes prontos a usar, mas também montar uma combinação que transforme o Claude numa ferramenta estável? Os subagentes fazem parte do seu clone de IA: uma forma de dar ao Claude uma equipa especializada que trabalha segundo a sua lógica. Os três pilares da metodologia são: clone de IA (Skills + Subagents) + Segundo Cérebro + Context Engineering. Esta combinação transforma o Claude de um assistente que adivinha numa ferramenta que pensa segundo a sua lógica.

Lançar 5 subagentes em paralelo: orquestrador + executantes#

A orquestração em paralelo funciona como um «maestro + orquestra». O maestro tem o plano, não escreve as partituras e verifica o que os músicos tocam. Se alguém tocar uma nota errada, o maestro pede-lhe que a toque novamente em vez de tentar terminar o trabalho no seu lugar.

Para um empresário, uma analogia mais próxima é uma agência de marketing a preparar uma estratégia para um novo cliente. Um analista faz uma análise SWOT, outro analisa a concorrência, um terceiro cria um perfil do público, um analista sénior elimina as hipóteses que não se enquadram no orçamento e o gestor de projeto reúne a apresentação final. No Claude Code, este processo começa com uma frase — e o crítico está integrado no processo desde o início, em vez de aparecer depois.

Prompt mínimo de orquestração

Uma frase no chat principal é suficiente:

Lança cinco subagentes em paralelo: três research-agents para diferentes fontes
(documentação da Anthropic, repositórios do GitHub, autores sobre IA), um critic-agent para filtrar
conclusões fracas e um summary-agent para o documento final.

Contexto: Estou a escrever um guia sobre X. Extensão pretendida: 2,000 palavras com fontes.
Antes de começar, cada um lê o CLAUDE.md.

O Claude delega então as tarefas aos cinco agentes. Cada um trabalha no seu próprio contexto: os agentes de investigação utilizam as respetivas fontes, o crítico filtra e o agente de síntese reúne o material. Só os resumos finais regressam ao chat principal.

Quando compensa trabalhar em paralelo

Não em todos os casos. A execução em paralelo só faz sentido quando:

1. As tarefas são independentes. Se o research-agent #2 estiver à espera do resultado do research-agent #1, não haverá paralelismo — na prática, trabalharão sequencialmente.
2. As tarefas demoram muito tempo. Não vale a pena paralelizar «remover espaços em branco no final das linhas»; o custo de lançar subagentes anula o benefício.
3. Tem limites suficientes. Mais informações na secção dedicada abaixo — os subagentes em paralelo consomem tokens rapidamente.

Multi-Agent v2 da Anthropic: um passo adiante

Em maio de 2026, a Anthropic lançou o Multi-Agent Orchestration v2, com três diferenças importantes em relação à abordagem clássica de lançar subagentes em paralelo. Mais informações na secção seguinte.

Novidades no Multi-Agent v2: orquestração, resultados e Dreaming#

Multi-Agent Orchestration: sistema de ficheiros partilhado + verificações a meio do fluxo de trabalho

A Anthropic descreve a funcionalidade assim:

A principal diferença em relação aos subagentes clássicos é o sistema de ficheiros partilhado. Antes, cada subagente trabalhava em completo isolamento, e a troca de informação ocorria apenas através do resumo devolvido. Agora, os especialistas podem escrever numa pasta partilhada e o agente principal pode consultar os resultados à medida que o trabalho avança, não apenas no fim. Isto resolve o problema de «todos trabalharam o dia inteiro e, no final, descobriu-se que duas pessoas tinham abordagens incompatíveis».

Em segundo lugar, há verificações a meio do fluxo de trabalho. O agente principal pode parar e perguntar a qualquer especialista «como está a correr», e depois ajustar o plano geral. É semelhante à forma como trabalha um verdadeiro gestor de equipa.

Outcomes: critérios de avaliação em vez de instruções passo a passo

Com a funcionalidade Outcomes, define os critérios de sucesso e o agente encontra uma forma de os cumprir. Um agente avaliador independente verifica o resultado no seu próprio contexto, para que não seja «contaminado» pelo raciocínio do agente principal.

Dez por cento em tarefas difíceis é um ganho significativo. Sobretudo quando a tarefa é formulada como «produzir um artigo extenso que cumpra estes critérios de qualidade», em vez de «seguir os passos 1–7».

Dreaming: os agentes acumulam experiência entre sessões

Esta é a funcionalidade mais inovadora do ponto de vista conceptual. Um agente percorre sessões anteriores, identifica padrões nos sucessos e nos erros e atualiza o repositório de memória. Pode configurar uma revisão manual antes de aplicar as alterações ou permitir que o próprio agente edite a memória.

A Anthropic refere que a Harvey (uma empresa de tecnologia jurídica) registou um aumento de cerca de seis vezes no sucesso de tarefas de redação jurídica após implementar a Dreaming. Já está a funcionar em produção, não é apenas uma demonstração.

O que significa para empresários que não programam

A Multi-Agent Orchestration está atualmente disponível através do Claude Agent SDK, e não diretamente na CLI do Claude Code. Mas a direção é clara: a orquestração está a passar de «lança manualmente N subagentes» para «descreve a tarefa e o agente principal decide a quem delegar e como». Se está a começar agora com subagentes, não se preocupe ainda com o v2. Aprenda o padrão clássico de «1 chat principal + 3–5 subagentes com funções diferentes» e, dentro de 3–6 meses, poderá passar naturalmente para o Managed Agents.

7 erros que impedem os subagentes de funcionar#

Erro 1. As descrições «Ajuda com X» não acionam o subagente

Sintoma: escreveu um subagente, verificou a estrutura e está tudo válido, mas o Claude não o invoca em resposta aos pedidos do utilizador. O motivo é quase sempre o mesmo: a descrição é abstrata, como «Ajuda na revisão de código». A solução: escreva na descrição 3–5 frases reais dos utilizadores entre aspas e acrescente «use proactively» / «use immediately after».

Erro 2. Criar um subagente quando é necessária uma Skill

Um subagente custa mais do que uma Skill — cria o seu próprio contexto, carrega o seu próprio prompt de sistema e utiliza mais tokens. Se uma tarefa for curta, não consumir o contexto principal e puder ser concluída numa única passagem, deve ser uma Skill, não um subagente. Exemplo de antipadrão: um subagente format-validator que verifica um esquema JSON com base em 20 regras. Deve ser uma Skill: um modelo, sem necessidade de isolamento e sem carregar contexto adicional.

Erro 3. Lançar «60 agentes em paralelo» logo de início

Esta é a ilusão mais comum. Vê um tweet a dizer «tenho 1,500 agentes a trabalhar» e pensa «também devia fazer isso». Na prática, 60 agentes esgotam os limites de um plano Pro numa hora, geram uma pilha de resultados contraditórios e, no fim do dia, não tem nada concluído.

Um profissional no Medium descreve a situação assim:

A solução: comece com um subagente para uma tarefa. Depois de dominar esse processo, adicione um segundo com uma função diferente. Quando souber orquestrar dois, passe para uma equipa de 3–5. Saltar de «instalei o Claude Code ontem» para «hoje tenho 20 em paralelo» vai certamente quebrar o código e esgotar os limites.

Erro 4. Dar todas as ferramentas a todos os agentes

Se o seu revisor de código tiver acesso a Bash, Write e WebFetch, isso representa uma enorme falha de segurança e de custos. Um revisor não deve ter permissão para escrever ficheiros, muito menos acesso à Internet.

A solução: limite rigorosamente tools. Um revisor de código recebe apenas Read, Grep, Glob. Um auditor de segurança recebe as mesmas ferramentas de leitura/pesquisa e um diff fornecido pela sessão principal. Acrescentar Bash concede capacidade de shell; não restringe automaticamente o agente a git diff. Um agente de investigação recebe WebFetch, WebSearch, Read, Write. Não dê a um subagente mais permissões do que as necessárias para uma tarefa específica.

Erro 5. Um subagente despeja resultados em bruto no contexto principal

Se um agente de investigação devolver «aqui estão as 30 páginas que encontrei; descobre tu» ao chat principal, perdeu a principal vantagem dos subagentes: o isolamento do ruído. A solução: exija explicitamente um formato de saída no prompt de sistema do subagente. «Devolve APENAS: TL;DR com 3 tópicos + lista de 5 fontes. SEM blocos de código, SEM resultados de pesquisa em bruto.» O formato deve ser rigoroso — o subagente não deve ter liberdade para «transformá-lo num ensaio».

Erro 6. Instruções vagas: pedidos de delegação pouco claros

Um subagente não consegue ver o histórico do diálogo principal. Começa com um contexto limpo + CLAUDE.md + aquilo que lhe escreveu explicitamente. Se escrever «corrige a autenticação», o subagente vai inventar coisas. Em vez disso: «Corrige o ciclo de redirecionamento OAuth em que, após um início de sessão bem-sucedido, o utilizador é redirecionado para /login em vez de /dashboard. Ficheiro: src/lib/auth.ts.»

Uma regra clara: ao delegar, dê ao subagente tanto contexto como daria a um novo prestador de serviços que acabou de entrar no projeto.

Erro 7. Agentes baseados em funções em vez de tarefas

Um padrão tentador é: «vamos criar um frontend-developer, um backend-developer e um qa-engineer e pô-los a trabalhar em equipa». Não funciona. Cada «função» perde o contexto do projeto como um todo e os agentes não conseguem chegar a acordo sobre os detalhes porque não se conseguem ver uns aos outros.

A solução: um subagente deve tratar de uma tarefa recorrente com um resultado claro, não assumir uma função. Não «frontend-developer», mas «explore-ui-tree», «refactor-component», «audit-accessibility». Cada subagente baseado numa tarefa executa um trabalho específico e devolve um resultado específico.

Quanto custam os subagentes em paralelo e quando compensam?#

Um plano Pro esgota-se numa hora se lançar 5 subagentes em paralelo para tarefas complexas. O Max 5x ($100) é o mínimo realista para trabalho regular em paralelo. Para equipas e para o plano Enterprise, a questão do dinheiro já está resolvida ao nível do orçamento para ferramentas.

Para mais informações sobre como poupar tokens no Claude Code, consulte o guia separado sobre limites. Para os subagentes, a regra fundamental é que compensam numa tarefa que exija pelo menos 10 minutos de trabalho concentrado. Se a tarefa for mais curta, não crie um subagente; faça-a no chat principal ou com uma Skill.

Como integrar subagentes no seu clone de IA e Segundo Cérebro?#

Antes de criar o primeiro especialista, o seu projeto deve incluir três elementos dos quais um subagente depende:

1. O CLAUDE.md adequado. Um subagente lê o CLAUDE.md antes de começar — é o seu «contrato de trabalho». Sem ele, não conhece o contexto do projeto, as suas restrições nem o seu tom. Vai inventar coisas.

2. Skills básicas. Uma Skill é uma metodologia empacotada. Um subagente carrega apenas as Skills de que precisa, não tudo de uma vez. Sem Skills, repete sempre o mesmo trabalho de raiz.

3. Segundo Cérebro: uma estrutura de conhecimento. A pasta business/ (ou o seu equivalente na sua área) é uma biblioteca consultada por todos os subagentes. Sem ela, o subagente dá uma resposta média do ChatGPT, indistinguível da de qualquer outra pessoa.

Inverter esta ordem significa entusiasmo sem resultados. «Tenho 60 subagentes em paralelo» com uma pasta business/ vazia significa ter 60 sessões médias do ChatGPT com a mesma abordagem.

A combinação completa — clone de IA + Segundo Cérebro + Context Engineering — constitui os três pilares que tornam o Claude consistente. Os subagentes fazem parte do clone de IA: uma forma de dar ao Claude uma equipa especializada que trabalha segundo a sua lógica.

A forma mais rápida de começar é copiar code-reviewer do primeiro exemplo acima para .claude/agents/code-reviewer.md, reiniciar o Claude Code e invocar @agent-code-reviewer no próximo commit. Em 5 minutos, saberá se precisa de subagentes ou se o chat principal é suficiente.