Como Adicionar Flags a Comandos Slash do Claude Code: 4 Padrões Que Realmente Funcionam

Como Adicionar Flags aos Comandos Slash do Claude Code: 4 Padrões Que Realmente Funcionam

O Claude Code não faz parsing de --flags da forma que esperarias para comandos slash personalizados, mas quatro padrões oferecem o mesmo UX, e três deles são mais limpos do que o parsing de CLI alguma vez foi. Eis como adicionar flags aos comandos slash do Claude Code corretamente, com ficheiros .md funcionais que podes copiar hoje mesmo.

Resposta Rápida:

• O Claude Code não faz parsing de flags de CLI (--json, --verbose) para comandos personalizados — a utilização não dispõe de um parser de flags.
• Para um UX ao estilo CLI, escreve as flags em $ARGUMENTS e deixa o LLM interpretá-las como linguagem natural.
• Para argumentos tipados, usa $1/$2 posicionais ou argumentos nomeados declarados no campo arguments: do frontmatter.
• Documenta as flags esperadas em argument-hint: para que o autocomplete do / as mostre ao utilizador.

Como Funcionam Realmente os Argumentos dos Comandos Slash do Claude Code?

O mecanismo do Claude Code substitui três tipos de tokens antes de enviar o comando ao LLM: $ARGUMENTS (a string completa após o nome do comando), os posicionais $0/$1/$2 (segmentos entre aspas ao estilo shell) e os nomeados $variableName declarados no frontmatter. Não existe um analisador de flags de CLI integrado; --dry-run acaba em $ARGUMENTS como texto literal.

É aqui que toda a gente se confunde. Quando se escreve /deploy --staging --dry-run, o Claude Code não executa o argparse sobre --staging --dry-run. O mecanismo cola essa string inteira onde quer que o ficheiro .md referencie $ARGUMENTS e depois envia o prompt renderizado ao modelo. O LLM vê --staging --dry-run como texto simples e decide o que fazer.

Isto não é um bug, é assim que foi concebido. O mecanismo é uma camada de substituição, não um analisador. Os comandos integrados como /clear e /help (ver a referência oficial da CLI) têm flags, mas os comandos personalizados que o utilizador cria seguem regras diferentes.

O mecanismo do Claude Code substitui tokens e depois entrega o prompt renderizado ao LLM. Não existe um analisador de flags.

No nosso próprio trabalho com o Claude Code, a confusão mais comum é exatamente esta: os programadores passam uma hora a tentar perceber porque é que --verbose "não está a ser detetado" antes de perceberem que o LLM é o analisador. A partir do Claude Code v2.1.126 (maio de 2026), este comportamento está documentado na documentação oficial de comandos slash e não deverá mudar tão cedo. Os comandos slash são um primitivo irmão dos hooks do Claude Code — ambos estendem o mecanismo, mas os comandos são acionados pelo input do utilizador enquanto os hooks são acionados por eventos de ferramentas.

Eis o comando personalizado mais pequeno possível que prova o modelo de substituição:

---
description: Echo whatever the user types after the command
argument-hint: [anything]
---

The user passed these arguments: $ARGUMENTS

Repeat them back verbatim, then describe what the user probably meant.

Guarde-o como .claude/commands/echo-args.md, escreva /echo-args hello world --foo e o LLM verá a string literal hello world --foo substituída no prompt. Este é todo o modelo mental. Para uma explicação mais aprofundada de como os ficheiros de comandos se relacionam com o sistema de skills mais amplo, consulte o nosso guia introdutório de Skills.

Cria o Teu Primeiro Comando Slash Paramétrico em 5 Minutos

Cria o ficheiro .claude/commands/greet.md com três linhas de frontmatter e uma linha de prompt que referencia $ARGUMENTS. Reinicia o Claude Code, escreve /greet World e vê o World ser substituído no prompt antes de o LLM o ver. É esta a cerimónia toda, cinco passos, sem ferramentas de build.

Aqui está a receita, de ponta a ponta:

