Comandos slash no Claude Code: padronize tarefas da equipe

Comandos slash no Claude Code: padronize tarefas da equipe

Comandos slash no Claude Code são arquivos Markdown guardados na pasta .claude/commands do repositório. Cada arquivo vira um comando que qualquer pessoa da equipe chama digitando a barra e o nome. Como o arquivo é versionado junto com o código, tarefas repetidas como revisão, release notes e testes passam a ter um único roteiro, revisado por pull request. Use comando quando a pessoa decide o momento de executar; use skill quando você quer que o Claude escolha o procedimento sozinho a partir do contexto.

Principais pontos

• Um comando slash é um arquivo Markdown com instruções; o nome do arquivo vira o nome do comando.
• Guardar o comando no repositório (.claude/commands) faz toda a equipe usar o mesmo roteiro, com histórico e revisão de mudanças.
• Comando serve para tarefas que um humano dispara de propósito; skill serve para conhecimento que o Claude deve aplicar quando perceber que é relevante.
• Limite as ferramentas permitidas em cada comando: revisão só precisa ler, release notes precisa de leitura do histórico, testes precisam executar um comando específico.
• Comece com um comando só, em um fluxo real, e decida depois de algumas semanas se expande, ajusta ou descarta.

O que é um comando slash personalizado no Claude Code?

O Claude Code já traz comandos internos, usados para gerenciar a sessão. Além deles, você pode criar os seus. Um comando personalizado é um prompt que você escreveu uma vez, salvou em arquivo e passou a invocar por nome, em vez de redigitar o pedido toda vez com palavras ligeiramente diferentes.

Há dois lugares comuns para esses arquivos:

• Na pasta .claude/commands dentro do projeto: o comando fica disponível para quem clonar o repositório e viaja com o código.
• Na pasta .claude/commands do diretório pessoal do usuário: o comando é só seu, em todos os projetos.

Para padronização de equipe, o primeiro lugar é o que importa. O ganho não é economizar digitação. O ganho é que a instrução deixa de morar na cabeça de uma pessoa ou numa conversa de chat e passa a ser um artefato da engenharia: pode ser lido, questionado, melhorado e revertido.

A sintaxe exata evolui entre versões do Claude Code. Antes de adotar qualquer detalhe deste texto, confirme na documentação oficial da versão que sua equipe usa. O que descrevemos a seguir é o padrão geral: arquivo Markdown, um bloco de metadados no topo (frontmatter) e o corpo com as instruções.

Como criar o primeiro comando versionado, passo a passo

Este é um plano curto, pensado para uma pessoa técnica e uma pessoa de operação trabalharem juntas.

• Escolha uma tarefa que a equipe repete toda semana e que hoje é feita de formas diferentes por cada pessoa. Revisão de pull request é um bom candidato.
• Escreva, em português simples, o que um bom resultado contém. Quais pontos o revisor sempre olha? O que nunca deve ser sugerido? Qual formato de resposta ajuda quem vai ler?
• Crie o arquivo dentro de .claude/commands, com um nome curto e claro, por exemplo revisar.md. O comando passa a ser chamado como /revisar.
• No topo, preencha a descrição do comando. Quando a versão suporta, defina também as ferramentas permitidas e uma dica de argumento, para que quem digitar saiba o que informar.
• No corpo, escreva as instruções. Se o comando recebe um parâmetro (número de um pull request, nome de uma pasta), use o marcador de argumentos previsto na documentação.
• Teste em dois ou três casos reais, incluindo um caso difícil. Ajuste o texto até o resultado ficar estável.
• Abra um pull request com o arquivo. A revisão do comando é parte do processo, como qualquer outra mudança de código.
• Avise a equipe e registre, no README, o que o comando faz e o que ele não faz.

Dois recursos costumam ser úteis, desde que a sua versão os suporte: executar um comando de shell antes do prompt para injetar contexto (por exemplo, a lista de arquivos alterados) e referenciar arquivos do repositório diretamente no texto. Ambos reduzem a necessidade de a pessoa colar informação à mão, o que também reduz erro. Do ponto de vista de contexto, vale a lição do material da Anthropic sobre engenharia de contexto para agentes: entregue o mínimo de informação relevante, não tudo o que existe.

