Comandos slash personalizados no Claude Code: /review, /handoff e /release para equipes

Você cola a mesma checklist de revisão de novo. Antes de uma release, tenta lembrar todos os passos. No fim de uma sessão longa no Claude Code, ainda precisa escrever manualmente o que mudou, o que foi verificado e o que ficou em risco. Quanto mais útil um agente de programação fica, mais esses pequenos rituais repetidos merecem virar processo.

Comandos slash personalizados transformam prompts repetidos em nomes curtos que o time inteiro entende. Um /review, /handoff ou /release não é apenas um atalho. Bem desenhado, ele vira um padrão de trabalho: como revisar código, como transferir contexto e como decidir se algo pode ser publicado.

Este artigo segue a documentação oficial de Claude Code Skills e a referência de Commands, verificadas em 3 de junho de 2026. O ponto importante é que comandos personalizados foram integrados a Skills. Arquivos existentes em .claude/commands/*.md continuam funcionando, mas novos workflows de equipe costumam ficar melhores em .claude/skills/<name>/SKILL.md.

Ideia central: um comando é um procedimento reutilizável

No Claude Code, comandos são mensagens que começam com / dentro de uma sessão. A referência oficial diz que o comando é reconhecido no início da mensagem e que o texto depois do nome é passado como argumento. Assim, /release 1.8.0 pode usar 1.8.0 como versão, enquanto /handoff frontend reviewer pode indicar para quem a nota deve ser escrita.

Um Skill é um pacote reutilizável de instruções para Claude. Em linguagem simples, é um pequeno playbook: quando usar, quais etapas seguir, quais entradas importam e qual formato de saída esperar. Os antigos arquivos em .claude/commands/ seguem válidos, mas Skills oferecem estrutura de diretórios, frontmatter, arquivos de apoio, argumentos nomeados e revisão mais fácil.

O primeiro cuidado prático é o nome. Instalações atuais do Claude Code podem já mostrar /review, /code-review ou /security-review. Antes de criar seu próprio /review, digite / e confira o menu. Se o nome existir, use /team-review, /review-note ou outro nome específico do time. O artigo trata do padrão de review; o nome concreto precisa evitar conflito no seu ambiente.

Local dos arquivos: prefira Skills e mantenha Commands para compatibilidade

Se uma regra pertence ao time, ela deve viver no projeto, não apenas no diretório pessoal de alguém. Skills de projeto podem ser commitados, revisados em pull requests e evoluir com o repositório. Skills pessoais são úteis, mas não devem carregar regras das quais todos dependem.

Local	Exemplo	Melhor uso
Skill de projeto	.claude/skills/team-review/SKILL.md	Reviews, releases, investigação e onboarding compartilhados
Command de projeto	.claude/commands/handoff.md	Comandos leves existentes ou transição durante migração
Skill pessoal	~/.claude/skills/my-note/SKILL.md	Notas pessoais e rotinas privadas
Command pessoal	~/.claude/commands/my-command.md	Atalhos temporários

Uma estrutura limpa fica assim:

.claude/
├── commands/
│   └── handoff.md
└── skills/
    ├── team-review/
    │   ├── SKILL.md
    │   └── checklists/
    │       └── review.md
    └── release-prep/
        ├── SKILL.md
        └── scripts/
            └── collect-release-notes.sh

O modelo mental é simples: o repositório guarda o procedimento, o menu / expõe como comando, a pessoa passa argumentos e o Claude Code combina as instruções com o contexto da tarefa.

flowchart LR
  A[".claude/skills ou .claude/commands"] --> B["Comando como /team-review"]
  B --> C["Argumentos: $ARGUMENTS ou $version"]
  C --> D["Claude Code carrega as instruções"]
  D --> E["Review, handoff ou preparação de release"]
  E --> F["Uma pessoa revisa e decide merge ou publicação"]

Depois de adicionar ou alterar um Skill, confirme se ele aparece no menu /. Se a sessão atual não detectar a mudança, use /reload-skills ou abra uma nova sessão do Claude Code. Também revise a descrição, porque ela ajuda o time a descobrir o workflow.

Modelo inicial para copiar

Comece pequeno. O exemplo abaixo cria /team-review, evitando conflito com um possível /review integrado.

mkdir -p .claude/skills/team-review
cat > .claude/skills/team-review/SKILL.md <<'EOF'
---
description: Review the current change with the team's checklist before a pull request or merge.
argument-hint: [target-branch-or-path]
disable-model-invocation: true
---

You are performing a read-only team review.

Target: $ARGUMENTS

If the target is empty, ask which diff, branch, or path to review before scanning broadly.
Do not edit files.
Do not run destructive commands.

Review from these perspectives:
1. Correctness bugs and edge cases
2. Security and privacy risks
3. Test coverage and missing verification
4. Consistency with existing code patterns
5. Documentation, migration notes, and user-facing copy

Output:
- Findings first, ordered by severity
- File path and line number when available
- One short suggestion for each issue
- "No blocking findings" only if you found none
EOF

Depois chame com /team-review main, /team-review src/auth ou outro alvo bem delimitado. disable-model-invocation: true impede que Claude escolha esse Skill automaticamente. Para review e release, isso é bom: são pontos de controle que devem começar por decisão humana.

Caso de uso 1: transformar /review em checklist do time

O valor de um comando de review é a consistência. Sem uma checklist compartilhada, uma pessoa foca em nomes, outra em segurança e outra em testes. O comando deve definir severidade, escopo e formato de saída para que Claude e humanos revisem pelo mesmo critério.

Se seu ambiente já tem /review, use team-review.md ou um Skill team-review. Se não houver conflito, .claude/commands/review.md ainda pode criar /review.

---
description: Team review checklist for the current branch or specified path.
argument-hint: [branch-or-path]
disable-model-invocation: true
---

Review target: $ARGUMENTS

Read the diff or files related to the target and report only review findings.
Do not rewrite code unless the user asks for fixes after the review.

Severity:
- P0: data loss, auth bypass, secret leak, production outage
- P1: correctness bug, missing validation, broken user flow
- P2: maintainability, unclear naming, duplicated logic
- P3: optional cleanup

Required checks:
1. Is the change scoped to the request?
2. Are tests or manual verification enough for the risk?
3. Are error paths and empty states handled?
4. Does the code follow existing local patterns?
5. Could the change break monetization links, analytics, or release notes?

Return a short summary after the findings.

A linha decisiva é “Do not rewrite code”. Uma review que edita arquivos sem pedido explícito deixa de ser review e vira implementação. Faça a primeira passada somente leitura; depois, se os achados forem aceitos, abra uma tarefa separada de correção.

Caso de uso 2: usar /handoff para a próxima pessoa ou agente

Sessões longas perdem valor quando terminam sem contexto claro. Um comando de handoff transforma o fechamento da tarefa em uma nota estruturada para você amanhã, para alguém do time ou para outro agente.

---
description: Create a concise handoff note for the current task.
argument-hint: [next-owner-or-audience]
disable-model-invocation: true
---

Create a handoff note for: $ARGUMENTS

Include these sections:
1. Goal: what the task was trying to achieve
2. Changed files: important files and why they changed
3. Decisions: tradeoffs or assumptions made during the work
4. Verification: commands run, screenshots checked, or checks not run
5. Risks: unresolved issues, fragile areas, or things needing human review
6. Next steps: the smallest useful next action

Keep it factual. Do not hide failed attempts. If something was not verified, say so clearly.

Isso ajuda muito em sites monetizados e aplicações em produção. Links internos, CTAs, eventos de analytics, screenshots e verificações manuais são fáceis de esquecer quando a mudança atravessa vários arquivos. O handoff mantém esses detalhes visíveis.

Caso de uso 3: usar /release para preparar, não publicar

Comandos de release devem ser conservadores. O objetivo não é deixar Claude publicar por você. O objetivo é reunir contexto, preparar notas, listar bloqueios e deixar a decisão final para uma pessoa.

Este modelo usa argumentos nomeados. A documentação atual descreve arguments como nomes ligados a argumentos posicionais; aqui o primeiro argumento vira $version.

---
description: Prepare a release checklist and changelog draft without publishing.
argument-hint: [version]
arguments: [version]
disable-model-invocation: true
---

Prepare release $version.

Allowed work:
1. Inspect the current diff, package metadata, and changelog
2. Draft a changelog section for $version
3. Suggest verification commands
4. List release blockers and rollback notes
5. Propose a commit message

Safety rules:
- Do not run git push
- Do not publish packages
- Do not deploy to production
- Do not delete files
- Ask before changing version files

Output:
- Release summary
- Checklist
- Blockers
- Commands the user should run manually

Esse é um comando de preparação de release, não um botão de publicação. Se o time quiser automatizar publicação, deixe isso no CI/CD, com aprovações, logs e regras de rollback explícitas.

Argumentos: comece com $ARGUMENTS

Para a maioria dos comandos próprios, $ARGUMENTS basta. /handoff backend reviewer coloca backend reviewer em $ARGUMENTS. A documentação atual também aceita $ARGUMENTS[0], $0 e argumentos nomeados como $issue ou $branch quando declarados no frontmatter.

---
description: Prepare an issue-specific work plan.
argument-hint: [issue] [branch]
arguments: [issue, branch]
disable-model-invocation: true
---

Issue: $issue
Branch: $branch
All arguments: $ARGUMENTS

Create a plan that:
1. Restates the issue in plain language
2. Lists files to inspect first
3. Identifies likely tests
4. Names one thing that should not be changed

Use aspas quando um argumento tiver várias palavras: /plan-issue "login redirect bug" fix-login. Cuidado com exemplos antigos que tratam $1 como primeiro argumento. A documentação atual descreve $0 como atalho para o primeiro argumento posicional.

Versionamento e fluxo de revisão

Trate Skills e Commands do projeto como código. Eles influenciam o que será revisado, o que pode passar despercebido e o que o time chama de “pronto”. Uma mudança em .claude/skills/release-prep/SKILL.md deve aparecer em pull request, não sumir dentro de uma feature sem relação.

Regra	Por que importa
Versionar .claude/skills/ no Git	Mostra quem mudou o workflow e quando
Permitir PRs só de comandos	Mudanças de processo não se misturam com app code
Listar comandos no README ou CLAUDE.md	Novos membros descobrem rápido
Proibir ações destrutivas no prompt	Evita push, publish, deploy ou remoção acidental
Revisar a lista mensalmente	Remove comandos obsoletos antes que confundam

Para adoção em equipe, combine este artigo com o guia inicial do Claude Code, as boas práticas de CLAUDE.md e o guia de Claude Code Hooks.

Armadilhas e segurança

O maior erro é achar que um comando personalizado é seguro só porque é curto. Ele continua sendo um prompt forte. Se você usa injeção dinâmica de contexto com backticks !, o Claude Code executa o comando de shell e insere a saída antes de Claude ler o Skill. Isso é útil, mas exige limite rígido de somente leitura.

---
description: Collect read-only git context for release notes.
disable-model-invocation: true
---

Current status:
!`git status --short`

Recent commits:
!`git log --oneline -20`

Summarize the release notes from the information above.
Do not run write operations.

Restrinja esses comandos a inspeções seguras como git status e git log. Não inclua rm, git clean, git push, npm publish, curl ... | sh nem scripts que afetem produção. Também tenha cuidado com allowed-tools: liberar Bash de forma ampla pode reduzir confirmações onde o time esperava uma pausa. Comece com ferramentas de leitura e adicione permissões só quando o workflow precisar.

Falhas concretas são fáceis de prever. Um /review próprio conflita com comando integrado. Um Skill fica só no home de uma pessoa. O corpo cresce tanto que consome contexto a cada uso. Um argumento vazio faz Claude varrer o repositório inteiro. Um release inclui publicação. Tudo isso nasce de tentar automatizar rápido demais. Comece em leitura, mantenha o alvo pequeno e deixe confirmação humana no desenho.

CTA: transforme os modelos em operação

Esses modelos valem mais quando se adaptam ao seu repositório. Desenvolvedores solo podem começar pela cheatsheet gratuita do Claude Code e manter padrões seguros por perto. Para modelos reutilizáveis de review, release e handoff, veja os produtos ClaudeCodeLab. Se sua equipe precisa desenhar permissões, CLAUDE.md, revisão de Skills, limites com CI e onboarding juntos, use a página de treinamento e consultoria Claude Code.

Ao testar no workflow de Masa, o resultado ficou claro: três comandos bastaram. /team-review, /handoff e /release-prep cobriram a maior parte do trabalho repetido sem transformar Claude Code em ferramenta perigosa de deploy. O maior ganho veio de definir /release como um comando que reúne evidências para decisão humana, não como um comando que publica. Comandos slash personalizados funcionam melhor quando ajudam o time a parar, verificar e transferir contexto com o mesmo padrão.