Criando comandos slash personalizados no Claude Code

O que são comandos slash personalizados?

O Claude Code vem com comandos slash nativos como /help e /clear, mas você sabia que pode facilmente adicionar seus próprios comandos? Comandos slash personalizados permitem invocar prompts frequentes ou tarefas rotineiras com uma palavra-chave curta, e dominá-los pode acelerar drasticamente seu desenvolvimento diário.

Em vez de digitar um prompt longo como “Revise o código da branch atual” toda vez, você pode simplesmente digitar /review para acionar o mesmo comportamento. Compartilhe comandos com sua equipe e poderá padronizar critérios de revisão ou procedimentos de release.

Localização e formato dos arquivos

Comandos slash personalizados são arquivos Markdown simples. Há dois locais de armazenamento:

• Específicos do projeto: .claude/commands/<nome-comando>.md
• Globais do usuário: ~/.claude/commands/<nome-comando>.md

Comandos específicos do projeto podem ser commitados no seu repositório e compartilhados com colegas, enquanto comandos globais do usuário ficam disponíveis em todos os seus projetos. O nome do arquivo se torna o nome do comando, então review.md vira /review.

Criando seu primeiro comando

Vamos começar com o comando mais simples possível. Execute isso a partir da raiz do projeto:

mkdir -p .claude/commands
cat > .claude/commands/review.md <<'EOF'
Leia todas as mudanças atualmente na área de staging do Git e
revise-as sob as seguintes perspectivas:

- Possíveis bugs
- Consistência de nomes
- Cobertura de testes ausente
- Preocupações de segurança

Se encontrar problemas, reporte-os com nomes de arquivos e números de linha.
EOF

Pronto. Quando você digita /review no Claude Code, o conteúdo do arquivo é enviado como prompt.

Aceitando argumentos

Para tornar os comandos mais úteis, deixe-os aceitar argumentos. Use o placeholder $ARGUMENTS dentro do seu Markdown e a string passada na invocação será injetada ali.

# .claude/commands/explain.md

Por favor, explique o seguinte arquivo ou símbolo de forma cuidadosa,
para que iniciantes consigam acompanhar.

Alvo: $ARGUMENTS

Sua explicação deve incluir:
1. Um resumo de uma ou duas frases do que o código faz
2. Um passo a passo das linhas importantes
3. Um exemplo de uso realista
4. Armadilhas comuns a evitar

Invoque-o com /explain src/utils/parser.ts. O token $ARGUMENTS é substituído por src/utils/parser.ts antes da execução.

Comandos que referenciam múltiplos arquivos

Além de passar caminhos de arquivo como argumentos, você pode usar a sintaxe @ dentro de um comando para carregar arquivos específicos explicitamente.

# .claude/commands/check-types.md

Depois de ler @tsconfig.json e @package.json, encontre todos os
erros de tipo em todo o projeto.

Passos:
1. Execute `npx tsc --noEmit`
2. Agrupe os erros por arquivo
3. Sugira uma ordem de prioridade de correção
4. Ordene primeiro pelo tamanho da área impactada

Apresente o resultado como uma tabela.

O Claude lê automaticamente tsconfig.json e package.json antes de começar a trabalhar no comando.

Na prática: um comando de preparação de release

Aqui está um exemplo que encapsula um workflow típico de release em um único comando.

# .claude/commands/release.md

Prepare o release para a versão $ARGUMENTS.

Passos:
1. Atualize o campo `version` no package.json para $ARGUMENTS
2. Adicione uma nova seção no início do CHANGELOG.md
   - Referencie o git log desde a tag anterior
   - Classifique em feat / fix / docs / chore
3. Execute `npm run test` e confirme que todos os testes passam
4. Execute `npm run build` e confirme que não há erros de build
5. Resuma as mudanças e proponha uma mensagem de commit

Importante: Não execute `git push` nem `npm publish` você mesmo.
Deixe a confirmação final para o usuário.

Digitar /release 1.4.0 cuida de tudo, do bump de versão à execução dos testes. Por segurança, evite operações destrutivas e deixe um humano confirmar o passo final.

Simulando flags e opções

Você pode descrever lógica de ramificação em Markdown para simular flags.

# .claude/commands/test.md

Argumentos: $ARGUMENTS

Siga estas regras:

- Se os argumentos estiverem vazios: execute todos os testes
- Se os argumentos contiverem `--unit`: execute apenas testes unitários
- Se os argumentos contiverem `--e2e`: execute apenas testes E2E
- Se um caminho de arquivo for incluído: execute apenas testes relacionados àquele arquivo

Após a execução, analise a causa de testes que falharem.

Chamadas como /test --unit ou /test src/auth.ts tornam-se possíveis.

Boas práticas para compartilhamento em equipe

Coloque comandos específicos do projeto em .claude/commands/ e gerencie-os com Git para que cada membro da equipe use os mesmos comandos. Tenha em mente:

• Use uma convenção de nomenclatura consistente: verbo primeiro, nomes curtos (review, fix, explain)
• Documente-os no README: facilite a descoberta de comandos
• Evite operações destrutivas: proíba explicitamente coisas como git push --force ou rm -rf
• Especifique o formato de saída: mantenha resultados de revisão consistentes com tabelas ou checklists

Conclusão

Comandos slash personalizados são o caminho mais curto para transformar o Claude Code em “seu próprio assistente de IA pessoal”. Comece com um ou dois comandos simples e adicione mais sempre que notar uma tarefa repetitiva. Em pouco tempo, eles se tornarão uma parte indispensável do seu workflow.

Para o básico do Claude Code, veja o guia de introdução. Para automação mais avançada, veja Introdução ao Agent SDK, e para dicas sobre contexto, consulte Gerenciamento de Contexto.

Para a documentação oficial, consulte a documentação da Anthropic.