Noções Básicas de Comandos Personalizados e Subagentes

7 exemplos para você começar com Comandos Personalizados e Subagentes - 5 básicos e 2 intermediários.

Pré-requisitos

• Uma instalação funcional do Claude Code, invocada a partir do diretório raiz do seu projeto.
• Um diretório de comandos com escopo de projeto em .claude/commands/ (criado sob demanda, sem etapa de instalação necessária).
• Nenhum pacote extra. Comandos são apenas arquivos markdown; subagentes são iniciados através da ferramenta Agent integrada, nada para configurar antecipadamente.

Exemplos Básicos

1. Criar um Diretório de Comandos

Todo comando personalizado vive como um arquivo markdown em .claude/commands/.

mkdir -p .claude/commands

• O Claude Code escaneia este diretório automaticamente; nenhuma etapa de registro é necessária além de criar o arquivo.
• Comandos aqui têm escopo de projeto e são verificados no controle de versão junto com o restante do repositório.
• Um equivalente em nível de usuário também existe para comandos que você deseja que estejam disponíveis em todos os projetos, mas o escopo de projeto é o padrão correto para comandos compartilhados pela equipe.

2. Escrever um Comando de Barra de Linha Única

O comando mais simples é um cabeçalho frontmatter mais uma única frase de prompt.

---
description: Resuma o diff git atual em linguagem simples
---
 
Resuma as alterações git atualmente em staging em duas ou três frases, escritas para um colega de equipe que ainda não viu o diff.

• Salve isso como .claude/commands/summarize-diff.md e o comando estará disponível como /summarize-diff.
• O campo description do frontmatter é o que aparece quando um usuário completa os comandos disponíveis com a tecla Tab.
• O corpo abaixo do frontmatter é enviado para a conversa exatamente como digitado, como se o usuário o tivesse colado.

3. Invocar o Comando

Uma vez que o arquivo existe, o comando está ativo imediatamente, sem necessidade de reinicialização.

# dentro de uma sessão do Claude Code
/summarize-diff

• Digitar /summarize-diff insere o corpo do prompt do arquivo na conversa e o executa imediatamente.
• Como o prompt é armazenado em disco, todos os membros da equipe que puxarem o repositório recebem o comando idêntico.
• Editar o arquivo markdown altera o comportamento do comando na próxima vez que ele for invocado, sem etapa de reconstrução envolvida.

Relacionado: Escrevendo Seu Primeiro Comando de Barra Personalizado com Frontmatter Markdown - o esquema completo do frontmatter

4. Aceitar Argumentos em um Comando

Comandos podem referenciar o texto digitado após o nome do comando.

---
description: Explique o propósito de um arquivo específico
---
 
Leia $ARGUMENTS e explique o que ele faz, quem o chama e quaisquer efeitos colaterais não óbvios, em menos de 150 palavras.

• $ARGUMENTS é substituído por qualquer coisa que o usuário digitou após o nome do comando, por exemplo, /explain-file lib/auth.ts.
• Isso transforma um comando único em um modelo reutilizável em vez de um prompt fixo e codificado.
• Se nenhum argumento for fornecido, $ARGUMENTS estará vazio, portanto, escreva o prompt para que ele degrade graciosamente ou observe que um alvo é necessário.

5. Iniciar um Único Subagente

Um subagente é uma instância Claude separada com seu próprio contexto, iniciada para lidar com uma tarefa limitada.

# uma solicitação em linguagem simples na sessão principal, não um comando shell
# "Use um subagente para encontrar todos os lugares onde os e-mails de notificação são enviados
#  nesta base de código e resuma as condições de gatilho para cada um."

• O subagente explora a base de código em seu próprio contexto isolado e retorna apenas um resumo para a sessão principal.
• Nenhuma das leituras de arquivo intermediárias ou etapas de pesquisa do subagente polui a janela de contexto da conversa pai.
• Esta é a abordagem correta quando uma tarefa é exploratória e, de outra forma, queimaria muito contexto em becos sem saída.

Relacionado: Como os Subagentes Obtêm Seu Próprio Contexto e Ferramentas - por que o isolamento existe

Exemplos Intermediários

6. Combinar um Comando com uma Solicitação de Subagente

O corpo do prompt de um comando pode, por si só, pedir ao Claude para delegar a um subagente.

---
description: Auditar uma área de recursos e relatar descobertas, sem descarrilar a sessão principal
---
 
Use um subagente para pesquisar como $ARGUMENTS é implementado em toda esta base de código:
pontos de entrada, fluxo de dados e quaisquer testes que o cubram. Peça ao subagente para retornar
um resumo conciso (caminhos de arquivo e uma breve descrição para cada um), não o conteúdo completo do arquivo.

• Salvo como .claude/commands/audit-feature.md, isso torna /audit-feature payment retries uma linha única repetível que sempre delega da mesma maneira.
• A sessão principal apenas vê o resumo do subagente, mantendo seu próprio contexto livre para a correção real ou trabalho de recursos que se segue.
• Formular o prompt para pedir explicitamente "um resumo conciso, não o conteúdo completo do arquivo" é importante, pois um subagente, de outra forma, retornará tudo o que encontrou.

7. Distribuir Vários Subagentes a partir de um Comando

Para auditorias maiores, um único comando pode solicitar que vários subagentes sejam executados em partes independentes da base de código ao mesmo tempo.

---
description: Pesquisar três subsistemas em paralelo e comparar seus padrões
---
 
Inicie três subagentes em paralelo, um para cada um: o código de autenticação,
o código de faturamento e o código de notificações. Cada subagente deve retornar
o padrão de tratamento de erros que encontra em sua área. Em seguida, compare os
três padrões e observe qualquer inconsistência que valha a pena corrigir.

• Como cada subagente obtém seu próprio contexto isolado, as três tarefas de pesquisa não interferem nem contaminam os resultados umas das outras.
• Executá-los em paralelo é mais rápido do que pesquisar cada subsistema sequencialmente na sessão principal.
• A sessão principal só precisa raciocinar sobre três resumos curtos, não sobre a amplitude total de arquivos que cada subagente realmente abriu.

Relacionado: Iniciando Subagentes Paralelos para Tarefas de Pesquisa Isoladas - o padrão de distribuição em profundidade

Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos de produtos mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.