1. Cria o diretório. A partir da raiz do teu projeto, executa mkdir -p .claude/commands. A pasta .claude/ fica ao lado do teu código; os comandos dentro dela são descobertos automaticamente quando o Claude Code inicia uma sessão.
2. Escreve o ficheiro do comando. Guarda o excerto abaixo como .claude/commands/greet.md.
3. Recarrega a sessão. Sai e volta a abrir o Claude Code (ou executa /reload se a tua versão o suportar). Os comandos são lidos uma única vez no início da sessão.
4. Invoca-o. Escreve /greet World no chat.
5. Verifica a substituição. Abre a transcrição e confirma que o LLM viu World interpolado no corpo do prompt, e não o token literal $ARGUMENTS.

Aqui está o ficheiro completo:

---
description: Greet someone enthusiastically
argument-hint: <name>
---

You are a friendly assistant. Greet the person named "$ARGUMENTS" with one short, warm sentence. Then ask them what they're working on today.

E a interação no terminal:

> /greet World
Hey World, great to see you! What are you working on today?

E está feito. Agora tens um comando slash paramétrico. O campo argument-hint é o que faz o menu de autocomplete do / mostrar <name> ao lado do teu comando, um pequeno toque de UX, com grande retorno.

Se o $ARGUMENTS não for substituído, 9 em cada 10 vezes é porque escreveste $args ou $ARGS, o token é literal, em maiúsculas.

O token distingue maiúsculas de minúsculas e é exato. $ARGUMENTS funciona. $arguments, $args, $ARGS, ${ARGUMENTS} falham todos silenciosamente, são enviados ao LLM como texto literal e o modelo só vê lixo. Verifica três vezes a ortografia antes de assumires um bug mais profundo.

Que Campos de Frontmatter Controlam o Tratamento de Argumentos?

Cinco campos de frontmatter determinam a forma como um comando slash trata os argumentos: argument-hint (o que o autocomplete mostra), allowed-tools (o que o comando pode invocar), arguments (declaração de argumentos nomeados), model (que variante do Claude o executa) e disable-model-invocation (restringe o comando a invocação exclusiva pelo utilizador). Em conjunto, cobrem praticamente todos os padrões paramétricos de que irá precisar.

Eis a referência completa de frontmatter para comandos personalizados do Claude Code v2.1.x:

Duas armadilhas que vale a pena fixar no ecrã. Primeira: allowed-tools é separado por espaços, não por vírgulas. Escrever Bash(git:*), Read, Edit falhará silenciosamente na atribuição de permissões — o parser trata a cadeia inteira como uma única entrada malformada. Use Bash(git:*) Read Edit. Aprendemos isto da forma mais difícil; para mais padrões como este, consulte as nossas boas práticas de CLAUDE.md sobre convenções de ficheiros de configuração.

Segunda: o campo model: substitui qualquer que seja o modelo que o utilizador tenha atualmente selecionado para a sessão. Útil quando um comando é computacionalmente leve e pretende forçá-lo para uma variante mais pequena — consulte o nosso guia sobre seleção de modelos para escolher entre o Opus 4.7 e o Sonnet para diferentes tipos de comandos.

O campo disable-model-invocation: true é a sua rede de segurança para comandos destrutivos. Defina-o em /deploy-prod ou /drop-database e os outros agentes não poderão invocar esses comandos programaticamente — apenas um humano a escrever no chat os poderá acionar.

Quais São os 4 Padrões de Argumentos Que Vai Realmente Usar?

Quatro padrões cobrem aproximadamente 95% dos comandos slash reais do Claude Code: (1) flag booleano, como /deploy --dry-run, analisado pelo LLM a partir de $ARGUMENTS; (2) flag com valor, como /test --filter auth, extraído de $ARGUMENTS; (3) posicional obrigatório + flag opcional, como /fix-issue 123 --priority high, misturando $1 e $ARGUMENTS; e (4) posicional estritamente tipado, como /migrate-component SearchBar React Vue, usando $0/$1/$2.

Escolha aquele que melhor corresponder à forma do seu comando. Aqui está um ficheiro .md funcional para cada um.

Padrão 1: Flag booleano (--dry-run)

