Skills e slash commands: criar seus próprios workflows

# Skills ficam em .claude/commands/ como arquivos Markdown
# Nome do arquivo = nome do comando (sem .md)

# Exemplo: .claude/commands/commit.md → /commit
# Exemplo: .claude/commands/code-review.md → /code-review
# Exemplo: .claude/commands/deploy.md → /deploy staging v2.1

# Estrutura de um arquivo de skill:

---
# Este bloco de frontmatter é opcional mas recomendado
description: Cria um commit com mensagem no formato Conventional Commits
---

Analise as mudanças staged com `git diff --staged` e crie um commit seguindo estas regras:

1. Formato: `tipo(escopo): descrição curta em PT-BR`
   - tipos: feat, fix, refactor, docs, test, chore, style, perf
   - escopo: componente ou módulo afetado (opcional)
   - descrição: máximo 72 caracteres, imperativo, sem ponto final

2. Se as mudanças cobrem múltiplos contextos, use commit com bullet points no body.

3. Nunca use --no-verify. Se o pre-commit falhar, investigue e corrija.

4. Após o commit bem-sucedido, confirme com: "✓ Commit criado: [mensagem]"

# Para invocar: /commit
# Claude Code carrega este arquivo, injetado como prompt do usuário

# .claude/commands/pr-review.md
# Uso: /pr-review 42 ou /pr-review https://github.com/org/repo/pull/42

Revise o Pull Request: $ARGUMENTS

Processo:
1. Use o MCP do GitHub para buscar o PR (número ou URL fornecido)
2. Leia o diff completo
3. Analise por estas dimensões (sem ser condescendente ou genérico):
   - Segurança: há possibilidade de injeção, vazamento de dados, permissão indevida?
   - Performance: loops O(n²), N+1 queries, blocking I/O desnecessário?
   - Manutenibilidade: a lógica está clara? há duplicação evitável?
   - Cobertura de edge cases: o que acontece com inputs inválidos, lista vazia, null?
   - Alinhamento com padrões do projeto (cheque o CLAUDE.md para convenções)

4. Formato da resposta:
   ### ✅ Aprovado / ⚠️ Mudanças necessárias / ❌ Bloqueado

   **Problemas críticos** (bloqueia merge):
   - ...

   **Sugestões** (não bloqueia, mas vale considerar):
   - ...

   **Pontos positivos** (o que está bem feito):
   - ...

5. Se não há problemas: "Aprovado ✅ — PR pode ser mergeado"

---
# .claude/commands/new-component.md
# Uso: /new-component NomeDoComponente

Crie um novo componente React: $ARGUMENTS

Siga o padrão dos componentes existentes em src/components/:
1. Leia 2-3 componentes similares para entender o padrão usado
2. Crie src/components/$ARGUMENTS.tsx com:
   - Props tipadas (interface ou type)
   - JSDoc na interface de Props
   - Named export (não default export)
   - Sem estado interno se possível (prefira componentes controlados)
3. Exporte no src/components/index.ts se existir
4. Confirme o que foi criado e próximos passos

# .claude/commands/deploy.md
# Uso: /deploy staging ou /deploy production

Executar deploy no ambiente: $ARGUMENTS

ATENÇÃO: Se o ambiente for "production", exija confirmação explícita antes de qualquer ação.

Checklist antes de qualquer deploy:
1. Verificar que não há mudanças não commitadas: git status
2. Verificar que os testes passam: npm test
3. Verificar que o build está limpo: npm run build
4. Para produção: verificar que está na branch main e o último commit é recente

Se algum item do checklist falhar, PARE e informe o problema. Não continue o deploy.

Se o ambiente for "staging":
- Execute: ./scripts/deploy.sh staging
- Aguarde confirmação de sucesso
- Reporte a URL de staging ao final

Se o ambiente for "production":
- Exiba o checklist e peça confirmação explícita: "Confirme digitando 'DEPLOY PRODUCTION'"
- Só prossiga após confirmação textual explícita
- Execute: ./scripts/deploy.sh production
- Monitore o rollout por 5 minutos
- Verifique os health checks configurados

# Dois locais para skills:

# 1. ~/.claude/commands/ — globais (disponíveis em TODOS os projetos)
~/.claude/commands/
├── commit.md              # /commit — padrão pessoal de commit
├── explain.md             # /explain — explique o código selecionado
└── quick-doc.md           # /quick-doc — gera docstring rapidamente

# 2. .claude/commands/ (projeto) — compartilhados com o time via git
.claude/commands/
├── deploy.md              # /deploy — específico deste projeto
├── pr-review.md           # /pr-review — padrões de review da equipe
├── new-component.md       # /new-component — padrão de componente React do projeto
└── security-check.md      # /security-check — checklist de segurança do projeto

# Regra de prioridade:
# - Skills de projeto têm prioridade sobre globais com mesmo nome
# - /commit no projeto pode sobrescrever /commit global se tiver convenções diferentes

# Descobrir skills disponíveis na sessão:
/help    # lista todos os comandos disponíveis, incluindo seus skills customizados

# Boas práticas de skills:
# ✅ Instrua Claude a ler arquivos relevantes antes de agir (contexto primeiro)
# ✅ Defina formato de saída esperado (evita variação entre execuções)
# ✅ Adicione checklist para ações destrutivas (deploy, deletar dados)
# ✅ Documente no CLAUDE.md quais skills existem e para que servem
# ❌ Não crie skills muito genéricos ("faça o que for necessário") — seja específico
# ❌ Não duplique o que o CLAUDE.md já cobre — skills são para workflows, não contexto

# .claude/commands/spec.md
# Uso: /spec [feature] — gera especificação técnica antes de implementar

Gere uma especificação técnica para: $ARGUMENTS

Antes de escrever qualquer código, produza um documento SPEC.md com:

## 1. Problema
O que estamos resolvendo? Por que isso importa?

## 2. Decisões de design
- Quais são as 2-3 abordagens possíveis?
- Para cada uma: trade-offs, complexidade, manutenabilidade
- Decisão escolhida e justificativa

## 3. Interface pública
- Quais funções/componentes/rotas serão criados/modificados?
- Tipos e assinaturas exatas
- Exemplos de uso

## 4. Casos de borda
- O que acontece com input inválido?
- O que acontece com falha de rede/banco?
- Limites de volume (quantos usuários, quantos registros)

## 5. Plano de implementação
- Passos ordenados de implementação
- Quais arquivos criar/modificar
- Estimativa de complexidade (S/M/L/XL)

## 6. Critérios de aceite
- Como verificar que está funcionando?
- Quais testes cobrir?

---
Após gerar o SPEC.md, aguarde aprovação antes de começar a implementação.
Escreva: "Especificação gerada em SPEC.md. Revise e diga 'implementar' para prosseguir."