O que CLI Help Layers: Guia de Design de Ajuda em Camadas faz?
Oferece diretrizes de design para interação de linha de comando e sistema de documentação de CLIs AI-First. Leitores principais: desenvolvedores humanos + LLM/Agent.
Três Princípios de Design
- Divulgação Progressiva: usage → help → man, densidade de informação aumenta progressivamente, agentes precisam apenas das duas primeiras camadas na maioria dos cenários
- Exemplos como Padrão: inspirado no tldr, cada camada de documentação ancora em exemplos executáveis
- Estruturação como Prioridade: delimitadores fixos e convenções de formato facilitam a extração zero-shot por LLMs
Arquitetura de Quatro Camadas
| Gatilho | Camada | Cobertura | Conteúdo |
|---|---|---|---|
| Comando sem argumentos | @USAGE | 80% | BRIEF + SYNTAX + 3-5 EXEMPLOS |
-h / --help | @HELP | 95% | Tabela OPTIONS + ENUMS + ERROS COMUNS |
Subcomando --help | @HELP sub | 98% | Opções específicas + OPÇÕES HERDADAS + TEMPLATE |
--man | @MAN | 100% | SCHEMA + CÓDIGOS DE SAÍDA + TODOS OS ERROS + RESSALVAS |
Marcadores Estruturados
@USAGE <caminho> / @HELP <caminho> / @MAN <caminho> → Identificador de camada
BRIEF: / SYNTAX: / OPTIONS: / ENUMS: / EXEMPLOS: / ERROS: → Rótulo de bloco
# [RECOMENDADO] / [TEMPLATE] / [PIPELINE] / [AVANÇADO] → Rótulo de exemplo
Regex do Agente: ^@(USAGE|HELP|MAN)\\s+(.+)$, bloco: ^([A-Z ]+):$
Fluxo de Trabalho
Ao projetar ou revisar documentação de ajuda CLI:
- Determinar estrutura do comando → Consulte
references/architecture.md(regras de nomenclatura, organização substantivo-verbo) - Escrever Usage → Consulte
references/usage-spec.md(template + princípios de seleção de exemplos) - Escrever Help → Consulte
references/help-spec.md(tabela OPTIONS + enumerações + Ajuda de Subcomando) - Escrever Man → Consulte
references/man-spec.md(SCHEMA + CÓDIGOS DE SAÍDA + códigos de erro completos) - Projetar mensagens de erro → Consulte
references/error-design.md(codificação de erros + estratégia de incorporação em cada camada) - Otimizar amigabilidade para Agent → Consulte
references/agent-friendly.md(estilo de texto + sistema de marcadores + processo de divulgação) - Verificar checklist → Consulte
references/checklist.md(checklist de cinco dimensões) - Consultar exemplo completo → Consulte
references/example-feishu-doc.md(prática completa de três camadas da família de comandos feishu doc)
Escopo de Aplicação
Não use esta skill para:
- Implementação real de código de ferramentas CLI (cuida apenas do design da documentação)
- Design de documentação de API não-CLI
- Execução e depuração de ferramentas CLI existentes