Command Development para Claude Code

Visão geral

Slash commands são prompts frequentemente usados definidos como arquivos Markdown que Claude executa durante sessões interativas. Compreender estrutura de comando, opções de frontmatter e recursos dinâmicos permite criar workflows poderosos e reutilizáveis.

Conceitos-chave:

• Formato de arquivo Markdown para comandos
• Frontmatter YAML para configuração
• Argumentos dinâmicos e referências de arquivo
• Execução bash para contexto
• Organização e namespacing de comandos

Fundamentos de Command

O que é um Slash Command?

Um slash command é um arquivo Markdown contendo um prompt que Claude executa quando invocado. Comandos fornecem:

• Reutilização: Define uma vez, usa repetidamente
• Consistência: Padroniza workflows comuns
• Compartilhamento: Distribui entre equipe ou projetos
• Eficiência: Acesso rápido a prompts complexos

Crítico: Commands são Instruções PARA Claude

Commands são escritas para consumo do agent, não consumo humano.

Quando um usuário invoca /command-name, o conteúdo do comando se torna as instruções do Claude. Escreva comandos como diretivas PARA Claude sobre o que fazer, não como mensagens PARA o usuário.

Abordagem correta (instruções para Claude):

Revise este código em busca de vulnerabilidades de segurança incluindo:
- SQL injection
- XSS attacks
- Problemas de autenticação

Forneça números de linha específicos e classificações de severidade.

Abordagem incorreta (mensagens para usuário):

Este comando revisará seu código em busca de problemas de segurança.
Você receberá um relatório com detalhes de vulnerabilidades.

O primeiro exemplo instrui Claude sobre o que fazer. O segundo diz ao usuário o que acontecerá mas não instrui Claude. Sempre use a primeira abordagem.

Locais de Command

Project commands (compartilhados com equipe):

• Localização: .claude/commands/
• Escopo: Disponível em projeto específico
• Label: Mostrado como "(project)" em /help
• Use para: Workflows de equipe, tarefas específicas do projeto

Personal commands (disponíveis em todo lugar):

• Localização: ~/.claude/commands/
• Escopo: Disponível em todos os projetos
• Label: Mostrado como "(user)" em /help
• Use para: Workflows pessoais, utilitários entre projetos

Plugin commands (agrupados com plugins):

• Localização: plugin-name/commands/
• Escopo: Disponível quando plugin instalado
• Label: Mostrado como "(plugin-name)" em /help
• Use para: Funcionalidade específica do plugin

Formato de Arquivo

Estrutura Básica

Commands são arquivos Markdown com extensão .md:

.claude/commands/
├── review.md           # /review command
├── test.md             # /test command
└── deploy.md           # /deploy command

Comando simples:

Revise este código em busca de vulnerabilidades de segurança incluindo:
- SQL injection
- XSS attacks
- Bypass de autenticação
- Tratamento inseguro de dados

Nenhum frontmatter necessário para comandos básicos.

Com YAML Frontmatter

Adicione configuração usando YAML frontmatter:

---
description: Revise código em busca de problemas de segurança
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

Revise este código em busca de vulnerabilidades de segurança...

Campos YAML Frontmatter

description

Propósito: Descrição breve mostrada em /help Tipo: String Padrão: Primeira linha do prompt do comando

---
description: Revise pull request em busca de qualidade de código
---

Melhores práticas: Descrição clara e acionável (menos de 60 caracteres)

allowed-tools

Propósito: Especifique quais ferramentas o comando pode usar Tipo: String ou Array Padrão: Herda da conversa

---
allowed-tools: Read, Write, Edit, Bash(git:*)
---

Padrões:

• Read, Write, Edit - Ferramentas específicas
• Bash(git:*) - Bash apenas com comandos git
• * - Todas as ferramentas (raramente necessário)

Use quando: Comando requer acesso a ferramentas específicas

model

Propósito: Especifique modelo para execução do comando Tipo: String (sonnet, opus, haiku) Padrão: Herda da conversa

---
model: haiku
---

Casos de uso:

• haiku - Comandos rápidos e simples
• sonnet - Workflows padrão
• opus - Análise complexa

argument-hint

Propósito: Documente argumentos esperados para autocomplete Tipo: String Padrão: Nenhum

---
argument-hint: [pr-number] [priority] [assignee]
---

