Revisão de UX de CLI
Audita uma CLI contra uma rubrica fixa, a partir da perspectiva de um não desenvolvedor que nunca a utilizou.
Quando invocar
- "Auditoria de UX de CLI" / "revise minha CLI" / "esta CLI é intuitiva"
- Antes de todo lançamento de CLI
- Após adicionar ou alterar qualquer comando da CLI
O enquadramento
Cada saída de comando deve responder a três perguntas: Qual é a situação? · Quais são os próximos passos? · O que posso fazer?
Padrão de qualidade: um comando termina da mesma forma que o Codex encerra uma sessão — uma linha de status simples, seguida pelo próximo comando exato, renderizado em uma cor distinta para que o olho se fixe em "digite isto".
Rubrica (pontue cada comando contra todos os 7)
- Próximo passo presente. Todo estado de sucesso / terminal termina com o próximo comando, ou um explícito "você terminou". Nenhum comando para silenciosamente.
- Comandos são destacados em cor. Comandos executáveis são renderizados em um destaque consistente (ciano + negrito). Nunca texto simples, nunca crases literais.
- Sem detalhes internos. Sem valores de enum, códigos de estado ou jargão na saída para o usuário. Palavras humanas mais uma legenda de uma linha ("dirty" vira "edições locais").
- Sem travamento silencioso. Comandos de longa duração ou de E/S padrão se anunciam em um TTY, para que o terminal nunca pareça congelado.
- Primitivas consistentes. Um conjunto de glifos, um auxiliar de linha/tabela, um bloco de próximo passo, compartilhados entre comandos, não reinventados por comando.
- Erros incorporam a correção. Todo erro nomeia o comando exato que o resolve.
- Primeira execução guiada. Invocação simples ou estado não logado mostra um guia de início rápido numerado.
Como executar
- Inventarie todos os comandos e todos os caminhos de saída. Leia o código-fonte, não apenas
--help. - Para cada comando, percorra o caminho de sucesso, cada caminho de erro e estados vazios.
- Pontue contra os 7 pontos da rubrica. Cite
arquivo:linhapara cada achado. - Onde falhar, escreva o antes / depois concreto com as strings exatas.
- Saída: problemas transversais, uma tabela por comando, correções classificadas antes/depois e um plano de execução.
Formato de saída
Um documento de achados: TL;DR e problema central, tabela de problemas transversais, achados por comando, antes/depois para cada correção, plano de execução. Nunca escreva "parece ok" sem ter percorrido o caminho de saída real que o comprove.