Quando queres a experiência de utilização de uma flag de CLI e a flag é apenas ligada/desligada, confia no LLM para a detetar dentro de $ARGUMENTS. Sem lógica de parsing, sem malabarismos posicionais — basta descrever a regra no prompt.

---
description: Deploy to staging or production
argument-hint: [--dry-run]
allowed-tools: Bash(git:*) Bash(npm:*) Read
---

Deploy the current branch to staging.

Arguments passed: $ARGUMENTS

If "$ARGUMENTS" contains "--dry-run", DO NOT actually deploy. Instead, print the deployment plan: which files would change, which env vars would be set, and which commands would run. Stop after printing the plan.

Otherwise, proceed with the real deployment using `git push staging main` and `npm run deploy:staging`.

Escreve /deploy --dry-run e o LLM vê a flag, imprime o plano e para. Escreve /deploy e ele envia. O utilizador não fez qualquer parsing, o LLM fez todo o trabalho — que é exatamente aquilo em que ele é bom.

Padrão 2: Flag com Valor (--filter <pattern>)

A mesma ideia, mas agora a flag transporta um valor. O LLM lê --filter auth a partir de $ARGUMENTS e utiliza a substring que se segue.

---
description: Run the test suite, optionally filtered
argument-hint: [--filter <pattern>]
allowed-tools: Bash(npm:*) Read
---

Run the project's test suite.

Arguments: $ARGUMENTS

If "$ARGUMENTS" contains "--filter <pattern>", run only tests matching <pattern>. Use `npm test -- --grep <pattern>` for the actual command.

If no `--filter` is present, run the full suite with `npm test`.

Report pass/fail counts at the end.

/test --filter auth executa apenas os testes de autenticação. /test executa tudo. O LLM extrai o padrão após --filter de forma fiável, porque o Claude é genuinamente bom neste tipo de extração de texto estruturado — bastante mais fiável do que as pessoas esperam.

Padrão 3: Posicional obrigatório + flag opcional

Este é o híbrido que mais usamos na nossa própria biblioteca de comandos. O $1 contém o argumento obrigatório, o $ARGUMENTS contém tudo (para que o LLM ainda consiga detetar as flags opcionais). É a combinação mais limpa quando um argumento é inegociável e o resto é contexto livre.

---
description: Fix a GitHub issue
argument-hint: <issue-number> [--priority high|medium|low] [context...]
allowed-tools: Bash(gh:*) Bash(git:*) Read Edit
---

Fix GitHub issue #$1.

Full arguments: $ARGUMENTS

Steps:
1. Run `gh issue view $1` to load the issue body.
2. Read the codebase to locate the relevant file(s).
3. If "$ARGUMENTS" contains "--priority high", create a hotfix branch off main. Otherwise branch off develop.
4. Apply the fix, run tests, and open a PR linked to the issue.

Anything else in $ARGUMENTS after the issue number is freeform context — fold it into your understanding of the bug.

Invoque como /fix-issue 1234 --priority high the login form blanks the email field after a failed attempt. O $1 resolve-se para 1234. O $ARGUMENTS resolve-se para toda a string subsequente, que o LLM analisa de bom grado, tanto a flag de prioridade como a descrição livre.

Usamos exatamente esta combinação $1 + $ARGUMENTS no nosso comando /fix-issue, $1 para o número da issue, o resto para contexto livre que o LLM analisa. Tem sido o padrão com maior ROI ao longo de um ano de utilização diária do Claude Code.

Padrão 4: Posicional Estrito (Com Tipos)

Quando todos os argumentos são obrigatórios e a ordem importa, elimine completamente o $ARGUMENTS. Utilize $0/$1/$2 (ou argumentos nomeados através do campo de frontmatter arguments:) para slots com tipos inequívocos.

---
description: Migrate a component between frameworks
argument-hint: <component> <from-framework> <to-framework>
arguments: [component, fromFramework, toFramework]
allowed-tools: Read Edit Write
---

Migrate the component named "$component" from $fromFramework to $toFramework.

1. Read the existing component file (search for `$component.{jsx,tsx,vue,svelte}`).
2. Translate the component idioms from $fromFramework to $toFramework: lifecycle methods, state handling, prop syntax, event binding.
3. Write the new file in the matching extension for $toFramework.
4. Print a diff summary at the end.