Benefícios:

• Ajuda usuários a entender argumentos do comando
• Melhora descoberta de comando
• Documenta interface do comando

disable-model-invocation

Propósito: Impeça a ferramenta SlashCommand de chamar comando programaticamente Tipo: Boolean Padrão: false

---
disable-model-invocation: true
---

Use quando: Comando deve ser apenas invocado manualmente

Argumentos Dinâmicos

Usando $ARGUMENTS

Capture todos os argumentos como string única:

---
description: Corrija problema por número
argument-hint: [issue-number]
---

Corrija o problema #$ARGUMENTS seguindo nossos padrões de codificação e melhores práticas.

Uso:

> /fix-issue 123
> /fix-issue 456

Expande para:

Corrija o problema #123 seguindo nossos padrões de codificação...
Corrija o problema #456 seguindo nossos padrões de codificação...

Usando Argumentos Posicionais

Capture argumentos individuais com $1, $2, $3, etc.:

---
description: Revise PR com prioridade e responsável
argument-hint: [pr-number] [priority] [assignee]
---

Revise pull request #$1 com nível de prioridade $2.
Após revisão, atribua a $3 para acompanhamento.

Uso:

> /review-pr 123 high alice

Expande para:

Revise pull request #123 com nível de prioridade high.
Após revisão, atribua a alice para acompanhamento.

Combinando Argumentos

Misture argumentos posicionais e restantes:

Deploy $1 para ambiente $2 com opções: $3

Uso:

> /deploy api staging --force --skip-tests

Expande para:

Deploy api para ambiente staging com opções: --force --skip-tests

Referências de Arquivo

Usando Sintaxe @

Inclua conteúdo de arquivo em comando:

---
description: Revise arquivo específico
argument-hint: [file-path]
---

Revise @$1 em busca de:
- Qualidade de código
- Melhores práticas
- Bugs potenciais

Uso:

> /review-file src/api/users.ts

Efeito: Claude lê src/api/users.ts antes de processar comando

Múltiplas Referências de Arquivo

Referencie múltiplos arquivos:

Compare @src/old-version.js com @src/new-version.js

Identifique:
- Mudanças breaking
- Novos recursos
- Correções de bugs

Referências de Arquivo Estáticas

Referencie arquivos conhecidos sem argumentos:

Revise @package.json e @tsconfig.json em busca de consistência

Garanta:
- Versão TypeScript corresponde
- Dependências estão alinhadas
- Configuração de build está correta

Execução Bash em Commands

Commands podem executar comandos bash inline para dinamicamente reunir contexto antes de Claude processar o comando. Isso é útil para incluir estado do repositório, informações de ambiente, ou contexto específico do projeto.

Quando usar:

• Inclua contexto dinâmico (git status, variáveis de ambiente, etc.)
• Reúna estado do projeto/repositório
• Construa workflows ciente de contexto

Detalhes de implementação: Para sintaxe completa, exemplos e melhores práticas, veja seção references/plugin-features-reference.md sobre execução bash. A referência inclui a sintaxe exata e múltiplos exemplos funcionais para evitar problemas de execução

Organização de Command

Estrutura Plana

Organização simples para pequenos conjuntos de comando:

.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

Use quando: 5-15 comandos, sem categorias claras

Estrutura com Namespacing

Organize commands em subdiretórios:

.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

Benefícios:

• Agrupamento lógico por categoria
• Namespace mostrado em /help
• Mais fácil encontrar comandos relacionados

Use quando: 15+ comandos, categorias claras

Melhores Práticas

Design de Command

1. Responsabilidade única: Um comando, uma tarefa
2. Descrições claras: Auto-explicativas em /help
3. Dependências explícitas: Use allowed-tools quando necessário
4. Documente argumentos: Sempre forneça argument-hint
5. Nomenclatura consistente: Use padrão verbo-substantivo (review-pr, fix-issue)

Manipulação de Argumentos

1. Valide argumentos: Verifique argumentos obrigatórios no prompt
2. Forneça padrões: Sugira padrões quando argumentos faltam
3. Documente formato: Explique formato de argumento esperado
4. Lide com casos extremos: Considere argumentos faltantes ou inválidos

---
argument-hint: [pr-number]
---

$IF($1,
  Revise PR #$1,
  Forneça um número de PR. Uso: /review-pr [number]
)