Quais tarefas valem um comando: revisão, release notes e testes

Nem toda tarefa merece um comando. As melhores têm três traços: acontecem com frequência, têm um formato de saída esperado e dependem de contexto que está no próprio repositório.

Revisão de código

O comando de revisão instrui o Claude a olhar a diferença entre a branch atual e a principal, e a responder em categorias fixas: risco de bug, segurança, legibilidade, cobertura de testes. Vale escrever também o que ele não deve fazer: não reescrever o arquivo, não aprovar nada, não comentar estilo que o linter já cobre. A saída é um rascunho para o revisor humano, não uma decisão.

Release notes

O comando lê as mudanças desde a última versão e redige um texto para o público certo. Aqui o ponto crítico é o público: nota de versão para quem usa o produto é diferente de changelog técnico. Defina no comando o tom, o idioma (português do Brasil, por exemplo) e a regra de que cada item deve apontar para a mudança real, sem inventar funcionalidade. A pessoa responsável pelo release lê e corrige antes de publicar.

Testes

O comando de testes pede ao Claude que rode a suíte indicada, explique falhas e proponha correção ou novos casos para o trecho alterado. Permita apenas o comando de teste combinado, não execução livre de shell. Sobre confiar no que for gerado, vale ler como validar testes automatizados gerados por IA: teste que passa não é o mesmo que teste que protege.

Cenário ilustrativo

Imagine uma equipe pequena de software que atende uma rede de lojas. Hoje cada desenvolvedor pede revisão ao Claude de um jeito, e as respostas variam de profundas a superficiais. A equipe cria o comando /revisar com cinco categorias fixas e uma regra: apontar arquivo e linha, e separar o que é certeza do que é suspeita. Em um pull request, quem abre o PR roda o comando e cola o resultado na descrição; o revisor humano usa isso como ponto de partida. Dois meses depois, alguém propõe, por pull request, incluir uma categoria sobre dados pessoais, porque o time notou que logs estavam expondo telefones de clientes. A mudança é discutida, aprovada e vale para todos. Esse é o efeito de versionar: a prática melhora de forma visível.

Comando ou skill: como decidir?

A pergunta central é quem aciona. No comando, é a pessoa: ela digita a barra e o nome. Na skill, o Claude lê a descrição e decide usar quando a tarefa em andamento combina com ela. Para entender o outro lado, veja o que são skills no Claude Code e como criar as da sua equipe.

Um guia de decisão em forma de lista:

• Use comando quando a tarefa tem um momento claro de disparo, como antes de abrir um pull request ou ao fechar uma versão.
• Use comando quando você quer previsibilidade: mesma entrada, mesmo roteiro, sem o Claude decidir se aplica ou não.
• Use skill quando o conhecimento deve valer em várias conversas e o Claude precisa reconhecer sozinho a situação, como convenções de nomeação do projeto ou regras de uma API interna.
• Use skill quando o procedimento envolve vários arquivos de apoio, como modelos, exemplos e scripts, que não devem ocupar contexto o tempo todo.
• Use os dois quando fizer sentido: um comando que dispara o fluxo e uma skill que guarda as regras detalhadas consultadas por ele.
• Na dúvida, comece com comando. Ele é mais simples de entender, de testar e de explicar para quem chega na equipe.

Uma observação honesta: dependendo da versão, a documentação oficial trata comandos e skills de forma bastante próxima, e arquivos antigos em .claude/commands continuam funcionando. A distinção prática, quem aciona e quanto material de apoio existe, continua útil para decidir. Confirme na documentação o que muda na sua instalação.

Como limitar o que um comando pode fazer

Comando padronizado também padroniza risco. Um roteiro que roda comandos de shell sem limite, escrito com pressa, replica o problema para todo o time. Por isso a etapa de limites é parte do desenho, não um adendo.