If $fromFramework or $toFramework is unsupported, abort and tell the user which frameworks ARE supported (React, Vue, Svelte, Solid).

Invoque como /migrate-component SearchBar React Vue. A declaração de argumentos nomeados torna o autocomplete e o corpo do prompt autoexplicativos — qualquer pessoa que leia o migrate-component.md consegue perceber, num relance, qual slot corresponde a quê. Este padrão destaca-se em comandos com três ou mais argumentos obrigatórios. Também pode ver este estilo em bibliotecas da comunidade, como a wshobson/commands no GitHub.

Os flags booleanos e de valor funcionam porque o LLM é um parser flexível. O posicional estrito funciona porque não é necessária qualquer inteligência do LLM. Misturar os dois é o segredo.

Quando Deve Usar $ARGUMENTS vs Posicionais vs Nomeados?

Use $ARGUMENTS quando os argumentos forem do estilo de flags de CLI e pretender uma análise flexível por parte do LLM. Use os posicionais $1/$2 quando os argumentos forem tipados, ordenados, e pretender zero ambiguidade para o LLM. Use os nomeados arguments: quando houver 3 ou mais argumentos e a clareza no autocompletar importar mais do que a concisão. Eis a matriz de decisão:

O instinto da maioria dos programadores é recorrer primeiro ao $ARGUMENTS, porque lhes parece mais próximo do mundo bash que conhecem. Isso é aceitável para protótipos, mas os posicionais tipados são genuinamente melhores quando o contrato é estável. O LLM não precisa de analisar $1; já é uma string limpa.

Uma regra prática aproximada: se consegue descrever a assinatura do comando numa frase em inglês sem usar as palavras "or" e "optionally", use posicionais. Se precisar dessas palavras, use $ARGUMENTS.

Os Slash Commands são agora o mesmo que as Skills?