Referências de Arquivo

1. Caminhos explícitos: Use caminhos de arquivo claros
2. Verifique existência: Lide com arquivos ausentes graciosamente
3. Caminhos relativos: Use caminhos relativos ao projeto
4. Suporte Glob: Considere usar ferramenta Glob para padrões

Comandos Bash

1. Limite escopo: Use Bash(git:*) não Bash(*)
2. Comandos seguros: Evite operações destrutivas
3. Lide com erros: Considere falhas de comando
4. Mantenha rápido: Comandos de longa execução retardam invocação

Documentação

1. Adicione comentários: Explique lógica complexa
2. Forneça exemplos: Mostre uso em comentários
3. Liste requisitos: Documente dependências
4. Versione comandos: Anote mudanças breaking

---
description: Deploy aplicação para ambiente
argument-hint: [environment] [version]
---

<!--
Uso: /deploy [staging|production] [version]
Requer: Credenciais AWS configuradas
Exemplo: /deploy staging v1.2.3
-->

Deploy aplicação para ambiente $1 usando versão $2...

Padrões Comuns

Padrão de Review

---
description: Revise mudanças de código
allowed-tools: Read, Bash(git:*)
---

Arquivos alterados: !`git diff --name-only`

Revise cada arquivo em busca de:
1. Qualidade de código e estilo
2. Bugs ou problemas potenciais
3. Cobertura de teste
4. Necessidades de documentação

Forneça feedback específico para cada arquivo.

Padrão de Testing

---
description: Execute testes para arquivo específico
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

Execute testes: !`npm test $1`

Analise resultados e sugira correções para falhas.

Padrão de Documentação

---
description: Gere documentação para arquivo
argument-hint: [source-file]
---

Gere documentação abrangente para @$1 incluindo:
- Descrições de função/classe
- Documentação de parâmetro
- Descrições de valor retornado
- Exemplos de uso
- Casos extremos e erros

Padrão de Workflow

---
description: Workflow completo de PR
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

Workflow PR #$1:

1. Busque PR: !`gh pr view $1`
2. Revise mudanças
3. Execute verificações
4. Aprove ou solicite mudanças

Solução de Problemas

Command não aparece:

• Verifique se arquivo está no diretório correto
• Verifique se extensão .md está presente
• Garanta formato Markdown válido
• Reinicie Claude Code

Argumentos não funcionando:

• Verifique se sintaxe $1, $2 está correta
• Verifique se argument-hint corresponde ao uso
• Garanta sem espaços extras

Execução Bash falhando:

• Verifique se allowed-tools inclui Bash
• Verifique sintaxe de comando em backticks
• Teste comando em terminal primeiro
• Verifique permissões necessárias

Referências de arquivo não funcionando:

• Verifique se sintaxe @ está correta
• Verifique se caminho de arquivo é válido
• Garanta se ferramenta Read é permitida
• Use caminhos absolutos ou relativos ao projeto

Recursos Específicos de Plugin

Variável CLAUDE_PLUGIN_ROOT

Commands de plugin têm acesso a ${CLAUDE_PLUGIN_ROOT}, uma variável de ambiente que resolve para o caminho absoluto do plugin.

Propósito:

• Referencie arquivos de plugin portavelmente
• Execute scripts de plugin
• Carregue configuração de plugin
• Acesse templates de plugin

Uso básico:

---
description: Analise usando script de plugin
allowed-tools: Bash(node:*)
---

Execute análise: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Revise resultados e reporte achados.

Padrões comuns:

# Execute script de plugin
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Carregue configuração de plugin
@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use template de plugin
@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Acesse recursos de plugin
@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

Por que usar:

• Funciona em todas as instalações
• Portável entre sistemas
• Sem caminhos hardcoded necessários
• Essencial para plugins multi-arquivo

Organização de Plugin Command

Commands de plugin são descobertos automaticamente do diretório commands/:

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

Benefícios de namespacing:

• Agrupamento lógico de comando
• Mostrado em saída /help
• Evite conflitos de nome
• Organize comandos relacionados

Convenções de nomenclatura:

• Use nomes de ação descritivos
• Evite nomes genéricos (test, run)
• Considere prefixo específico do plugin
• Use hífens para nomes multi-palavra

Padrões de Plugin Command

Padrão baseado em configuração:

---
description: Deploy usando configuração de plugin
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

Carregue configuração: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

Deploy para $1 usando configurações de definições.
Monitore deployment e reporte status.

Padrão baseado em template:

---
description: Gere docs de template
argument-hint: [component]
---

Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

Gere documentação para $1 seguindo estrutura de template.

Padrão multi-script:

---
description: Workflow de build completo
allowed-tools: Bash(*)
---

Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`

Revise outputs e reporte status de workflow.

Veja references/plugin-features-reference.md para padrões detalhados.

Integração com Componentes de Plugin

Commands podem integrar com outros componentes de plugin para workflows poderosos.

Integração de Agent

Lance agents de plugin para tarefas complexas:

---
description: Revisão de código profunda
argument-hint: [file-path]
---

Inicie revisão abrangente de @$1 usando o agent code-reviewer.

O agent analisará:
- Estrutura de código
- Problemas de segurança
- Performance
- Melhores práticas

Agent usa recursos de plugin:
- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

Pontos-chave:

• Agent deve existir no diretório plugin/agents/
• Claude usa ferramenta Task para lançar agent
• Documente capacidades de agent
• Referencie recursos de plugin que agent usa

Integração de Skill

Aproveite skills de plugin para conhecimento especializado:

---
description: Documente API com padrões
argument-hint: [api-file]
---

Documente API em @$1 seguindo padrões de plugin.

Use a skill api-docs-standards para garantir:
- Documentação completa de endpoint
- Formatação consistente
- Qualidade de exemplo
- Documentação de erro

Gere docs de API prontos para produção.

Pontos-chave:

• Skill deve existir no diretório plugin/skills/
• Mencione nome de skill para disparar invocação
• Documente propósito de skill
• Explique o que skill fornece

Coordenação de Hook

Projete commands que funcionem com hooks de plugin:

• Commands podem preparar estado para hooks processarem
• Hooks executam automaticamente em eventos de ferramenta
• Commands devem documentar comportamento de hook esperado
• Guie Claude na interpretação de saída de hook

Veja references/plugin-features-reference.md para exemplos de commands que coordenam com hooks

Workflows Multi-Componente

Combine agents, skills e scripts:

---
description: Workflow de revisão abrangente
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Alvo: @$1

Fase 1 - Análise Estática:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Fase 2 - Revisão Profunda:
Lance agent code-reviewer para análise detalhada.

Fase 3 - Verificação de Padrões:
Use skill coding-standards para validação.

Fase 4 - Relatório:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile achados em relatório seguindo template.

Quando usar:

• Workflows multi-passo complexos
• Aproveite múltiplas capacidades de plugin
• Requer análise especializada
• Necessite saídas estruturadas

Padrões de Validação

Commands devem validar entradas e recursos antes de processar.

Validação de Argumento

---
description: Deploy com validação
argument-hint: [environment]
---

Valide ambiente: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

Se $1 é ambiente válido:
  Deploy para $1
Caso contrário:
  Explique ambientes válidos: dev, staging, prod
  Mostre uso: /deploy [environment]

Verificações de Existência de Arquivo

---
description: Processe configuração
argument-hint: [config-file]
---

Verifique se arquivo existe: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

Se arquivo existe:
  Processe configuração: @$1
Caso contrário:
  Explique onde colocar arquivo de config
  Mostre formato esperado
  Forneça exemplo de configuração

Validação de Recurso de Plugin

---
description: Execute analisador de plugin
allowed-tools: Bash(test:*)
---

Valide setup de plugin:
- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`

Se todas as verificações passam, execute análise.
Caso contrário, reporte componentes ausentes.

Tratamento de Erro

---
description: Build com tratamento de erro
allowed-tools: Bash(*)
---

Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`

Se build sucedeu:
  Reporte sucesso e localização de output
Se build falhou:
  Analise saída de erro
  Sugira causas prováveis
  Forneça etapas de solução de problemas

Melhores práticas:

• Valide cedo no comando
• Forneça mensagens de erro úteis
• Sugira ações corretivas
• Lide com casos extremos graciosamente

---

Para especificações detalhadas de campo frontmatter, veja references/frontmatter-reference.md. Para recursos específicos de plugin e padrões, veja references/plugin-features-reference.md. Para exemplos de padrão de comando, veja diretório examples/.