Como o Claude Code decide qual subagente usar?

Ele lê a descrição de cada subagente disponível e, quando uma tarefa combina com alguma, delega automaticamente àquele subagente. A descrição é o critério de decisão, por isso ela é o campo mais importante: uma descrição clara faz o ajudante certo entrar na hora certa, sem você chamá-lo.

Posso chamar um subagente específico eu mesmo?

Pode. Além da delegação automática, existe a chamada explícita, em que você pede diretamente que um subagente pelo nome cuide da tarefa. É útil quando você sabe exatamente qual ajudante quer. As duas formas convivem: o agente decide na maioria das vezes e você assume quando quer precisão.

Como escrevo uma boa descrição?

De forma clara e específica: diga o que o subagente faz e quando usá-lo, com gatilhos concretos. Evite descrições vagas como revisa código, que não dizem quando acionar. Prefira algo como revisa segurança após mudanças sensíveis. Quanto menos ambígua, mais o Claude Code delega na hora certa.

Um subagente pode burlar minhas permissões?

Não. Quando um subagente executa, as suas ações passam pelas checagens de segurança e pelas permissões que você configurou. Ele opera dentro das suas regras, com o acréscimo de poder ter ferramentas ainda mais restritas. Delegar não afrouxa a segurança; se acaso, a reforça.

E se o Claude Code não estiver delegando ao meu subagente?

Quase sempre o problema está na descrição. Se ela é vaga ou não deixa claro quando usar o subagente, o agente não delega. Torne a descrição mais específica, com gatilhos claros do que o subagente faz e quando. Você também pode sempre chamá-lo explicitamente pelo nome enquanto ajusta.

Módulo 10 - Subagentes

Como o Claude Code decide delegar

7 min de leitura · por Cesar Gargiulo, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 13/07/2026

O que você vai aprender

Entender como a descrição guia a delegação automática.
Chamar um subagente explicitamente quando quiser.
Escrever descrições claras e específicas.
Evitar descrições que confundem a delegação.

A descrição guia a delegação

O que faz um subagente ser útil de verdade não é existir, é ser acionado na hora certa. E o que decide isso é a descrição. O Claude Code lê a descrição de cada subagente disponível e, quando encontra uma tarefa que combina com uma delas, delega automaticamente àquele subagente. É por isso que a descrição é o campo mais importante: ela é o critério de decisão. Um subagente com a descrição revisa código procurando problemas de segurança será acionado quando você pedir uma revisão de segurança, sem você precisar chamá-lo pelo nome. A delegação acontece nos bastidores, guiada por essa correspondência entre a tarefa e a descrição.

Essa delegação automática é o que torna os subagentes tão fluidos. Você não precisa lembrar de acionar cada ajudante; você trabalha normalmente, pedindo tarefas, e o Claude Code aciona o subagente certo quando faz sentido, entregando o resultado na sua conversa. É como ter uma equipe que sabe quando entrar em campo sem você chamar cada um pelo nome. Isso só funciona bem, porém, se as descrições forem claras: se o Claude Code não entende quando usar um subagente, ele não delega, e o ajudante fica esquecido no arquivo. Por isso, escrever boas descrições é a habilidade central deste tema.

Diagrama mostrando o Claude Code recebendo uma tarefa e comparando-a com as descrições de vários subagentes disponíveis. A tarefa combina com a descrição de um deles (o revisor de segurança), e o Claude Code delega automaticamente àquele subagente, que devolve o resultado. — O Claude Code casa a tarefa com a descrição do subagente certo e delega automaticamente.

Delegação automática ou chamada explícita

Há duas formas de um subagente entrar em ação. A automática, que acabamos de ver, é o Claude Code decidindo sozinho pela descrição. A explícita é você pedindo diretamente que um subagente específico cuide de uma tarefa, chamando-o pelo nome. As duas convivem. A automática é ótima para o fluxo do dia a dia, em que você confia no agente para acionar os ajudantes certos. A explícita é útil quando você sabe exatamente qual subagente quer, ou quando quer garantir que aquele ajudante específico, e não outro, faça o trabalho. Ter as duas dá flexibilidade: você deixa o agente decidir na maioria das vezes e assume o controle quando quer precisão.

