Slash Commands avançado: subagentes e orquestração de ferramentas

Os dois primeiros artigos cobriram o que é um slash command (um arquivo Markdown) e como usar o prefixo ! para injetar saída de shell no contexto. Este vai além: como fazer um único command orquestrar as capacidades mais poderosas do Claude Code — referências de arquivo, subagentes, ferramentas MCP — mantendo as permissões sob controle.

Nesse nível, um command deixa de ser um "atalho de prompt" e vira um pequeno fluxo de trabalho reutilizável.

Referências `@file`: uma injeção estática mais limpa que `!cat`

!cat file.md leva o conteúdo de um arquivo para o contexto, mas passa pelo shell, e isso tem custos: gera um subprocesso toda vez, caminhos com espaços ou caracteres especiais precisam de escape, e o Claude Code trata a saída como texto simples em vez de "um arquivo".

A referência @ é nativa:

---
description: Revisar as mudanças contra os padrões do projeto
---

Materiais de referência:

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

Agora revise as mudanças do diff abaixo e aponte todas as violações desses padrões.

!`git diff HEAD`

@caminho diz ao Claude Code "anexe esse arquivo à conversa". A diferença:

Cenário	Usar `!cat`	Usar `@`
Caminho vem de um argumento (`$ARGUMENTS`)	✅ Obrigatório	❌ `@` não expande variáveis
Padrões, templates e convenções fixos	⚠️ Funciona mas é pesado	✅ Nativo, sem shell
Conteúdo dinâmico (diff, logs, resultados de teste)	✅ Obrigatório	❌ Não rola

Regra prática: @ para arquivos estáticos, ! para saída dinâmica, !cat $ARGUMENTS para caminhos parametrizados.

`allowed-tools`: limites de permissão para commands

Por padrão, um command pode usar todas as ferramentas disponíveis na sessão. Nem sempre é o que você quer — /review é uma tarefa somente leitura, e você não quer que ela "aproveite" e edite uma linha de código no caminho.

Adicione allowed-tools ao frontmatter e apenas as ferramentas listadas ficam disponíveis enquanto o command roda:

---
description: Revisão de código somente leitura
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

Revise a diferença entre esta branch e master. Só leitura, sem edições.

!`git diff master...HEAD`

Pontos-chave:

Bash(git diff:*) é autorização de granularidade fina — só comandos bash começando com git diff são permitidos; git push seria bloqueado
Read / Grep / Glob concede explicitamente só ferramentas de leitura
Edit / Write não estão listados, então o modelo não consegue modificar código nem se quisesse

O inverso também funciona — um command de alto privilégio como /deploy:

---
description: Deploy da branch atual
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

Travar "o que esse command pode fazer" é muito mais confiável do que depender de aprovação manual de prompts bash a cada execução.

Chamando subagentes: isolar o trabalho que come contexto

Algumas tarefas estouram seu contexto principal — percorrer dezenas de arquivos para achar todos os call sites de uma função, rodar estatísticas no codebase inteiro, raspar um log enorme para análise. Feito inline, milhares de linhas de saída ficam no contexto e cada turno seguinte fica mais lento e mais burro.

O certo é passar esse trabalho para um subagente. Ele roda no próprio contexto e só traz a conclusão de volta. No command basta dizer isso de forma explícita:

---
description: Pesquisa profunda sobre todos os usos de um símbolo
allowed-tools: Task
---

Use um subagente Explore para pesquisar profundamente todos os usos de: $ARGUMENTS

O subagente deve cobrir:
- Todos os pontos de chamada (incluindo arquivos de teste)
- Os cenários de negócio cobertos
- Se existem implementações alternativas equivalentes

Quando o subagente retornar, me dê um resumo de até 300 palavras — não cole trechos brutos de código.

Dispare /trace SomeClass#some_method e o Claude Code sobe um subagente Explore para varrer o codebase em paralelo. A conversa principal recebe apenas a conclusão destilada. Sem saída de grep, sem fragmentos de arquivo. O contexto fica limpo.

Levando mais longe:

---
description: Pesquisar três abordagens candidatas em paralelo
allowed-tools: Task
---

Suba 3 subagentes em paralelo, cada um investigando um caminho de implementação:

1. ActiveJob + Sidekiq existentes
2. Solid Queue
3. Uma fila leve feita em casa

Cada agente responde: esforço, risco e o quão invasiva é a mudança no código atual. Quando os três retornarem, eu comparo.

Três agentes rodando em paralelo, a conversa principal espera uma vez só. Este é um dos maiores pontos de alavancagem que um command oferece: transformar "tarefas de pesquisa que custam muitos tokens" em um gatilho único.

