Subagentes no Claude Code permitem dividir um trabalho em tarefas com instruções e contexto próprios. Para criar um, defina uma responsabilidade delimitada, escolha o escopo do arquivo e peça ao Claude Code que produza a definição. Depois, revise o conteúdo e delegue uma tarefa cuja saída possa ser avaliada pelo agente principal e pela equipe.
O melhor ponto de partida costuma ser um papel que você consegue explicar em uma frase. “Revisar os riscos de uma alteração” é mais claro do que “ajudar no projeto”. A definição precisa indicar qual decisão a análise deve apoiar.
Escolha uma responsabilidade que não se misture com as demais
A documentação de subagentes descreve contexto e instruções próprios, com retorno resumido ao agente principal. Não presuma que o subagente recebe integralmente a conversa anterior.
Por isso, descreva a tarefa delegada com informações suficientes para ela fazer sentido por conta própria. Inclua o objetivo, o material relevante e o formato de saída esperado.
Uma divisão prática pode separar investigação, revisão e implementação. A pessoa responsável pelo trabalho deve continuar sabendo qual parte foi analisada e quais dúvidas precisam voltar à discussão principal.
Evite criar vários papéis que apenas repetem a mesma solicitação. O benefício da divisão está na diferença de responsabilidade, não na quantidade de agentes mencionados.
Peça a criação do arquivo no escopo adequado
O fluxo atual do guia orienta pedir ao Claude Code a criação de um arquivo Markdown com metadados YAML. O escopo pessoal usa ~/.claude/agents; o do projeto usa .claude/agents.
Para uma definição compartilhável pelo repositório, um pedido próprio pode ser:
Crie um subagente de revisão de escopo no diretório de agentes deste projeto. Ele deve analisar uma mudança solicitada, identificar riscos e relacionar as verificações necessárias. Sua entrega é um parecer organizado, sem implementar a alteração. Use apenas as ferramentas necessárias à leitura e explique a definição criada para revisão.
Esse pedido expressa a responsabilidade e a entrega. Antes de aceitar o arquivo, examine se a definição realmente corresponde ao papel e se acrescentou acessos ou comportamentos que você não solicitou.
Revise os metadados e as instruções
Confira name, description, tools, model e o corpo das instruções conforme a definição produzida. Não escolha ferramentas apenas porque estão disponíveis: relacione cada uma ao trabalho do subagente.
Na descrição, procure uma condição de uso reconhecível. A equipe deve entender quando faz sentido chamar aquele papel e em que situação outro caminho seria mais adequado.
No corpo, defina como tratar informação ausente. Um revisor de escopo pode apontar uma dúvida e explicar por que ela impede uma conclusão. Ele não precisa produzir uma resposta definitiva para cada ponto.
Combine um formato de retorno. Para esse papel, pode ser: entendimento do pedido, arquivos relacionados, riscos e verificações. Essa estrutura permite ao agente principal usar o parecer sem confundir uma recomendação com uma mudança implementada.
Delegue uma tarefa com contexto suficiente
Quando o diretório de agentes é criado na sessão, o guia orienta reiniciar o Code para que a definição seja detectada. Depois, peça a delegação explicitamente ao agente definido.
Uma solicitação de avaliação pode ser:
Delegue ao revisor de escopo a análise desta mudança: tornar mais clara a confirmação de envio. Forneça o objetivo, os arquivos já identificados e as condições que precisam permanecer iguais. Quero um parecer sobre riscos e verificações, sem implementação nesta etapa.
Observe que a solicitação inclui o que já é conhecido. Não dependa de uma referência vaga como “analise o assunto que conversamos”. Quanto mais autônoma for a descrição da tarefa, mais fácil será reconhecer se o retorno responde ao que foi delegado.
Avalie o retorno antes de continuar
Um parecer útil explica a relação entre risco e código. Uma lista de recomendações que serviria para qualquer aplicação não ajuda a decidir o próximo passo.
Procure informações que alteram a decisão: um estado de erro esquecido, uma dependência fora do escopo ou uma dúvida sobre a regra do produto. Relacione cada ponto a uma ação possível.
Se o retorno estiver incompleto, decida se falta contexto ou se o papel foi mal definido. A primeira situação pede uma entrada melhor. A segunda pode exigir revisar a descrição e as instruções do subagente.
Mantenha a implementação como uma decisão posterior quando esse for o limite combinado. Um parecer favorável sobre escopo não representa uma execução ou uma verificação concluída.
Mantenha os papéis compreensíveis para a equipe
Revise a definição quando o processo mudar. Registre o responsável por aprovar alterações e os casos que mostram o comportamento esperado do papel.
Antes de acrescentar outro subagente, pergunte qual decisão diferente ele vai apoiar. Essa pergunta ajuda a manter a divisão ligada ao trabalho e a evitar uma coleção de definições com funções sobrepostas.
O resultado desejado é uma tarefa bem delegada e um retorno que permita continuar com clareza. Se o produto também possui atendimento ao cliente, a integração Claude da Nextags pode apoiar essa operação em um fluxo próprio.
Fontes e referências
Regras e recursos dos canais podem mudar. Confira as condições atuais nas fontes oficiais antes de colocar sua operação no ar.
Conteúdo de Angelo Sebastião Silva Goncalves. Preparado com apoio de IA. Consulte as fontes e os critérios editoriais. Conheça nossos critérios editoriais e como solicitar uma correção.