• Permita só as ferramentas necessárias. Um comando de revisão lê arquivos e o histórico; ele não precisa gravar nada. Isso segue o princípio de menor privilégio descrito em guias como o OWASP Authorization Cheat Sheet.
• Escreva no próprio comando o que é proibido: não fazer push, não apagar arquivos, não tocar em arquivos de configuração com segredos.
• Se o comando usa integrações externas, trate-as com cuidado. O texto sobre configurar MCP no Claude Code explica escopos local, de projeto e de usuário, que importam quando o comando depende de uma ferramenta conectada.
• Lembre que conteúdo lido pelo comando (descrição de pull request, comentários, arquivos de terceiros) pode conter instruções maliciosas. Revisão e release notes leem texto que outras pessoas escreveram.
• Mantenha dados pessoais fora do fluxo. Se o repositório contém dados de clientes, a LGPD pede cautela sobre o que é enviado a um serviço externo; vale conferir o que a lei exige em transferência internacional de dados com IA.

A lógica é a mesma defendida no material da Anthropic sobre construir agentes eficazes: comece pelo fluxo mais simples que resolve o problema e só aumente a autonomia quando houver motivo e forma de observar o resultado.

Como pilotar, medir e passar o bastão para a equipe

O método que usamos para qualquer adoção de IA vale aqui, em escala pequena: mapear, limitar, pilotar e transferir.

• Mapear: descreva como a tarefa é feita hoje, quem faz, quanto tempo leva e onde as pessoas divergem. Sem esse ponto de partida, ninguém saberá se o comando ajudou.
• Limitar: defina ferramentas permitidas, dados que podem entrar e o que o comando nunca faz.
• Pilotar: coloque um único comando em uso real, com um grupo pequeno, e combine antes qual sinal conta como sucesso. Pode ser qualitativo: os revisores acham o rascunho útil? As notas de versão exigem menos correção?
• Transferir: documente, indique responsável pelo arquivo e decida em conjunto se expande, ajusta ou encerra.

Sobre medir, evite transformar o comando em instrumento de vigilância individual. O ponto é melhorar o processo, não ranquear pessoas; o artigo sobre medir produtividade com IA sem virar vigilância trata desse equilíbrio.

Para manter a coleção saudável, uma rotina simples ajuda:

• Um responsável por comando, citado no arquivo.
• Revisão trimestral: o comando ainda é usado? Ainda reflete o processo?
• Remoção sem cerimônia de comandos que ninguém chama.
• Nomes consistentes, em português ou em inglês, mas não misturados.
• Uma lista no README com a descrição de cada comando em uma linha.

Perguntas frequentes

Onde ficam os comandos slash personalizados e como a equipe os recebe? Os comandos do projeto ficam na pasta .claude/commands dentro do repositório, e quem clona ou atualiza o código recebe os arquivos junto. Comandos pessoais ficam no diretório do usuário e não são compartilhados. Para padronização de equipe, use o repositório e passe as mudanças por pull request.

Preciso saber programar para criar um comando? Não para escrever o arquivo, que é texto em Markdown com instruções claras. Mas quem cria deve entender o processo que está padronizando e, se o comando executa algo no terminal, ter apoio de alguém técnico para definir os limites. Para quem está começando, o conteúdo sobre Claude Code para quem não programa é um bom ponto de partida.

Quando devo trocar um comando por uma skill? Troque quando perceber que as pessoas esquecem de chamar o comando, ou quando o procedimento passa a depender de muitos arquivos de apoio e regras que o Claude deveria aplicar sozinho. Se o disparo manual faz parte do processo, como no fechamento de uma versão, o comando continua sendo a escolha mais clara.

O resultado do comando pode ser publicado sem revisão? Não é o recomendado. O comando padroniza o roteiro, mas não garante que a saída esteja correta. Revisão, release notes e testes gerados devem passar por uma pessoa responsável antes de virar decisão, publicação ou código em produção.

Fontes

• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• OWASP: Authorization Cheat Sheet