Delegação automática

O Claude Code decide pela descrição.
Ótima para o fluxo do dia a dia.
Você trabalha normalmente e o ajudante certo entra.

Chamada explícita

Você chama o subagente pelo nome.
Útil quando sabe qual ajudante quer.
Garante que aquele subagente específico atue.

🎮 Jogo da aula

Delegação: verdade ou mito?

Para cada afirmação sobre como o Claude Code delega, diga se é verdadeira ou falsa.

Um detalhe de segurança conecta com o módulo de permissões: quando um subagente executa, as suas ações também passam pelas checagens de segurança, e as permissões que você configurou continuam valendo. Um subagente não é uma porta dos fundos para burlar as suas regras; ele opera dentro delas, com o acréscimo de poder ter as ferramentas ainda mais restritas. Isso significa que delegar não afrouxa a segurança; se acaso, a reforça, porque o subagente pode ter poderes menores que a conversa principal. Você monta a sua equipe de ajudantes com a tranquilidade de que as suas defesas seguem de pé para todos eles.

Escrever descrições que funcionam

Como a descrição decide tudo, escrevê-la bem é a habilidade central. Uma boa descrição diz claramente o que o subagente faz e quando usá-lo, de forma específica. Compare: revisa código é vago demais, e o Claude Code não sabe quando acionar; revisa código procurando problemas de segurança, como senhas expostas e validação de entrada, use após mudanças em partes sensíveis é específica, e o agente sabe exatamente quando delegar. A regra é a mesma dos bons pedidos do módulo da conversa: quanto mais concreta e menos ambígua, melhor. Pense na descrição como o cartão de visitas do subagente: ela precisa dizer, em poucas palavras, o serviço que ele presta e a hora de chamá-lo.

Com a delegação dominada, você entende o ciclo completo do subagente: criar com um bom arquivo, descrever com clareza, e deixar o Claude Code acioná-lo na hora certa, ou chamá-lo você mesmo. A última aula do módulo mostra tudo isso na prática, com exemplos de subagentes úteis e o horizonte do que vem além, formas mais avançadas de vários agentes trabalhando juntos. Você já tem o essencial para montar a sua equipe de ajudantes especializados e colher os quatro benefícios de delegar. Daqui, é questão de identificar as suas tarefas recorrentes e dar a cada uma o seu especialista de plantão.

Teste rápido

Por que a descrição é o campo mais importante de um subagente?

Perguntas frequentes

Como o Claude Code decide qual subagente usar?: Ele lê a descrição de cada subagente disponível e, quando uma tarefa combina com alguma, delega automaticamente àquele subagente. A descrição é o critério de decisão, por isso ela é o campo mais importante: uma descrição clara faz o ajudante certo entrar na hora certa, sem você chamá-lo.
Posso chamar um subagente específico eu mesmo?: Pode. Além da delegação automática, existe a chamada explícita, em que você pede diretamente que um subagente pelo nome cuide da tarefa. É útil quando você sabe exatamente qual ajudante quer. As duas formas convivem: o agente decide na maioria das vezes e você assume quando quer precisão.
Como escrevo uma boa descrição?: De forma clara e específica: diga o que o subagente faz e quando usá-lo, com gatilhos concretos. Evite descrições vagas como revisa código, que não dizem quando acionar. Prefira algo como revisa segurança após mudanças sensíveis. Quanto menos ambígua, mais o Claude Code delega na hora certa.
Um subagente pode burlar minhas permissões?: Não. Quando um subagente executa, as suas ações passam pelas checagens de segurança e pelas permissões que você configurou. Ele opera dentro das suas regras, com o acréscimo de poder ter ferramentas ainda mais restritas. Delegar não afrouxa a segurança; se acaso, a reforça.
E se o Claude Code não estiver delegando ao meu subagente?: Quase sempre o problema está na descrição. Se ela é vaga ou não deixa claro quando usar o subagente, o agente não delega. Torne a descrição mais específica, com gatilhos claros do que o subagente faz e quando. Você também pode sempre chamá-lo explicitamente pelo nome enquanto ajusta.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.

← Criando um subagente Concluir e avançar →