Chamando ferramentas MCP: alcançar sistemas externos

Se a sessão tem servidores MCP conectados (Linear, GitHub, Sentry, proxy de banco interno, etc.), o command pode instruir o modelo a usá-los:

---
description: Transformar um issue do Linear em um plano de implementação
allowed-tools: mcp__linear__*, Read, Grep
---

Puxe a descrição completa e os comentários do issue do Linear $ARGUMENTS.

Combinando com o estado atual do codebase (use Grep/Read para achar os arquivos relevantes), produza um todo de implementação:
- Quais arquivos precisam mudar
- Se cada passo deve ser um commit independente ou agrupado
- Quaisquer ambiguidades que precisem de conversa prévia com o PM

Não comece a escrever código. Só o plano.

mcp__linear__* autoriza todas as ferramentas MCP do Linear — o modelo consegue buscar detalhes do issue, comentários, status. O command inteiro vira a porta de entrada de um fluxo "do ticket ao plano de implementação".

Importante: nomes de ferramentas MCP em allowed-tools precisam do prefixo completo (mcp__<servidor>__<ferramenta>), senão a autorização não se aplica.

A armadilha da composição: slash commands não recursam

Um mal-entendido comum: colocar /test dentro do arquivo de /review achando que isso vai "disparar" o command de teste. Não dispara. Slash commands expandem exatamente uma vez, na entrada do usuário no topo. Um /xxx dentro do corpo do command é só texto — o modelo lê, mas o Claude Code não executa.

Se você quer compor commands, as abordagens corretas são:

Opção A: extraia a lógica compartilhada para arquivos de contexto e referencie de cada command com @ ou !cat

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

Opção B: escreva "faça do jeito que /review faz" e repita as instruções-chave

Não é elegante mas funciona. Desde que o prompt esteja claro, o modelo vai seguir o mesmo caminho.

Opção C: faça um command usar a ferramenta Task para subir um subagente, e reuse os mesmos arquivos de contexto dentro do prompt do subagente

Toda orquestração real de fluxo vive aqui. O command pai despacha e resume; o subagente executa o passo real.

O antipadrão a evitar: escrever um único command com centenas de linhas tentando fazer tudo de uma vez. O custo de manutenção explode e uma única execução consome todo o seu orçamento de tokens.

Quando usar qual

Com @, !, subagentes e ferramentas MCP em campo, os mecanismos para injetar "capacidade externa" em um command estão todos na mesa. Como escolher:

Necessidade	Escolha
Padrões, templates, documentos de contexto fixos	Referência `@file`
Estado ao vivo (diff, logs, testes, queries DB)	Injeção `!shell`
Conteúdo de arquivo parametrizado	`!cat $ARGUMENTS`
Pesquisa pesada em contexto, busca cross-arquivo	Subagente via Task
Sistemas externos (tracker, monitoramento, dados de prod)	Ferramentas MCP + `allowed-tools`
Fluxos multi-step sequenciais ou paralelos	Command pai despachando subagentes

Declare os limites de permissão explicitamente com allowed-tools, especialmente em commands que o time inteiro compartilha. Travar o que um command pode fazer é melhor que confiar em aprovação manual a cada execução.

Um exemplo próximo da produção

Juntando tudo — um command que transforma um Linear ticket em um plano de implementação:

---
description: Gerar um plano de implementação a partir de um Linear ticket
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## Contexto

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## Estado atual do repo

!`git log --oneline -10`

## Tarefa

Busque o Linear ticket $ARGUMENTS — descrição, comentários e tickets relacionados.

Depois suba dois subagentes em paralelo:
1. Primeiro agente: varra o codebase atrás de implementações existentes relevantes e módulos reutilizáveis
2. Segundo agente: avalie o risco — que caminhos de código de alto tráfego essa mudança toca, onde há lacunas de cobertura de teste

Quando ambos retornarem, devolva:
- Passos de implementação (ordenados por dependência)
- Lista de riscos
- Granularidade de commit sugerida

Não comece a escrever código.

Rode /plan ENG-4213 e um único command percorre o fluxo todo: buscar ticket → pesquisa paralela no codebase → avaliação de risco → plano sintetizado. O usuário só lê a saída e decide se começa.

Com isso se fecha o arco dos três primeiros artigos da série: definir prompts reutilizáveis (intro) → injetar contexto dinâmico (context) → orquestrar ferramentas e subagentes (este). Nesse nível, .claude/commands/ não é mais um diretório de atalhos. É uma pequena biblioteca de fluxos de trabalho que o time inteiro compartilha.