getedgehq/cli-ux-review

Revisión de UX de CLI

Audita una CLI contra una rúbrica fija, desde la perspectiva de un no desarrollador que nunca la ha usado.

Cuándo invocar

• "Auditoría de UX de CLI" / "revisa mi CLI" / "¿esta CLI es intuitiva?"
• Antes de cada lanzamiento de CLI
• Después de agregar o cambiar cualquier comando de CLI

El marco

Cada salida de comando debe responder tres preguntas: ¿Cuál es la situación? · ¿Cuáles son los próximos pasos? · ¿Qué puedo hacer?

Barra de calidad: un comando termina como Codex finaliza una sesión: una línea de estado simple, luego el comando exacto siguiente, renderizado en un color distintivo para que el ojo se dirija a "escribe esto".

Rúbrica (puntúa cada comando contra los 7 criterios)

1. Próximo paso presente. Cada éxito/estado terminal finaliza con el siguiente comando, o un explícito "has terminado". Ningún comando se detiene silenciosamente.
2. Los comandos están resaltados en color. Los comandos ejecutables se renderizan en un acento consistente (cian + negrita). Nunca texto simple, nunca comillas literales invertidas.
3. Sin internos crudos. Sin valores de enumeración, códigos de estado ni jerga en la salida del usuario. Palabras humanas más una leyenda de una línea ("sucio" se convierte en "ediciones locales").
4. Sin bloqueo silencioso. Los comandos de larga duración o de E/S estándar se anuncian en una TTY, para que la terminal nunca parezca congelada.
5. Primitivas consistentes. Un conjunto de glifos, un ayudante de filas/tablas, un bloque de próximo paso, compartidos entre comandos, no reinventados por comando.
6. Los errores incluyen la solución. Cada error nombra el comando exacto que lo resuelve.
7. Primer uso guiado. Una invocación simple o un estado de no haber iniciado sesión muestra un inicio rápido numerado.

Cómo ejecutar

1. Inventaria cada comando y cada ruta de salida. Lee el código fuente, no solo --help.
2. Para cada comando, recorre el camino de éxito, cada camino de error y los estados vacíos.
3. Puntúa contra los 7 puntos de la rúbrica. Cita archivo:línea para cada hallazgo.
4. Donde falle, escribe el antes/después concreto con las cadenas exactas.
5. Salida: problemas transversales, una tabla por comando, correcciones clasificadas antes/después y un plan de ejecución.

Formato de salida

Un documento de hallazgos: TL;DR y problema central, tabla de problemas transversales, hallazgos por comando, antes/después para cada corrección, plan de ejecución. Nunca escribas "se ve bien" sin haber recorrido la ruta de salida real que lo pruebe.