Command Arguments & Discoverability

Como expor os argumentos dos comandos slash `/k-*` (e demais comandos do context) de forma que o usuário os descubra e lembre. Diretriz mestra: **os parâmetros nunca moram no `description`** — moram no campo nativo `argument-hint` (autocomplete) e a referência completa fica no `/k-commands <cmd>`. O `description` responde só "o quê".

Problema que esta policy resolve

O autocomplete do Claude Code mostra o campo description do frontmatter do comando e trunca pelo fim. Quando a lista de parâmetros é enfiada dentro do description (prosa longa), os parâmetros — que ficam no fim — somem da exibição. O usuário não consegue lembrar quais flags existem nem o que cada uma faz.

São dois sub-problemas distintos, com dois mecanismos distintos:

Sub-problema Pergunta do usuário Mecanismo
Descoberta "quais flags esse comando tem?" argument-hint no autocomplete
Recall "o que --bg faz mesmo?" /k-commands <cmd> (referência completa)

1. Regra: parâmetros nunca no description

O description descreve o que o comando faz — uma frase, em pt-BR, alvo ≤ ~110 caracteres. Proibido enumerar flagsmodosparâmetros nele (Modos: --all, --slug ..., Flags: ..., O argumento $ARGUMENTS segue o formato ...). Esses trechos vão para o argument-hint e para o corpo.

❌ description: "Resumo do status. Modos: --all, --slug <mod>, --locks, --recap, --bg."
✅ description: "Responde 'Em que ponto estamos?' com um resumo do status."
   argument-hint: "[--all | --slug <mod> | --locks | --recap [N] | --bg]"

2. Regra: todo comando com argumentos tem argument-hint

Se o comando aceita qualquer argumento, o frontmatter deve ter a linha argument-hint, imediatamente após description. Sintaxe compacta:

  • opcionais entre [...]
  • posicionais / placeholders entre <...>
  • alternativas com |
  • alvo ≤ ~70 caracteres (compacto > exaustivo — a referência completa é o

    /k-commands <cmd>). Muitas flags? Liste as principais, não precisa todas.

Exemplos:

argument-hint: "<slug> [--device android|<servidor>]"
argument-hint: "[<módulo>] [--fast]"
argument-hint: "<termo> [--regex] [--since 7d] [--limit N]"

Comando sem argumentos (ex.: /k-commit, /k-housekeep, /k-ship): não recebe argument-hint.

3. Param vs. comando-sufixo — a regra de dois eixos

Owner-ratificado 2026-06-22 (substitui o antigo "default sempre flag, quase nunca comando novo"). Motivo: o uso real de parâmetros — sobretudo nomeados — é mínimo; uma lista plana de comandos-sufixo é, na prática, mais usável que flags escondidas. A escolha não é param-vs-sufixo em bloco — é por tipo de argumento.

Princípio motor — o comando base, sem args, faz o caso 90%. É por isso que o uso de parâmetros é (e deve seguir) mínimo: /k-go auto-detecta, /k-commit faz o fluxo todo, /k-save auto-descobre. Maximize o que o comando nu resolve ANTES de pensar em variante.

Para o resto, dois eixos:

Tipo de argumento Forma Por quê
Valor (módulo, ref, path, texto livre, lista 1,3) param (sempre) Não dá pra pré-enumerar <módulo> como sufixo.
Combinação (modo A × modo B) param O produto cartesiano é a explosão real — nunca vira N comandos.
Modo discreto frequente (gen-only, report-only, local/remote, um enum fixo) comando-sufixo (alias fino) É o que o owner de fato alcança; uma lista plana de /k-x-modo é MAIS descobrível que uma flag escondida.

Alias fino, não comando novo com lógica. O sufixo é UMA linha que despacha pro core param'd — /k-test-gen ≡ /k-test --gen-only. Há uma implementação e N nomes de entrada. Isso dissolve as duas objeções clássicas: não há duplicação de manutenção, e a "explosão" só existiria se cada combinação virasse comando com lógica própria — o que o eixo Combinação proíbe. (Precedentes já vivos: k-setup-local/-remote, k-test-gen-*, k-ia-compendium.)

Cunhar por uso, podar por desuso. Um alias-sufixo nasce quando o owner pega aquele modo repetidamente — não pré-gerando a matriz de modos. Alias morto é atrito: o /k-meta-tune varre e remove alias-sufixo sem uso (mesma disciplina "merece existir" do resto do meta).

Modos raros ou combinações que ficaram como flag têm a descoberta resolvida pelo argument-hint + /k-commands <cmd> (§2, §4) — não viram comando.

4. /k-commands <cmd> é a referência completa

/k-commands sem argumento lista todos os comandos (tabela). /k-commands <cmd> lê meta/context/commands/<cmd>.md e renderiza a tabela completa de parâmetros com a explicação de cada um (sem truncar, sob demanda). É aqui que o detalhe longo de cada flag vive — não no description.

5. Fonte de verdade

O corpo do arquivo do comando é a fonte de verdade dos argumentos (parsing de $ARGUMENTS, seção de uso, exemplos). A tabela do k-commands e o CLAUDE.md são derivados e podem ficar stale — ao divergirem, o corpo vence e os derivados se alinham a ele.

6. Não-objetivos

  • Não cobre o parsing de $ARGUMENTS em si (cabe a cada comando).
  • Não cobre comandos não-k-* de terceiros; mas a convenção (description

    enxuto + argument-hint) é recomendada para qualquer comando do context.