Edita un monorepositorio tipado sin romperlo y mantén al día su wiki

## Encuentra qué paquetes, pruebas y documentos toca un cambio Trata las directrices raíz para agentes como el contrato compartido por todos los agentes de programación. Todo archivo de instrucciones específico de una herramienta debe mantenerse conciso y remitirse a ese contrato en lugar de duplicarlo. - Identifica dónde se encuentran los paquetes principales, las integraciones opcionales, las herramientas para desarrolladores, los módulos del ecosistema, los ejemplos, la documentación y las pruebas. - Espera que las pruebas y sus fixtures estén cerca del paquete que comprueban, salvo que el repositorio indique lo contrario. - Lee las directrices del paquete más cercano antes de editar un subsistema. - Antes de tocar archivos, vincula el cambio solicitado con el paquete al que pertenece, su superficie pública, sus pruebas y su documentación. - Prefiere el menor ámbito afectado; no conviertas una tarea específica en una reescritura de todo el repositorio. ## Usa el gestor de paquetes y los scripts del repositorio Usa el gestor de paquetes, la definición del espacio de trabajo, la versión del entorno de ejecución y los scripts declarados por el repositorio. No los sustituyas por una alternativa conocida solo porque esté instalada localmente. - Usa el comando de instalación documentado para preparar las dependencias del espacio de trabajo. - Usa los scripts raíz de compilación, pruebas, linting y comprobación de tipos para realizar verificaciones completas. - Usa los filtros de espacio de trabajo compatibles para centrar el trabajo en un paquete. - Conserva exactamente el reenvío de argumentos cuando un envoltorio pase opciones a una herramienta subyacente. - Revisa los archivos de configuración del repositorio antes de cambiar supuestos sobre el gestor de paquetes o el entorno de ejecución. - Registra cualquier requisito previo del que dependa un comando de ámbito más reducido. ## Ejecuta las pruebas en el orden de la CI sin compilaciones obsoletas Reproduce el orden de la integración continua en lugar de inventar una secuencia local. Si la CI instala las dependencias y ejecuta su comando de validación sin compilar primero, ejecuta las pruebas del mismo modo. - No compiles primero cuando los resultados generados puedan detectarse junto a los archivos fuente. - Interpreta los errores de registro duplicado, esquema duplicado o clase decorada duplicada como posibles indicios de que se cargaron tanto los archivos fuente como los generados. - Elimina únicamente los directorios de resultados generados situados bajo las raíces de código fuente documentadas, y excluye las dependencias, las pruebas y los fixtures. - Nunca elimines directorios de código fuente para resolver un fallo causado por resultados generados. - Tras la limpieza, vuelve a ejecutar la prueba que falla antes de modificar el código de implementación. - Si la limpieza no cambia el fallo, retoma la depuración habitual con las nuevas evidencias. ## Sigue el estilo del código y no guardes el estado de la app en globales Prefiere los patrones establecidos en el repositorio a las abstracciones nuevas. Usa el sistema de módulos, las convenciones del lenguaje tipado, el formateador, el linter y el estilo de nombres de archivo ya adoptados por el código. - Mantén los nombres de archivo en minúsculas y separados por guiones cuando esa sea la convención del repositorio. - Haz que los cambios de la API pública sean deliberados, estén cubiertos por pruebas y queden documentados. - Mantén el estado mutable de ejecución específico de una aplicación en un ámbito propiedad de esa aplicación, no en un singleton global del proceso. - Usa el almacenamiento por ámbitos del framework para las utilidades del ciclo de vida y otros servicios propios de cada aplicación. - Vuelve a entrar en el ámbito de la aplicación propietaria para callbacks desvinculados, como temporizadores, escuchas de eventos, manejadores de proxy y puntos de escape en el ámbito del módulo. - No añadas envoltorios de ámbito redundantes alrededor de accesores ya fijados al contexto correcto de la aplicación. ## Haz que los módulos cargados al inicio no rompan las instantáneas de inicio Cuando un entorno de ejecución pueda serializar una instantánea de inicio, asume que el arranque durante la compilación puede detenerse antes del inicio normal de la aplicación. Todo módulo cargado durante esa fase debe poder serializarse con seguridad. - Mantén los módulos como externos cuando el trabajo realizado durante la importación o el arranque cree estado nativo no serializable. - Considera los analizadores HTTP, los enlaces HTTP/2, los contextos TLS, los canales DNS, las instancias de WebAssembly, los monitores de archivos, los complementos nativos y los sockets abiertos como dependencias de alto riesgo para las instantáneas. - Encauza los módulos externalizados a través del puente de carga del entorno de ejecución durante la restauración. - Mantén una única lista predeterminada y documentada de los módulos que deben seguir siendo diferidos o externos. - Amplía esa lista mediante la configuración compatible del repositorio, en lugar de parchear los resultados generados. - Distingue la creación directa de estado nativo del uso transitivo de la red: los módulos integrados externalizados de forma diferida pueden proteger ya las dependencias transitivas, mientras que un paquete que cree directamente estado nativo o de WebAssembly sigue necesitando un tratamiento explícito. - Añade una prueba de compilación de instantáneas cuando una dependencia del framework pueda acceder a la pila nativa o de red durante el arranque. ## Pon los tipos globales añadidos en un módulo de tipos dedicado Coloca las ampliaciones globales de todo un paquete en un módulo dedicado de tipos globales. Las ampliaciones compartidas que sirven a varios paquetes pertenecen a un paquete compartido de definiciones de tipos, no a un único consumidor. - Mantén los archivos de declaraciones como módulos mediante una importación, una importación solo de tipos o una exportación vacía. - Importa la ampliación compartida desde el punto de entrada del paquete que necesite esa superficie de tipos. - Evita las declaraciones ambientales que se vuelven globales únicamente porque un archivo carece de sintaxis de módulo. - Después de mover tipos compartidos, prueba tanto el paquete que los define como al menos un paquete que los consuma. - Documenta cualquier cambio en la superficie pública de tipos. ## Ejecuta las pruebas necesarias y revisa el diff final antes de informar Ejecuta primero las comprobaciones más específicas que demuestren el comportamiento modificado y amplía el alcance solo cuando lo exija el límite afectado. - Añade cobertura de regresión para los cambios en cargadores, ciclo de vida de la aplicación, agrupamiento, agentes, gestión de HTTP o comportamiento de procesos. - Ejecuta el formateo, el linting, la comprobación de tipos y las pruebas pertinentes mediante los scripts del repositorio. - Usa la convención de mensajes de commit del repositorio y mantén el ámbito exacto. - Explica la motivación, el comportamiento modificado, el riesgo y las evidencias de las pruebas en la descripción del cambio. - Revisa el diff final para detectar ediciones no relacionadas, ruido generado y cambios públicos sin documentar. - No afirmes que el trabajo ha sido satisfactorio hasta que el comando pertinente se haya completado correctamente. ## No subas secretos y detente antes de publicar fallos de seguridad Lee la política de seguridad del repositorio antes de trabajar en vulnerabilidades. Nunca incorpores al repositorio secretos, credenciales, endpoints privados ni configuraciones específicas de una máquina. - Mantén las versiones locales del entorno de ejecución y del gestor de paquetes alineadas con las declaraciones del repositorio. - Trata los archivos de bloqueo y la configuración del espacio de trabajo como entradas coordinadas; cámbialos solo para una actualización intencionada de dependencias o de la cadena de herramientas. - Usa marcadores de posición en los ejemplos y la documentación en lugar de credenciales reales o URL privadas. - Mantén los cambios sensibles para la seguridad en un ámbito reducido y añade cobertura de regresión para el límite protegido. - Detente antes de publicar detalles de vulnerabilidades o modificar sistemas externos protegidos, salvo que la tarea autorice explícitamente esa acción. ## Separa el código y otras fuentes, la wiki y las reglas para la IA Mantén tres capas de conocimiento distintas. Las fuentes sin procesar son evidencias autorizadas, la wiki almacena síntesis duraderas y las directrices raíz para agentes definen las reglas compartidas del flujo de trabajo. - Trata el código, la documentación dirigida a usuarios, los archivos raíz del proyecto, los artefactos externos explícitos y el material sin procesar importado como evidencias de fuente. - Empieza por los resúmenes de la wiki para orientarte, pero contrástalos con las fuentes sin procesar cuando importen los detalles, los conflictos o la vigencia. - No reescribas las fuentes sin procesar a menos que la tarea lo exija. - Guarda en la base de conocimientos del repositorio las evidencias externas que se usen repetidamente. - Registra los conflictos en lugar de aplanarlos hasta crear un falso consenso. - Mantén concisos los archivos de agente específicos de cada herramienta y haz que apunten al esquema compartido. ## Dale a cada página de la wiki un solo tema y sus archivos de origen Asigna a cada página de conocimiento sustancial un único tema claro y un tipo de página declarado, como paquete, concepto, flujo de trabajo, decisión o fuente. - Usa nombres de archivo en minúsculas y separados por guiones. - Incluye metadatos iniciales con un título legible, el tipo de página, un resumen de una línea, las principales rutas de origen, la fecha local del calendario y el estado de vigencia. - Enumera las afirmaciones no triviales junto con archivos fuente trazables. - Etiqueta como inferencia las síntesis que no sean evidentes. - Marca las afirmaciones obsoletas o no resueltas cuando su vigencia sea incierta. - Mantén el índice de la wiki conciso y organizado por categorías. - Usa un registro de solo adición para las incorporaciones sustanciales, los hallazgos duraderos, las refactorizaciones importantes y los cambios que alteren lo comprendido y registrado. - No registres ediciones triviales que solo corrijan erratas. ## Lee el índice de la wiki antes de añadir fuentes o responder preguntas Usa un flujo de trabajo predecible al incorporar fuentes, responder preguntas sobre el repositorio o comprobar la base de conocimientos con un linter. - Para incorporar material, lee el índice, busca páginas existentes que deban absorberlo, crea o actualiza una página de fuente cuando corresponda, actualiza las páginas afectadas, renueva el índice y añade una entrada al registro para los cambios sustanciales. - Para las consultas, lee primero el índice y las páginas pertinentes de la wiki, verifica la información con las fuentes sin procesar, incorpora los nuevos hallazgos duraderos y registra los cambios sustanciales del conocimiento. - Para el linting, comprueba si hay páginas huérfanas, afirmaciones obsoletas, conceptos duplicados, referencias de fuentes ausentes, áreas de uso frecuente sin páginas y contradicciones. - Prefiere reestructurar las páginas solapadas a alargarlas indefinidamente. - Prioriza la cobertura duradera de paquetes fundamentales, integraciones, herramientas, comportamiento del ciclo de vida, carga, pruebas, trabajo de publicación y mantenimiento de la documentación. ## Actualiza la wiki solo cuando cambien las API o los flujos de trabajo Actualiza la base de conocimientos cuando el trabajo modifique de forma sustancial las API públicas, la estructura de la documentación, las responsabilidades de los paquetes, la arquitectura, los flujos de trabajo recurrentes de los colaboradores, las expectativas de pruebas o los procedimientos de publicación. - Evita cambios innecesarios en la wiki por una modificación exclusiva del código que no altere la comprensión duradera. - Actualiza las directrices para colaboradores en el mismo cambio cuando una nueva regla pase a ser aplicable de forma general. - Mantén las rutas de origen y las fechas de vigencia sincronizadas con los hechos que sustentan. - Añade una entrada al registro solo cuando el cambio de conocimiento sea lo bastante sustancial como para ayudar en trabajos futuros. - Verifica la documentación final con el comportamiento implementado antes de informar de la finalización.