Haz que la IA lea antes de editar un repositorio grande y publique solo con revisión

## Lee primero las reglas generales y luego la guía de la carpeta donde trabajas Limita el documento raíz a políticas estrictas y enrutamiento; deja que las guías específicas gestionen el flujo de trabajo detallado de cada área. Antes de trabajar dentro de un subárbol, lee la guía que lo gobierna. ### Un solo lugar para cada tipo de regla Las políticas estrictas, los límites transversales y qué guía gobierna qué residen en la raíz. Los procedimientos específicos de cada tarea residen en la guía específica junto al código que gobiernan. No repitas un flujo de trabajo en dos lugares donde las copias puedan divergir. ### Referencia el código como lo hace el repositorio Cita los archivos por su ruta relativa al repositorio, no por una ruta absoluta o del directorio personal, para que una referencia signifique lo mismo para cualquier lector. ## Busca una biblioteca o herramienta existente antes de crear la tuya Antes de proponer o construir un sistema, función, herramienta, integración o automatización personalizada, haz una verificación rápida para ver si ya existe una biblioteca, complemento o plataforma gratuita que lo resuelva razonablemente bien. ### Prefiere la opción probada Cuando una opción existente sea adecuada, úsala. Construye algo personalizado solo cuando las alternativas no sean adecuadas, sean demasiado costosas, estén sin mantenimiento, sean inseguras, incumplan normas, o el usuario haya pedido explícitamente una construcción personalizada. ### Mantén la verificación económica Esto es un filtro previo breve, no una tarea de investigación. No recomiendes un servicio de pago a menos que el usuario haya aprobado el gasto. ## Revisa leyendo quién llama, a quién se llama y las pruebas, no solo el diff Las correcciones, la clasificación de problemas y las revisiones necesitan alta confianza respaldada por la lectura, no una suposición basada en el cambio visible. Una revisión que solo mira el diff es insuficiente. ### Lee toda la superficie antes de emitir un veredicto Antes de decir que algo está bien, mal, es la mejor solución o hay suficiente prueba, lee toda la función o módulo modificado, junto con quienes lo llaman, lo que llama, implementaciones hermanas, pruebas adyacentes, documentación específica y los contratos de todo aquello de lo que depende. ### Construye un pequeño mapa de evidencia Nombra la superficie modificada, su punto de entrada, el límite del propietario, al menos un llamador y un llamado, superficies hermanas que comparten el invariante, las pruebas existentes y el comportamiento actualmente en producción. Si falta algún elemento, señala el vacío en lugar de sacar una conclusión. ### Si te cuestionan, lee antes de defender Cuando se cuestione un veredicto, revisa primero la ruta que falta; no defiendas la conclusión anterior hasta haberla examinado. ## Lee el código fuente de las dependencias y prueba las API externas en vivo Cuando el comportamiento depende de una biblioteca o un servicio externo, verifícalo contra la fuente real, no contra la memoria, un envoltorio, un esquema generado o el informe de otro agente. ### Lee el código fuente propio de la dependencia Para el comportamiento respaldado por una dependencia, lee directamente el código fuente, la documentación o los tipos de la fuente original, y cita lo que verificaste. La mayoría de las dependencias son de código abierto, así que no hay excusa para adivinar un valor por defecto, un error o un tiempo de ejecución. ### Prueba en vivo los servicios externos El trabajo con APIs externas necesita una prueba en vivo más una evidencia citada y actual; no hagas afirmaciones sobre una API basándote en la memoria. Verifica en vivo siempre que sea posible, y nunca imprimas un secreto en el proceso. ## Decide si un arreglo es el mejor, no solo uno que funciona El veredicto de una revisión debe determinar si el cambio es la mejor solución, no simplemente una que funcione. Compara los límites del propietario, los llamadores, las superficies hermanas, las pruebas y el comportamiento actual antes de concluir. ### Las soluciones parciales necesitan pruebas de las superficies hermanas Una solución que toca una superficie pero no sus hermanas necesita pruebas de que estas no se ven afectadas, o un seguimiento explícito que las cubra. ### No registres una preferencia de estilo como un hallazgo No plantees un hallazgo por una simple preferencia de política del repositorio cuando el código modificado sigue su guía específica y no muestra riesgo visible para el usuario, en tiempo de ejecución, de seguridad o para quien mantiene el proyecto. ## Lee la configuración de una sola forma y migra las claves antiguas sin perderlas En tiempo de ejecución solo se lee la forma canónica actual de la configuración y los datos. No existe compatibilidad silenciosa para claves antiguas o malformadas. ### Elimina la ruta antigua Prefiere una única ruta canónica y elimina la antigua, a menos que se cite un contrato ya publicado explícitamente o una ruta de actualización etiquetada. Una refactorización que deja una segunda ruta probablemente ha fallado. ### Migra, nunca elimines en silencio Si un cambio invalida la configuración existente, añade una migración correspondiente en el paso dedicado de migración o reparación; nunca elimines una clave en silencio, porque una clave eliminada es un cambio de comportamiento oculto. ### Mantén pequeña la superficie de configuración La superficie de configuración y de entorno tiene un umbral alto. Antes de añadir una opción, demuestra que el comportamiento existente no puede resolverlo, y prefiere eliminar o consolidar opciones. Trata los flujos de configuración documentados como sensibles a la compatibilidad: prefiere banderas aditivas antes que romper fragmentos existentes. ## Deja el código propio de un módulo en ese módulo, no en el código compartido El código compartido y central debe permanecer genérico; el comportamiento específico de un propietario reside en el módulo que lo posee. Cruza un límite solo a través de una interfaz pública documentada, nunca accediendo directamente a los detalles internos de otro módulo. ### Traslada la responsabilidad, no la envuelvas La forma predeterminada de una solución es una refactorización limpia y acotada que traslada la lógica a su propietario correcto y elimina abstracciones obsoletas, políticas duplicadas y ramas muertas, no el parche más pequeño posible. ### Correcto, pero sin sobreingeniería La corrección ante entradas y estados reales es obligatoria; las capas y protecciones adicionales para entradas imaginarias son defectos, no rigor. Cuando sacrifiques un caso extremo improbable a cambio de simplicidad real, nombra esa decisión explícitamente para que sea una elección y no un descuido. ## Guarda el estado en el almacén del proyecto, no en archivos sueltos Mantén el estado en tiempo de ejecución en el almacén canónico del proyecto. No dispersues archivos secundarios para estado, cachés, colas, índices o datos temporales que deberían pertenecer al almacén. ### Las migraciones son responsables de la forma antigua Los almacenes de archivos heredados y las formas retiradas se normalizan solo en el código de migración o reparación antes del tiempo de ejecución; el tiempo de ejecución en estado estable nunca lee una ubicación de respaldo. ### Nunca incrementes la versión del esquema por tu cuenta Un cambio de versión de esquema que los lectores antiguos no puedan tolerar requiere primero una discusión explícita con el usuario y su aceptación; nunca lo avances de forma autónoma. Un cambio puramente aditivo que las versiones anteriores aún toleran no requiere incrementar la versión. ## Reutiliza datos ya resueltos en vez de buscarlos en cada petición Una ruta crítica debe transportar los datos que ya se resolvieron antes, en lugar de volver a descubrirlos en cada solicitud. ### Resuelve una vez, reutiliza Pasa hacia adelante identificadores, rutas resueltas y datos de capacidades, y reutiliza el objeto ya preparado. No soluciones el descubrimiento repetido en tiempo de solicitud dispersando cachés; mueve el dato canónico a una etapa anterior y elimina las búsquedas duplicadas. ### Sin verificaciones de vigencia dentro del bucle Los metadatos estables durante el proceso, como instalaciones, manifiestos y rutas resueltas, solo cambian al reiniciar o mediante una recarga explícita, así que las rutas críticas no deben volver a verificar su vigencia releyendo o recalculando hashes. Una caché local del proceso es aceptable solo cuando pertenece a un ciclo de vida definido y tiene límites claros. ## Escribe código breve, legible y con tipos estrictos Mantén activada la verificación estricta de tipos y conserva la honestidad del código. El objetivo es un código pequeño y claro, no el diff más pequeño posible. ### Tipa los límites, cierra las ramas Evita el tipo dinámico genérico que lo atrapa todo; prefiere tipos reales y adaptadores acotados. Valida la entrada externa con un esquema. Ramifica según uniones discriminadas o códigos de resultado cerrados, en lugar de cadenas de texto libres o valores centinela, y haz que los estados imposibles no puedan representarse. ### Estructura pensando en la lectura Prefiere los retornos anticipados frente a pirámides anidadas, y divide el trabajo en recopilar, normalizar, decidir y actuar. Mantén los puntos de llamada sencillos: las decisiones complejas ocurren antes, así que los argumentos siguen siendo nombres, literales o lecturas simples. ### Comenta lo que no es obvio Un comentario en línea se justifica cuando explica un invariante no evidente, una restricción de orden, un límite de propiedad o un acoplamiento de limpieza: de una a tres líneas que expliquen por qué existe la rama y qué se rompe si se elimina. Nada de narrar la sintaxis. ## Si una refactorización alarga el código, recórtalo o explica por qué Una refactorización debería eliminar aproximadamente la misma complejidad local que añade. Un aumento neto de líneas en producción es una señal que debe justificarse, no algo que se acepta por defecto. ### Revisa el tamaño antes de cerrar Antes de terminar una refactorización no trivial, compara el tamaño del cambio; si el código que no es de pruebas creció, recórtalo o explica claramente por qué menos rutas ahora cuestan más líneas. ### Haz que cada nueva superficie se justifique Un nuevo ayudante o archivo debe reducir de inmediato las rutas de llamada, los conceptos o la lógica repetida. No añadas uno para compatibilidad puntual, renombrar campos o resiliencia especulativa. Mantén las interfaces públicas acotadas y devuelve la forma útil más pequeña posible. ## Prueba el comportamiento y no los textos, y aísla cada prueba Las pruebas demuestran el comportamiento y protegen contra regresiones; no son una casilla que marcar por cada rama interna. ### Prueba el comportamiento, no el texto Prefiere las pruebas de comportamiento antes que buscar cadenas de documentación o de política. Coloca los recordatorios para el operador en la documentación, no en las aserciones de las pruebas. Revisa las pruebas nuevas antes de integrarlas y elimina las de poco valor, incluidas las de rutas que acabas de eliminar. ### Mantén las pruebas aisladas y honestas Limpia temporizadores, entorno, variables globales, simulaciones y estado temporal. Una simulación debe exportar cada vínculo que el código real utiliza, incluidos los tipos de error usados en comprobaciones de identidad. No edites un archivo de referencia o de instantánea para silenciar una comprobación sin aprobación. ### Prueba sobre una copia del estado real Cuando los datos realistas importan, copia el estado a una ubicación temporal y prueba sobre la copia; nunca modifiques directamente el estado de un servicio en producción sin aprobación explícita. ## Nunca ejecutes código no confiable en local y envía las compilaciones pesadas a un ejecutor remoto Clasifica la confianza de la fuente antes de decidir cuánto validar, y elige dónde se ejecuta esa validación según esa misma confianza. ### Nunca ejecutes código no confiable localmente El código de fuente confiable puede ejecutar localmente algunas pruebas puntuales y verificaciones estáticas económicas cuando las dependencias están listas. El código no confiable o aportado externamente no ejecuta localmente ninguno de sus propios scripts, pruebas, hooks o configuración, sin importar el tamaño de la validación; usa en su lugar una ejecución aislada y sin credenciales. ### Envía el trabajo pesado a un ejecutor remoto Las suites completas, las compilaciones, las verificaciones de tipos, el empaquetado y la validación multiplataforma se ejecutan en un ejecutor remoto, que se obtiene de forma diferida en el primer comando pesado, se reutiliza durante una sesión y se libera antes de entregar el trabajo. Si el ejecutor remoto no está disponible, el trabajo confiable puede recurrir a lo local; el trabajo no confiable nunca lo hace. ### Condiciona la integración a una revisión reciente Antes de integrar, ejecuta una revisión automatizada reciente hasta que no queden hallazgos accionables; no integres basándote solo en una integración continua en verde, salvo que el alcance sea trivial o el usuario decida omitirlo. Si la validación está bloqueada, indica exactamente qué falta y por qué. ## Abre issues y pull requests según el proceso del proyecto y pide aprobación antes de publicar Cambiar una superficie compartida es un acto social: sigue el proceso de contribución del proyecto y obtén aprobación para cada paso irreversible. ### Sigue el proceso de revisión y fusión Lee la guía de contribución, las plantillas de incidencias y de solicitudes de cambio, y el archivo de propietarios de código antes de abrir nada. Abre primero una incidencia para errores, funciones visibles para el usuario y decisiones de arquitectura. Escribe una descripción real de la solicitud de cambio con el problema, el impacto y la evidencia, y verifica el estado en vivo mediante la propia herramienta de la plataforma antes de cualquier modificación. ### No hagas nada irreversible sin que te lo pidan No etiquetes, renombres, rebases ni integres sin que te lo pidan. Muestra primero un comentario público como borrador, a menos que el usuario te haya pedido explícitamente publicarlo, y nombra cada comentario publicado con su enlace. Termina el trabajo de incidencias y solicitudes de cambio con la URL completa del elemento. ### Confirma cambios y ramifica con orden Confirma solo los archivos previstos con mensajes concisos y agrupados, rebasa sobre la rama principal más reciente antes de subir los cambios, y nunca elimines ni renombres archivos inesperados. Mantén la documentación alineada con el comportamiento dentro del mismo cambio, y deja el registro de cambios del lanzamiento al proceso de publicación. ### Obtén aprobación para lanzamientos y secretos Los lanzamientos, los incrementos de versión y los cambios de dependencias o de archivos de bloqueo necesitan aprobación explícita. Nunca confirmes credenciales reales ni configuración en producción, y guarda los secretos en el almacén designado.