Você já entende o que é um subagente, sabe escrever seu .md e conhece a diferença entre projeto e global. Agora vem a pergunta prática: como crio um agente de verdade, do zero? O comando /agents é o wizard nativo do Claude Code — lista o que existe, abre o criador guiado e deixa você trimar o resultado. Neste módulo você vai criar um agente completo (plan-roaster) e aprender exatamente como o Claude decide qual agente chamar.
Fluxo do wizard /agents: do comando ao agente ativo em 3 passos
Conteúdo detalhado
🔍 O comando /agents — ver e criar
Seu painel de controle de subagentes
O /agents é o ponto de entrada para tudo relacionado a agentes customizados no Claude Code. Ele exibe a lista completa dos agentes disponíveis no projeto e no global, e abre o wizard de criação guiado.
- • Lista todos os agentes disponíveis (projeto + global)
- • Mostra onde cada arquivo .md está salvo
- • Abre o wizard de criação interativo
- • Permite editar agents existentes
- • Exibe description, tools e modelo configurados
- • Não cria o arquivo manualmente (o wizard cria)
- • Não executa o agente diretamente
- • Não mostra built-ins do Claude Code
- • Não sincroniza com outros projetos
- • Não define quando o Claude ativa (isso é a description)
Ao rodar /agents sem parâmetros, o Claude Code varre os diretórios .claude/agents/ do projeto e do global, lê o frontmatter de cada .md e monta uma lista com nome, description truncada e localização.
Antes de criar um agente novo, sempre liste os existentes — você pode já ter um que cobre o caso de uso, ou descobrir nomes que colidem com o que planejava criar.
Projeto prevalece sobre global quando há conflito de nome. O wizard de criação já avisa se o nome existe. A lista inclui built-ins do Claude Code separados dos seus customs.
⚡ Generate-with-Claude × manual
Duas formas de preencher o .md — quando usar cada uma
Dentro do wizard, a opção Generate with Claude usa o modelo atual para rascunhar o arquivo .md a partir de uma descrição de alto nível que você digita. É o ponto de partida mais rápido — mas o output gerado quase sempre precisa de trim na description.
Claude escreve o corpo, escolhe tools e sugere um modelo. Você descreve o objetivo em linguagem natural. Saída em segundos. Exige trim da description para evitar texto longo demais.
Você escreve o .md do zero num editor. Controle total, sem surpresas. Ideal quando já tem um template pronto ou está iterando sobre um agente existente.
A escolha entre os dois modos define velocidade de criação vs. controle do resultado. Gerar é ótimo para o primeiro rascunho; manual é melhor para iterações finas.
Agentes gerados automaticamente tendem a ter descriptions verbosas que disparam no momento errado. Saber quando trimar evita misfires custosos.
Regra prática — gere o rascunho, abra o .md e corte a description para no máximo 2-3 frases com gatilho explícito. O corpo pode ser rico; a description deve ser cirúrgica.
🧩 Escolhas no wizard: tools, model, color, memory
As quatro decisões que definem o comportamento do agente
O wizard guia você por cada campo, mas você pode deixar em branco e editar depois direto no .md. O campo tools é o mais crítico — agentes com acesso irrestrito podem tomar ações inesperadas.
Lista de ferramentas permitidas. Prefira listas explícitas (ex.: ["Read","Bash","WebSearch"]). Omitir = herda todas as tools do contexto pai.
Modelo a usar: haiku para tarefas rápidas/baratas, sonnet para o equilíbrio, opus para raciocínio pesado.
Cor do badge do agente na UI do Claude Code. Puramente estética — útil para diferenciar agentes rapidamente na lista do /agents.
Controla se o agente pode ler/gravar na memória persistente (allow / deny). Na maioria dos casos, deny é mais seguro — agentes especialistas não precisam de memória.
O wizard usa defaults conservadores: sem tools explícitas, sem modelo definido. Em produção você quase sempre vai querer declarar tools e model para comportamento previsível.
Agente sem model definido herda o modelo do claude pai — pode mudar de sessão para sessão dependendo do seu plano. Fixar o modelo garante custos e latência previsíveis.
Mínimo recomendado para produção: name, description (cirúrgica), tools (lista explícita), model. Color e memory são opcionais.
🔥 Caso plan-roaster: criar e trimar
Da ideia ao agente funcionando — walkthrough completo
Quando você usa "Generate with Claude", o modelo gera uma description longa e detalhada. Parece bom — mas uma description assim dispara o agente em contextos genéricos demais. Trim é obrigatório.
/agents → Create → nome: plan-roasterO wizard pede o nome. Use kebab-case. Este agente vai revisar planos criticamente.
Ex.: "agente que revisa planos de implementação, aponta pontos cegos, riscos e alternativas melhores — como um engenheiro sênior cético"
.claude/agents/plan-roaster.md e trime a descriptionCorte para 2-3 frases: o quando dispara + o que faz. Remova qualquer parágrafo de contexto — isso vai no corpo.
@plan-roaster revise este planoSe disparar corretamente, confira se o output está detalhado. Se for genérico, enriqueça o corpo do .md.
Progressive disclosure aplicado à description: o Claude lê só os primeiros tokens da description para decidir se ativa o agente. Tudo depois do gatilho principal raramente importa para a ativação.
Uma description de 5 linhas com muitos contextos heterogêneos cria ambiguidade — o Claude pode ativar o agente mesmo quando não é ideal. 2-3 frases com gatilho claro são mais precisas.
Fórmula de description enxuta: "Use [quando exatamente]. [O que faz em 1 frase]. [Opcional: exemplos de trigger]." O resto vai no corpo do .md, que o agente lê depois de ser ativado.
🎯 Quatro formas de invocar um agente
Automático, proativo, @nome e --agent
O Claude lê a description de todos os agentes disponíveis a cada turno. Se o seu prompt combina com a description de um agente, ele é ativado automaticamente — sem você precisar pedir. Isso é o modo automático. Mas você pode forçar outros modos.
Claude lê a description e ativa o agente se o contexto combinar. Você não faz nada — ele decide. Depende de uma description precisa.
A description inclui "Use proativamente quando..." — o Claude verifica se deve acionar mesmo sem você pedir explicitamente, como após commits ou ao abrir um PR.
Você digita @plan-roaster revise isto. Ativação garantida independente da description. Mais explícito — menos surpresas. Ideal ao testar um agente novo.
Na linha de comando: claude --agent plan-roaster "revise o plano". Útil em scripts e automações onde você não está no modo interativo.
Quando dois agentes têm descriptions que combinam com o mesmo prompt, o Claude usa o contexto completo da conversa para decidir qual é mais específico. Agentes de projeto têm precedência sobre global com o mesmo nome.
Se você tem um code-reviewer global e um do projeto, o do projeto sempre ganha. Isso permite customizações por projeto sem remover o global.
Ordem de prioridade: 1) invocação @nome (forçado), 2) agente de projeto (auto), 3) agente global (auto), 4) built-in. Nomes únicos eliminam o problema de concorrência.
🔧 Misfire e conserto
Quando o agente dispara errado — e como corrigir
- • Agente ativa em prompts que não têm nada a ver
- • Dois agentes ativam ao mesmo tempo
- • Agente nunca ativa — mesmo pedindo
- • Agente errado ativa (colisão de description)
- • Output genérico: corpo do .md não foi lido
- • Trime description — remova contexto desnecessário
- • Renomeie ou separe descriptions com gatilhos distintos
- • Adicione "Use proativamente quando [frase exata]"
- • Use prefixo no nome:
proj-code-reviewer - • Enriqueça o corpo do .md com instruções detalhadas
Pergunte ao Claude: "Por que o agente plan-roaster não disparou no meu último prompt?" — ele vai explicar qual description leu e por que não combinou. Use essa informação para ajustar.
A description raramente fica perfeita na primeira vez. O ciclo é: escrever → testar com 5+ prompts variados → observar quando dispara e quando não → ajustar a description → repetir.
Agentes de produção que disparam errado podem consumir tokens desnecessariamente ou interferir no fluxo de trabalho. Iterar a description é o principal custo de manutenção de um agente.
Teste de 5 prompts: 2 que devem acionar, 2 que não devem, 1 borda. Se a taxa de acerto é 4/5 ou melhor, a description está boa. Abaixo disso, itere.
✂️ Trimando a description gerada
A arte do corte preciso — progressive disclosure
O Claude Code usa as descriptions de todos os agentes disponíveis como parte do contexto de decisão a cada turno. Descriptions longas consomem mais tokens nessa janela de seleção — e ambiguidade semântica nelas gera misfires. A description otimizada é aquela que passa no teste de 5 prompts com o mínimo de palavras.
"Este agente especializado em revisão crítica de planos de implementação foi projetado para analisar documentos de planejamento técnico e estratégico, identificando lacunas, pontos cegos, riscos não considerados, dependências ocultas e alternativas mais eficientes. Atua como um engenheiro sênior cético..."
"Use proativamente quando o usuário apresentar um plano, spec ou documento de implementação para revisão. Revisa criticamente como um engenheiro sênior cético: aponta pontos cegos, riscos e alternativas."
A fórmula de 3 partes: (1) gatilho explícito com "Use [quando/proativamente quando]...", (2) o que faz em 1 frase ativa, (3) opcionalmente, exemplos de trigger como hint semântico.
Descriptions seguindo essa fórmula têm taxa de misfire próxima de zero em testes empíricos. O "Use quando" ancora o Claude na intenção correta antes de qualquer ambiguidade semântica.
Template: "Use proativamente quando [trigger]. [O que faz]. [Hint adicional opcional]." — 2-3 frases no máximo. Todo o contexto operacional vai no corpo do .md.
📄
Exemplo real: plan-roaster.md
Arquivo completo — description trimada, corpo rico, tools mínimas
--- name: plan-roaster description: "Use proativamente quando o usuário apresentar um plano, spec ou documento de implementação. Revisa criticamente: aponta pontos cegos, riscos e alternativas melhores." tools: [Read] model: claude-sonnet-4-5 color: red --- # Revisor de Planos (plan-roaster) Você é um engenheiro sênior cético. Sua função é revisar planos de implementação com ceticismo construtivo. Nunca valide sem questionar. ## Protocolo de revisão 1. Leia o plano completo antes de comentar 2. Identifique as 3 maiores lacunas ou riscos 3. Para cada risco, sugira uma mitigação concreta 4. Aponte dependências implícitas não declaradas 5. Questione os pressupostos de tempo/custo 6. Conclua com um veredito: Aprovar / Revisar / Rejeitar ## Tom Direto, sem rodeios. Sem elogios desnecessários. Use listas numeradas. Máximo 400 palavras no output.
- • Description trimada para 3 frases com gatilho explícito
- •
tools: [Read]— mínimo necessário (só lê, não escreve) - • Corpo rico com protocolo de 6 passos — isso é lido depois de ativado
- • Tom definido explicitamente — evita respostas genéricas
💬 Prompts prontos
Copy-paste e use agora
/agents → Create → nome: plan-roaster → Generate with Claude → "revisor crítico de planos como engenheiro sênior cético"
@plan-roaster revise o plano em docs/plan.md e me dê os 3 maiores riscos
Por que o agente plan-roaster não disparou quando eu disse "revise meu plano de migração"? O que estava na description que não combinou?
🖥️
Tela simulada: wizard /agents
Recriação ilustrativa — não é screenshot real
🏋️ Exercício: crie e invoque um agente por nome
- 1.Abra o Claude Code no seu projeto e rode
/agents— anote quantos agentes já existem. - 2.Crie um agente chamado
bug-hunterusando "Generate with Claude" com o objetivo: "agente que analisa código e encontra bugs potenciais antes de um PR". - 3.Abra o
.mdgerado e trime a description para no máximo 3 frases usando a fórmula do tópico 7. - 4.Invoque por nome:
@bug-hunter analise o arquivo main.py e me dê os 3 maiores riscos. - 5.Teste 3 prompts que NÃO deveriam ativar o agente e confirme que ele não dispara.
.claude/agents/bug-hunter.md existe no projeto
@bug-hunter retorna uma análise estruturada com bugs enumerados
.md preenchido
📚 Resumo do módulo
/agents é o painel completo — lista, cria e edita agentes
Você completou a Trilha 2 — agora sabe criar agentes na prática. A Trilha 3 aprofunda modelo, custo e orquestração: qual modelo escolher por tarefa, como encadear subagentes e medir o custo real de um sistema multiagente.