Sub-agents no Claude Code: quando compensam — e quando não

Imagine o Claude Code como um consultor com uma pequena equipa. Fala apenas com o consultor. Ele encaminha as subtarefas para especialistas e, no fim, comunica-lhe o resultado.

É exatamente isso que são os sub-agents. Não é hype, é uma ferramenta prática de divisão do trabalho. Este artigo mostra quando compensam — e quando não.

O que é um sub-agent

A sessão principal é o orquestrador. É a instância com quem fala. É ela que arranca sub-agents autónomos e lhes atribui tarefas.

Cada sub-agent trabalha num contexto próprio e novo. Devolve apenas um resultado compacto. Os sub-agents falam com a sessão principal, nunca entre si.

Porque compensam

Há quatro razões que tornam os sub-agents úteis.

• Contexto limpo. A pesquisa, os registos longos e os relatórios extensos ficam fora do chat principal.
• Trabalho em paralelo. Muitas tarefas independentes correm ao mesmo tempo em vez de umas atrás das outras.
• Modelos baratos. O trabalho de rotina fica a cargo de um modelo pequeno, a direção a cargo de um modelo forte.
• Revisões honestas. Um agente novo não está condicionado a concordar consigo.

Integrados ou construídos por si

O Claude Code traz sub-agents genéricos. Além disso, pode construir agentes próprios e especializados. Um sub-agent não é mais do que um ficheiro Markdown.

No topo está o frontmatter YAML: nome, descrição, modelo e ferramentas permitidas. A descrição é a alavanca mais importante. É ela que decide se o agente serve para a tarefa.

Um erro frequente na prática é uma aspa esquecida. A estrutura parte-se e o agente nunca chega a arrancar.

Ao nível do projeto ou global

Os agentes ligados ao projeto ficam no repositório e viajam com ele. Os agentes globais ficam na sua pasta de utilizador e pertencem apenas a si.

Regra prática: se a equipa o vai usar, pertence ao projeto. Movê-lo é trivial, afinal é apenas um ficheiro.

Quando usar um sub-agent — e quando não

Nem todas as tarefas precisam de um sub-agent. Demasiados conduzem muitas vezes a piores resultados. Uma pergunta simples ajuda.

Isto vai despejar já uma montanha de informação no meu chat que nunca mais volto a ler? Se sim, delegue. Se não, fica na sessão principal.

Use sub-agents quando forem lidos muitos ficheiros, quando houver tarefas a correr em paralelo ou quando quiser uma revisão imparcial.

Prescinda deles em alterações pequenas, em passos que dependem uns dos outros ou quando o agente teria de fazer uma pergunta de esclarecimento.

Fluxos de trabalho dinâmicos e «ultra code»

Desde o Opus 4.8 existem fluxos de trabalho dinâmicos. A sessão principal arranca então automaticamente muitos sub-agents em paralelo. É poderoso, mas consome depressa o seu limite de sessão.

Foi por isso que a palavra-gatilho mudou de «workflow» para «ultra code». Assim, nenhum fluxo de trabalho grande arranca por engano. Use a ferramenta de forma consciente.

Levar as permissões a sério

Se um agente pode ler ou alterar dados, tem de partir do princípio de que um dia o fará. Por isso, liberte apenas as ferramentas de que ele realmente precisa.

Para agentes de pesquisa e de verificação isso significa, na maior parte dos casos: só leitura. Em ficheiros de agentes de origem externa, verifique previamente possíveis prompt injections.

A minha promessa

Os sub-agents não são um fim em si mesmos. São uma ferramenta de divisão do trabalho. O ganho é menos ruído no chat, custos mais baixos e um olhar imparcial sobre o seu trabalho.

A minha promessa: só recomendo sub-agents onde ajudem de forma mensurável. A automatização é mais do que hype de IA.

Nota: este artigo resume as ideias centrais de um vídeo do YouTube em inglês sobre os sub-agents do Claude Code e enquadra-as numa perspetiva de consultoria. Fonte: youtube.com/watch?v=e18sdZLwP7o.