A Anthropic integrou os comandos personalizados no sistema mais alargado de skills na primavera de 2026, mas os ficheiros .claude/commands/*.md continuam a funcionar e usam o mesmo frontmatter. Uma skill é um diretório (.claude/skills/foo/SKILL.md mais ficheiros de suporte) com controlo de invocação adicional, como disable-model-invocation. Um comando é um único ficheiro .md. As mesmas regras de substituição, empacotamento diferente.

Eis a diferença prática:

Portanto não, .claude/commands/ não está descontinuado. A Anthropic manteve explicitamente o formato de ficheiro a funcionar quando integrou os sistemas — demasiados projetos têm bibliotecas de comandos fixadas no controlo de versões. Se quiser ficheiros de suporte (como uma referência CONTRIBUTING.md que a sua skill carrega, ou um template.json que ela copia), opte pelas skills. Caso contrário, fique com os comandos.

Esta integração faz parte de um esforço mais amplo em torno do padrão aberto agentskills.io, e é uma das várias alterações na v2.1.x que vale a pena conhecer — veja o nosso resumo das funcionalidades do Claude Code v2.1 para o panorama completo de funcionalidades e o nosso tutorial de skills para um guia mais aprofundado sobre skills.

Porque é que o meu $ARGUMENTS não está a ser substituído? Erros comuns corrigidos

Cinco razões comuns pelas quais $ARGUMENTS falha na substituição: (1) token em minúsculas ou abreviado ($args, $ARGS, $arguments — tem de ser literalmente $ARGUMENTS), (2) argumentos com várias palavras sem aspas (/cmd hello world separa; /cmd "hello world" mantém tudo junto), (3) allowed-tools separados por vírgulas em vez de espaços, (4) ficheiro de comandos fora de .claude/commands/ ou .claude/skills/, (5) a sessão do Claude Code precisa de ser recarregada após editar o ficheiro.

$ARGUMENTS está a aparecer literalmente no prompt do LLM

Sintoma: O seu prompt mostra $ARGUMENTS como texto simples na resposta do modelo, como se o uso o tivesse ignorado. Causa: Capitalização incorreta ou ortografia errada. O token é literalmente $ARGUMENTS, oito caracteres, tudo em maiúsculas. Correção: Abra o .md, procure com grep por $args, $ARGS, $arguments, ${ARGUMENTS} e substitua por $ARGUMENTS. O bug do erro ortográfico $args já afetou todos os programadores da nossa equipa pelo menos uma vez; é o bug de maior volume na família "unknown slash command".

Argumento com várias palavras está a ser dividido inesperadamente

Sintoma: Executou /migrate-component Search Bar React Vue e $1 é Search, $2 é Bar. Causa: Os espaços em branco dividem os argumentos posicionais. Correção: Coloque o argumento com várias palavras entre aspas: /migrate-component "Search Bar" React Vue. Agora $1 é Search Bar. Isto corresponde ao comportamento da shell, que é o modelo mental que o comando replica deliberadamente.

allowed-tools não está a ser respeitado

Sintoma: O comando é executado, mas o Claude recusa-se a invocar as ferramentas que julgava ter autorizado, ou invoca ferramentas que não indicou. Causa: Estão separadas por vírgulas em vez de espaços. Correção: Altere allowed-tools: Bash, Read, Edit para allowed-tools: Bash Read Edit. Para subpadrões de ferramentas, use o formato Bash(git:*) Bash(npm:*) Read.

Comando não aparece no autocompletar de /

Sintoma: Ao escrever /, o seu comando não está na lista. Causa: Localização do ficheiro, frontmatter em falta ou disable-model-invocation configurado incorretamente. Solução: Confirme que o ficheiro se encontra em .claude/commands/yourcmd.md (ou .claude/skills/yourcmd/SKILL.md) relativamente à raiz do seu projeto. Confirme que o frontmatter tem, pelo menos, um campo description:. Se definir disable-model-invocation: true, o comando não será apresentado a outros agentes, mas continuará a aparecer no menu / escrito pelo utilizador.

Editou o ficheiro .md, mas nada mudou

Sintoma: Corrigiu o bug, guardou o ficheiro, voltou a executar o comando, e o mesmo comportamento incorreto persistiu. Causa: O Claude Code coloca os ficheiros de comandos em cache no início da sessão. Solução: Saia e reinicie o Claude Code, ou execute /reload se a sua versão o suportar.

O Claude Code lê os ficheiros .md no início da sessão. Se editar um comando e este "não mudar", reinicie a sessão antes de assumir que se trata de um bug mais profundo.

Para casos extremos para além destes cinco, os issues do repositório do Claude Code são o melhor local para pesquisar. A maioria dos bugs de substituição estranhos que vimos são alguma variante de um dos casos acima.

FAQ: Argumentos de Comandos Slash do Claude Code

Como passo argumentos para um comando slash do Claude Code?

Escreva a string de argumentos após o nome do comando: /greet World. Dentro do ficheiro .md do seu comando, referencie o valor como $ARGUMENTS (a string completa), $1 (o primeiro argumento posicional) ou $variableName (se declarou arguments: [variableName] no frontmatter). O utilizador substitui o token antes de enviar o prompt para o LLM.

O que é $ARGUMENTS no Claude Code?

$ARGUMENTS é um token de substituição em ficheiros de comandos de barra personalizados que o Claude Code utiliza para substituir toda a cadeia de argumentos que o utilizador introduziu após o nome do comando. Se um utilizador executar /deploy --staging --dry-run, então $ARGUMENTS torna-se a cadeia literal --staging --dry-run dentro do prompt renderizado, antes mesmo de o LLM o ver.

Os comandos slash do Claude Code aceitam flags ao estilo CLI, como --json?

Nativamente não — o utilizador não dispõe de um analisador de flags para comandos personalizados. Escreve --json em $ARGUMENTS e o seu prompt instrui o LLM a detetá-lo e a agir em conformidade. Isto funciona porque o Claude é um analisador flexível de texto estruturado. Os comandos integrados, como /clear e /help, têm flags reais, mas os comandos personalizados que criar seguem apenas as regras de substituição.

Qual é a diferença entre $1, $ARGUMENTS e $name no Claude Code?

$1 é o primeiro argumento posicional separado por espaços em branco ($2 é o segundo, e assim por diante). $ARGUMENTS é a cadeia de argumentos completa, exatamente como foi introduzida, incluindo todas as partes posicionais e quaisquer flags. $name é um argumento nomeado declarado no campo arguments: [name] do frontmatter, útil quando se pretende slots posicionais autodocumentados sem indexação numérica.

Como funciona o argument-hint no Claude Code?

argument-hint é um campo de frontmatter que controla o que o menu de autocomplete de / apresenta junto ao nome do comando. Definir argument-hint: <issue-number> [--priority high] apresenta exatamente esse modelo depois de o utilizador digitar /. É apenas UX — não valida nem interpreta argumentos. Ainda assim, vale a pena defini-lo, porque é a documentação mais barata que alguma vez irá escrever.

Como crio um comando slash personalizado com vários argumentos?

Duas opções limpas. Para argumentos posicionais: referencie $1, $2, $3 no corpo do prompt. Para argumentos nomeados: declare arguments: [first, second, third] no frontmatter e referencie $first, $second, $third. Os nomeados são mais legíveis com três ou mais argumentos. Use $ARGUMENTS apenas quando quiser que o LLM analise uma string livre no final, depois dos slots posicionais obrigatórios.

O .claude/commands/ está descontinuado em favor do .claude/skills/?

Não. A Anthropic fundiu os dois sistemas na primavera de 2026, mas manteve explicitamente o .claude/commands/*.md a funcionar com regras de substituição idênticas. Utilize os comandos para automatizações de ficheiro único e as skills para pacotes de múltiplos ficheiros (SKILL.md mais modelos ou referências). Mesmo frontmatter, mesmo comportamento de $ARGUMENTS, apenas o empacotamento é diferente. Ambos são de primeira classe desde a v2.1.126.

Porque é que $ARGUMENTS não está a ser substituído no meu comando?

Três causas principais, por ordem de frequência: erro de capitalização (tem de ser $ARGUMENTS em maiúsculas, não $args nem $arguments), localização do ficheiro incorreta (tem de estar em .claude/commands/ ou .claude/skills/), ou sessão desatualizada (o Claude Code lê os ficheiros de comandos no início da sessão, por isso reinicia após editar). Se as três causas estiverem corretas, executa /echo-args foo com o exemplo mínimo da secção H2 #1 para isolar o problema.

Posso exigir certos argumentos?

Não ao nível da utilização — não existe validação nativa de argumentos obrigatórios. O padrão consiste em instruir o LLM no seu prompt: "Se $1 estiver vazio, para e pede ao utilizador que forneça um número de issue." O modelo faz cumprir o contrato. Não é infalível, mas na prática é suficientemente fiável para utilização diária, especialmente quando combinado com um argument-hint claro.

O model: no frontmatter sobrepõe-se às flags da CLI?

Sim, o frontmatter tem prioridade. Se o ficheiro de comando declarar model: claude-haiku-4, esse comando é executado no Haiku, independentemente do modelo que o utilizador selecionou para a sessão. Isto é útil para comandos económicos, invocados com frequência, que pretende manter fora do Opus. Consulte o nosso guia sobre mudar de modelos do Claude para escolher a variante certa para cada tipo de comando.

Conclusão

Quatro padrões. Escolha o que melhor se adequa ao formato do seu comando:

• Flag booleano (--dry-run), escreva-o em $ARGUMENTS e deixe o LLM detetá-lo.
• Flag com valor (--filter <pattern>), a mesma abordagem — o LLM extrai o valor.
• Posicional obrigatório + flag opcional, $1 para o argumento indispensável, $ARGUMENTS para o resto.
• Posicional estrito, $0/$1/$2 (ou com nomes via arguments:) quando todos os parâmetros são obrigatórios e ordenados.

Agora que os seus comandos são paramétricos, o passo seguinte é integrá-los em fluxos de trabalho de agentes — comece pelo nosso tutorial de Claude Skills para a melhoria de empacotamento em múltiplos ficheiros, ou explore ferramentas de codificação com IA alternativas se estiver a comparar plataformas. De uma forma ou de outra, a sua pasta .claude/commands/ acaba de ficar muito mais útil.