Desarrollar una CLI multiplataforma en un árbol de trabajo compartido sin estropear el trabajo ajeno

## Buscar y editar solo dentro del árbol de trabajo actual Cuando el desarrollo usa árboles de trabajo, el directorio de trabajo actual es el repositorio completo de la rama activa. Busca, lee, compila, prueba y edita únicamente dentro de esa raíz. - Usa rutas relativas o rutas resueltas bajo la raíz actual. - No supongas que un directorio superior es el repositorio. - No busques implementaciones ni configuraciones en árboles de trabajo hermanos. - Rechaza las rutas codificadas de forma fija al directorio personal de un desarrollador. - Resuelve las rutas de fixtures y código fuente desde la raíz activa. Salir del árbol de trabajo puede mezclar código obsoleto de otra rama con el análisis y los cambios. ## No restablecer ni borrar los cambios de otras sesiones Supón que los archivos y cambios desconocidos pueden pertenecer a otra sesión activa. Nunca elimines, restablezcas, descartes ni sobrescribas trabajo solo porque esté fuera de la tarea actual. - Conserva los archivos que no hayas creado. - Pregunta antes de retirar archivos sin seguimiento. - No ejecutes operaciones de restablecimiento, descarte mediante checkout, limpieza o eliminación de stashes sin aprobación explícita. - Si los hooks fallan por archivos que no tocaste, informa del conflicto en vez de modificarlos. - Limita los cambios al alcance solicitado e inspecciona la diferencia final. Trata el estado del árbol de trabajo compartido como datos del usuario cuya propiedad debe resolverse antes de una acción destructiva. ## Añadir comandos mediante un registro en vez de condicionales dispersos Usa un registro para que los comandos, proveedores e integraciones sean extensibles. Una implementación nueva debe satisfacer una interfaz estable y registrarse por una única ruta canónica, en lugar de añadir condiciones por toda la aplicación. - Define interfaces para el comportamiento principal. - Inyecta dependencias mediante constructores o campos. - Genera mocks con el generador admitido por el repositorio. - Usa opciones funcionales para configuraciones extensibles con valores predeterminados. - Mantén una implementación de comando por cada archivo con una responsabilidad definida. - Añade paquetes específicos en vez de ampliar un paquete genérico de utilidades. Busca en las capas existentes de comandos, ejecución y paquetes antes de introducir lógica paralela. ## Usar el contexto solo para cancelaciones y plazos, y pasar las banderas por un único analizador Usa el contexto de la solicitud únicamente para cancelación, plazos y unos pocos valores con alcance de solicitud. Cuando se acepte, pásalo como primer parámetro. No uses el contexto para ocultar configuración, dependencias ni parámetros ordinarios. Modela la configuración como una canalización determinista: 1. carga las fuentes de configuración; 2. procesa importaciones y herencia; 3. aplica la precedencia desde las banderas del comando, pasando por el entorno y los archivos, hasta los valores predeterminados; 4. renderiza las plantillas admitidas; 5. genera la configuración efectiva. Encamina las banderas y la vinculación del entorno mediante el analizador unificado. Al añadir una opción, actualiza todos los esquemas que la poseen y nunca eludas la capa central de vinculación. ## Enviar los datos para tuberías y los mensajes para personas a flujos distintos Escribe los resultados canalizables únicamente en el flujo de datos. Escribe las indicaciones, el progreso, las advertencias y los mensajes formateados para personas en el flujo de interfaz. Reserva el registro estructurado para eventos del sistema, no para la salida dirigida al usuario. - Usa abstracciones de I/O compartidas en vez de imprimir directamente. - Deja que la capa de UI gestione los colores, iconos, Markdown, ancho del terminal y detección de capacidades. - Degrada automáticamente la presentación cuando el terminal no admita estilos o la ejecución ocurra en integración continua. - Mantén válidos los datos estructurados cuando se desactive el formato para personas. - Aplica de manera coherente el enmascaramiento de secretos y no captures datos del usuario en la telemetría. Las banderas de prueba o grabación pueden forzar características del terminal, pero los valores predeterminados de producción deben seguir adaptándose al entorno. ## Mantener funciones pequeñas y envolver los errores con categorías estables Mantén enfocados los archivos y las funciones. Extrae pasos con nombre de la orquestación de alta complejidad para que la función de nivel superior se lea como una canalización plana. - Usa el formato, la agrupación de importaciones, los alias y la puntuación de comentarios definidos por el repositorio. - Conserva los comentarios útiles y actualízalos cuando cambie el comportamiento. - Aplica el seguimiento de rendimiento estándar a las operaciones públicas significativas. - Excluye accesores triviales, constructores, búsquedas puras y delegaciones simples cuando la política lo permita. - Envuelve los errores con categorías estables y conserva sus causas. - Combina fallos independientes sin perder ninguna cadena de errores. - Comprueba los errores envueltos mediante coincidencia semántica, no comparando cadenas. Usa constructores de errores enriquecidos cuando los usuarios necesiten sugerencias, contexto o semántica de salida. ## Probar el comportamiento con mocks y pruebas que de verdad puedan fallar Prefiere pruebas unitarias rápidas con mocks generados para el comportamiento aislado; después añade cobertura de integración o aceptación donde el comportamiento público del comando cruce límites reales. - Usa casos basados en tablas para cubrir entradas y errores. - Prueba el comportamiento, no la implementación interna. - Retira los stubs, las pruebas tautológicas y las pruebas omitidas permanentemente. - Para colecciones combinadas, modifica el resultado y la fuente en comprobaciones separadas a fin de demostrar el aislamiento bidireccional. - Para resultados de slices, verifica contenidos representativos además de la longitud. - Añade pruebas negativas que demuestren que la recuperación no se activa cuando falta su condición. - Usa coincidencia semántica de errores para los fallos envueltos. La cobertura solo es evidencia cuando las verificaciones pueden fallar por el comportamiento que protegen. ## Escribir pruebas que funcionen en todos los sistemas y fallen claramente si falta la preparación Las pruebas deben ejecutarse en las plataformas de escritorio y servidor admitidas sin suponer la existencia de un shell, un separador de rutas ni una utilidad específica de la plataforma. - Construye rutas a partir de componentes separados con la biblioteca estándar de rutas. - Normaliza los separadores solo para comparaciones portables de sufijos o de visualización. - Usa el ejecutable de prueba o un ejecutor inyectado en vez de comandos específicos de la plataforma. - Integra las puertas de subprocesos en un punto de entrada de prueba existente en lugar de definir otro duplicado. - Resuelve las raíces de los fixtures como rutas absolutas antes de recorrerlas o contarlas. - Haz que las protecciones de prerrequisitos y recuento de fixtures fallen claramente cuando falte la configuración. - Añade centinelas de compilación para los campos de esquema cuyo cambio de nombre deba romper la prueba. Verifica la propagación implícita del entorno en una subprueba explícita de prerrequisito antes de probar el comportamiento dependiente de un subproceso. ## Regenerar las instantáneas con las herramientas de prueba en vez de editarlas a mano Las instantáneas doradas incluyen formato invisible, ancho del terminal, estilos y salida sensible al entorno. Nunca las edites manualmente. - Regenera las instantáneas mediante la bandera de prueba o el generador admitidos. - Revisa la diferencia resultante antes de aceptarla. - No canalices las pruebas de instantáneas o terminal, porque la redirección puede cambiar la detección de capacidades. - Regenera juntas las grabaciones relacionadas cuando cambien la ayuda o la salida del comando. - Valida las grabaciones para detectar fallos del comando, referencias ausentes y filtraciones de rutas específicas de una máquina. - No cambies fixtures protegidos ni datos de prueba sin un alcance explícito. La salida generada debe cambiarse mediante su fuente propietaria y el flujo de trabajo canónico. ## Documentar cada comando nuevo y registrar como incidencia el trabajo aplazado Todo comando, bandera, parámetro o superficie de configuración nuevos necesitan documentación para el usuario con los metadatos, uso, ejemplos, argumentos, banderas y evidencia visual que exija el repositorio. - Verifica el identificador de página declarado en vez de adivinar una URL a partir del nombre del archivo. - Compila el sitio de documentación después de los cambios y comprueba enlaces, imágenes y componentes. - Regenera capturas visuales cuando cambien el comportamiento, la ayuda o la salida del comando, no para ediciones solo de prosa. - Coloca los documentos de requisitos en la ubicación y con la convención de nombres designadas. - Cuando se aplace trabajo, crea una incidencia con seguimiento y enlaza su identificador antes de la fusión. - Mantén las notas de versión, los datos de la hoja de ruta y las etiquetas alineados con la clase de cambio. La documentación está incompleta cuando promete un seguimiento que no se ha registrado. ## Actualizar las revisiones sin saltarse los hooks ni usar comandos Git destructivos Usa el flujo de revisión del repositorio y limita la automatización de mantenimiento recurrente a la sesión, salvo que se autorice explícitamente un servicio persistente. - Haz rebase o actualiza únicamente mediante el proceso de rama aprobado. - Comprueba la integración continua y atiende los hilos de revisión sin resolver. - Responde dentro del hilo de revisión original y verifica la vinculación. - Ejecuta el lint y la cobertura de pruebas limitados al parche antes de actualizar la revisión. - No eludas los hooks ni uses banderas que omitan la verificación. - No confirmes notas provisionales, investigaciones ni marcadores de posición sin resolver. Nunca ejecutes comandos destructivos de Git ni retires el trabajo de otra sesión sin confirmación explícita de lo que se perderá. ## Reproducir cada fallo con una prueba primero y corregir la causa de las comprobaciones fallidas Para un error, escribe primero una prueba que lo reproduzca, observa el fallo, implementa la corrección mínima y comprueba que no haya regresiones. Antes de terminar, confirma: - el proyecto compila con la cadena de herramientas fijada; - los archivos cambiados superan el formateador y el linter canónicos; - las pruebas breves pasan, y se ejecutan las pruebas completas o de aceptación cuando la ruta afectada lo requiere; - la cobertura cumple el umbral exigido sin verificaciones teatrales; - los mocks, esquemas, instantáneas, documentos y capturas visuales generados están actualizados; - se siguen cumpliendo los límites de complejidad y tamaño de archivo; - las rutas multiplataforma y las pruebas de subprocesos son portables; - no se han incorporado a la diferencia secretos, datos del usuario ni trabajo ajeno. Corrige la causa de cada puerta fallida en lugar de debilitarla.