Onde fica o arquivo de um subagente?

Numa pasta de agentes: do projeto, para o time compartilhar pelo controle de versão, ou da sua área pessoal, para valer em todos os seus projetos. A lógica de escopo é a mesma da memória e dos comandos: do time naquele projeto, ou seu em todo lugar, conforme o alcance desejado.

Quais campos um subagente tem?

Um cabeçalho com nome, descrição, ferramentas e modelo, mais um corpo com as instruções. Nome e descrição são essenciais; a descrição é o que guia a delegação. Ferramentas e modelo são opcionais e refinam segurança e custo. O corpo é o prompt especializado que o subagente segue.

Preciso saber a sintaxe do arquivo?

Não precisa escrever do zero. O jeito mais fácil é pedir ao Claude Code para criar o subagente: você descreve o que quer e ele escreve o arquivo, com cabeçalho e instruções. Depois você lê, ajusta e está pronto. É deixar o agente cuidar da mecânica enquanto você decide a intenção.

O que acontece se eu omitir as ferramentas ou o modelo?

São campos opcionais. Se você omite as ferramentas, o subagente herda um conjunto padrão. Se omite o modelo, ele usa o modelo da sessão. Definir esses campos é um refinamento: restringir ferramentas por segurança, ou escolher um modelo mais barato por custo. Sem eles, o subagente já funciona.

Criei um subagente e o Claude Code não o encontra. O que fazer?

Se você criou o subagente durante a sessão, pode ser preciso reiniciar a ferramenta para ela reconhecê-lo, principalmente se a pasta de agentes não existia antes. É um detalhe conhecido, mencionado na documentação oficial. Após reiniciar, o subagente costuma aparecer normalmente.

Módulo 10 - Subagentes

Criando um subagente

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

O que você vai aprender

Conhecer o formato do arquivo de um subagente.
Entender os campos: nome, descrição, ferramentas e modelo.
Escolher entre subagente de projeto e pessoal.
Pedir ao Claude Code para criar um subagente por você.

Um arquivo de texto define o subagente

Depois de aprender a criar comandos personalizados no módulo de comandos, criar um subagente vai parecer familiar: também é um arquivo de texto. Um subagente é definido por um arquivo em formato Markdown, guardado numa pasta de agentes. Assim como na memória e nos comandos, essa pasta pode ser do projeto, para o time compartilhar o subagente pelo controle de versão, ou da sua área pessoal, para o subagente valer em todos os seus projetos. A lógica de escopo é a mesma que você já domina: do time ou seu, conforme o alcance que o ajudante deve ter.

O arquivo tem duas partes. A primeira é um cabeçalho, com algumas informações-chave: o nome do subagente, uma descrição do que ele faz, opcionalmente as ferramentas a que ele tem acesso e o modelo que ele usa. A segunda é o corpo, escrito em texto normal, com as instruções que o subagente segue, o seu prompt especializado. É ali que você diz como ele deve agir: um revisor de segurança teria instruções sobre o que procurar; um escritor de testes, sobre o formato dos testes. Cabeçalho com os dados, corpo com as instruções: essa estrutura simples é tudo que define um subagente.

Diagrama de um arquivo de subagente dividido em duas partes: um cabeçalho com os campos nome, descrição, ferramentas e modelo, e um corpo com as instruções especializadas. Uma seta transforma o arquivo num subagente disponível para o Claude Code acionar. — Um arquivo com cabeçalho (nome, descrição, ferramentas, modelo) e corpo (instruções) define o subagente.

Os campos do cabeçalho

Vale entender cada campo do cabeçalho. O nome identifica o subagente, é como você e o Claude Code se referem a ele. A descrição, o campo mais importante, explica o que ele faz e quando usá-lo; é ela que o agente lê para decidir quando delegar, então escrevê-la bem é crucial, tema da próxima aula. As ferramentas são opcionais: se você as define, o subagente fica restrito a elas, o que aumenta a segurança; se você as omite, ele herda um conjunto padrão. O modelo também é opcional: se você o define, o subagente usa aquele modelo; se omite, ele usa o modelo da sessão. Com esses quatro campos, você configura quem é o subagente e o que ele pode fazer.

Campo	O que faz	Obrigatório?
Nome	Identifica o subagente	Sim
Descrição	Diz o que ele faz e quando usá-lo (o agente lê para delegar)	Sim
Ferramentas	Restringe o subagente às ferramentas listadas	Não (herda o padrão)
Modelo	Define o modelo que o subagente usa	Não (usa o da sessão)

Os campos do cabeçalho. Nome e descrição são essenciais; ferramentas e modelo refinam segurança e custo.

🎮 Jogo da aula

Campo obrigatório ou opcional?

Classifique cada campo do cabeçalho de um subagente.

Você não precisa escrever esse arquivo do zero, encarando a sintaxe. O jeito mais fácil e recomendado é pedir ao próprio Claude Code para criar o subagente. Você descreve o que quer, algo como crie um subagente que revisa código procurando problemas de segurança, e o agente escreve o arquivo para você, com o cabeçalho e as instruções bem montados. Depois, você lê o que ele gerou, ajusta o que quiser e está pronto. É a mesma filosofia de deixar o agente cuidar da mecânica enquanto você decide a intenção. Criar um subagente vira, assim, uma conversa, não um exercício de sintaxe.

O jeito fácil: pedir ao Claude Code

Na prática, criar o seu primeiro subagente é uma conversa curta. Você diz o que quer que ele faça, em que projeto ou se é pessoal, e o Claude Code escreve o arquivo no lugar certo. Vale caprichar na descrição do que você quer, porque ela vira a descrição do subagente, que guia a delegação. Depois de criado, o subagente fica disponível: o Claude Code passa a poder acioná-lo quando uma tarefa combina com a descrição dele, e você também pode chamá-lo explicitamente. Em alguns casos, se o subagente foi criado durante a sessão, pode ser preciso reiniciar a ferramenta para ela reconhecê-lo, um detalhe que a documentação oficial menciona.

Com o subagente criado, você deu um passo importante: montou o primeiro membro de uma equipe de ajudantes especializados. A próxima aula aprofunda o campo que faz tudo funcionar, a descrição, mostrando como o Claude Code a usa para decidir sozinho quando delegar uma tarefa a um subagente, e como escrever descrições que fazem essa delegação acontecer na hora certa. Entender isso é o que separa um subagente que fica esquecido no arquivo de um que o agente realmente aciona quando você precisa. É onde a sua equipe de ajudantes ganha vida de verdade.

Teste rápido

Qual é o jeito mais fácil de criar um subagente no Claude Code?

Perguntas frequentes

Onde fica o arquivo de um subagente?: Numa pasta de agentes: do projeto, para o time compartilhar pelo controle de versão, ou da sua área pessoal, para valer em todos os seus projetos. A lógica de escopo é a mesma da memória e dos comandos: do time naquele projeto, ou seu em todo lugar, conforme o alcance desejado.
Quais campos um subagente tem?: Um cabeçalho com nome, descrição, ferramentas e modelo, mais um corpo com as instruções. Nome e descrição são essenciais; a descrição é o que guia a delegação. Ferramentas e modelo são opcionais e refinam segurança e custo. O corpo é o prompt especializado que o subagente segue.
Preciso saber a sintaxe do arquivo?: Não precisa escrever do zero. O jeito mais fácil é pedir ao Claude Code para criar o subagente: você descreve o que quer e ele escreve o arquivo, com cabeçalho e instruções. Depois você lê, ajusta e está pronto. É deixar o agente cuidar da mecânica enquanto você decide a intenção.
O que acontece se eu omitir as ferramentas ou o modelo?: São campos opcionais. Se você omite as ferramentas, o subagente herda um conjunto padrão. Se omite o modelo, ele usa o modelo da sessão. Definir esses campos é um refinamento: restringir ferramentas por segurança, ou escolher um modelo mais barato por custo. Sem eles, o subagente já funciona.
Criei um subagente e o Claude Code não o encontra. O que fazer?: Se você criou o subagente durante a sessão, pode ser preciso reiniciar a ferramenta para ela reconhecê-lo, principalmente se a pasta de agentes não existia antes. É um detalhe conhecido, mencionado na documentação oficial. Após reiniciar, o subagente costuma aparecer normalmente.

Fontes

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

← Por que e quando delegar a um subagente Concluir e avançar →