Haz que un agente de codificación de IA entregue código sin advertencias e informes honestos en un repositorio de compilación estricta

## Compila solo el módulo cambiado mientras iteras y valida todo antes del push Usa el wrapper de compilación incluido en el repositorio en lugar de una cadena de herramientas instalada globalmente, para que cada colaborador y cada agente compilen de forma idéntica. Para iterar rápido, compila y prueba solo el módulo que modificaste en lugar de toda la compilación multi-módulo; normalmente existe un perfil "rápido" que omite las comprobaciones de análisis estático y una opción que omite las pruebas. Estos atajos son solo para ciclos de trabajo locales. Antes de confirmar (commit) debes ejecutar una compilación completa del módulo afectado con las comprobaciones activadas y confirmar que no hay ninguna advertencia; nunca confirmes cambios basándote en una compilación con comprobaciones omitidas. Antes de hacer push, ejecuta el paso de validación del proyecto, que es consciente de los cambios (diff-aware): clasifica el cambio (solo documentación, un único módulo, o cambio en la raíz/configuración) y compila únicamente los módulos afectados junto con el cierre de sus dependencias, mientras que un cambio en la configuración de compilación raíz obliga a una compilación completa. La validación deja un marcador de corta duración que el hook de push comprueba. Cancela las ejecuciones de pipeline superadas en tu rama antes de hacer push para no desperdiciar los runners compartidos. ## No te saltes los hooks de Git y escribe mensajes de commit cortos sin firma de IA Activa la ruta de hooks del repositorio al inicio de cada sesión de trabajo; las sesiones pueden archivarse y reanudarse, así que esto no es una configuración de una sola vez. Nunca omitas los hooks: ni la opción que salta la verificación ni el bypass de firma. Los hooks exigen los encabezados de licencia, la ausencia de importaciones no usadas o duplicadas, y el formato del mensaje de commit. Escribe los asuntos de los commits en el formato convencional tipo(ámbito): descripción, usando tipos como feat, fix, docs, refactor, test y chore. Limita cada mensaje a un máximo de dos líneas no vacías, con la primera línea por debajo de unos 100 caracteres. No añadas líneas finales de ningún tipo: ni trailer de coautor, ni trailer de sign-off y, sobre todo, ninguna firma de autoría o generación por IA; el hook del mensaje de commit las rechaza. Las correcciones de errores van directas a la rama principal de desarrollo; las funciones nuevas usan ramas de funcionalidad. ## Sigue el estilo del código cercano y trata cada advertencia como un error Ajusta el estilo al del código circundante y realiza el cambio más pequeño y razonable para lograr el resultado. Todo archivo fuente debe llevar el encabezado de licencia requerido. Prefiere la composición sobre la herencia; usa una construcción try-with-resources para cada recurso cerrable; devuelve un wrapper opcional en lugar de null desde las API públicas; usa la inferencia de tipo local solo cuando el tipo sea evidente por el contexto; prefiere las expresiones switch y el pattern matching sobre cadenas largas de if/else; usa tipos sellados (sealed) y portadores de registro inmutables (records) donde encajen; parametriza siempre los genéricos; anota los métodos que sobrescriben; construye cadenas con un builder dentro de los bucles; y construye colecciones inmodificables con los helpers de fábrica estándar. Trata toda advertencia del compilador, de obsolescencia (deprecation) y de análisis estático como un error. La compilación se ejecuta con todas las comprobaciones de lint activadas y falla ante importaciones no usadas o duplicadas, así que se exigen cero advertencias para poder publicar. No introduzcas nuevas anotaciones de supresión de advertencias sin un comentario que justifique por qué es inevitable, y nunca borres un comentario del código a menos que puedas demostrar que es activamente falso. ## Que solo quien crea un recurso lo cierre, y nunca ignores los límites de capacidad Los siguientes invariantes bloquean el lanzamiento sin importar el alcance de la función; incumplir uno de ellos bloquea el lanzamiento sin importar cuán pequeño sea el cambio. **Propiedad (ownership)** — Solo el creador de un recurso puede liberarlo, cerrarlo o apagarlo. Registra la propiedad de forma explícita, y cuando aceptes un executor, pool o conexión suministrado externamente, envuélvelo para que las llamadas de ciclo de vida no puedan destruir algo que no creaste. Toda rutina de inicio necesita una rutina de parada simétrica que deshaga cada registro —listeners, handlers, hooks— y todo buffer debe liberarse en todas las rutas terminales y de error. **Completitud de las rutas terminales** — Toda ruta de salida (éxito, fallo, cancelación, tiempo de espera, rechazo) debe dejar el sistema en un estado completado: resolver los futures, restablecer las banderas (flags), liberar los buffers. Haz que el cierre sea idempotente con un patrón de compare-and-set o de cierre único (close-once). Si una guarda comprueba un contador, alguna ruta debe realmente incrementar ese contador. **Contrapresión (backpressure)** — Nunca ignores las señales de rechazo o de capacidad. Comprueba el valor de retorno de un offer acotado, gestiona la ejecución rechazada y gestiona las escrituras parciales. Toda caché y todo buffer necesitan un límite de tamaño o una política de expulsión (eviction); una estructura sin límite alimentada por entrada externa es un vector de denegación de servicio. ## Valida la entrada en cada límite e informa solo de lo que realmente está en ejecución Estos invariantes también bloquean el lanzamiento sin importar el alcance de la función. **Seguridad en los límites (boundary safety)** — En cada límite (red, sistema de archivos, shell, URL, HTTP) valida y codifica antes de interpretar. Decodifica texto solo a partir de mensajes completos y delimitados (framed), nunca a partir de fragmentos de transporte en bruto. Normaliza y valida las rutas del sistema de archivos: resuelve, normaliza y luego confirma que el resultado permanece dentro de la raíz prevista, rechazando segmentos de directorio padre, separadores y segmentos vacíos. Usa arrays de argumentos para las llamadas al shell, codifica en URL las partes dinámicas de ruta y consulta, compara los tipos de contenido sin distinguir mayúsculas y minúsculas, y devuelve un error de cliente en lugar de un error de servidor ante una entrada malformada, capturando los fallos de parseo en el límite. **Verdad en tiempo de ejecución (runtime truth)** — Anuncia e informa únicamente el estado confirmado en tiempo de ejecución, nunca la intención de configuración ni la mera presencia en el classpath. Las banderas de capacidad y los endpoints de descubrimiento deben reflejar lo que realmente está en ejecución, y el anuncio de una función debe suprimirse cuando falla el arranque. **Seguridad** — Toda superficie que modifique estado o de administración requiere autenticación y autorización explícitas, con denegación por defecto. La verificación de integridad debe fallar de forma cerrada (fail closed); cualquier modo de fallo abierto (fail-open) debe ser explícito y no ser el predeterminado. Nunca publiques valores por defecto inseguros en rutas de producción —protégelos detrás de una activación explícita (opt-in) con una advertencia de arranque— y los ejemplos no deben retroceder en esta postura. **Paridad de modos** — Si una función existe en varios modos de invocación (síncrono, asíncrono, streaming), la semántica debe coincidir: el manejo de errores, los eventos de ciclo de vida, la observabilidad y el comportamiento de finalización. Documenta y prueba cualquier diferencia intencional, y cuando añadas una función a una ruta, verifícala en todas las rutas. ## Añade una prueba de regresión a cada error grave y prohíbe las pruebas vacías Toda corrección de un error de alta severidad debe publicarse junto con una prueba de regresión que reproduzca el escenario que fallaba. No se permiten pruebas de relleno (placeholder) ni pruebas que no hacen nada (no-op) en los carriles de CI obligatorios: está prohibida una prueba que se limite a afirmar una verdad trivial, y cada prueba debe verificar el comportamiento específico que dice comprobar. Las pruebas end-to-end deben verificar la función bajo prueba, no simplemente que un servidor se inició. Si debes poner en cuarentena una prueba inestable (flaky), necesita un responsable, una fecha de caducidad y un issue de seguimiento, y aun así debe seguir ejecutándose en un carril programado. Los filtros de ruta del workflow deben incluir todo script y ubicación de configuración que afecte al comportamiento del área que se está modificando, o CI omitirá silenciosamente justo el código que se modificó. ## Haz que los ejemplos llamen a la API real en lugar de simularla Las aplicaciones de muestra y de ejemplo son lo primero que ven los usuarios, así que deben tener calidad de producción, no ser stubs. Usa de verdad la integración que afirmas demostrar: si un ejemplo lleva el nombre de una capacidad real, debe llamar a esa API real, no simularla con un sustituto en memoria. Si no logras que la integración real funcione, dilo y pide ayuda en lugar de publicar un mock disfrazado; comentarios como "en una app real llamarías a esto" son una señal de alarma de que el ejemplo no es la app real. Antes de escribir código de integración contra una biblioteca de terceros, lee su API real —inspecciona los artefactos de la dependencia y lee las firmas públicas— y nunca inventes llamadas a métodos. Prefiere la autoconfiguración que ofrece la biblioteca antes que el cableado manual. Todo ejemplo debe compilar y publicarse con un README breve que explique qué hace, cómo ejecutarlo y qué muestra el código clave. No crees un ejemplo por cada variante de backend cuando el sentido de la abstracción es precisamente tener una única dependencia intercambiable. ## Comprueba cada afirmación con el código o el historial de Git antes de escribirla Toda afirmación factual en la documentación, las entradas del changelog, los mensajes de commit y los textos de cara al usuario debe corresponder a algo que exista realmente en el código o en el historial de git. No inventes funciones, nombres de métodos, conjuntos de capacidades, cifras de métricas ni commits de corrección; cada invención cuesta credibilidad y hay que rastrearla y revertirla. Las afirmaciones numéricas requieren una fuente: verifica un recuento contra el código real antes de escribirlo. Las viñetas "fixed" y "added" del changelog deben corresponder a commits reales: busca el cambio en el log y conserva el hash del commit en tu borrador antes de publicarlo; si no encuentras el commit, la corrección no ocurrió. Las afirmaciones sobre la superficie de la API requieren leer primero el código fuente real (listas de campos, nombres de métodos). Una afirmación de que algo está publicado, conectado o integrado requiere un consumidor real en producción, en una ruta alcanzada desde una acción del usuario, y no simplemente una interfaz de proveedor de servicio o una implementación de referencia. Cuando un hecho no se pueda verificar, elimínalo o márcalo explícitamente como no verificado y pregunta antes de publicarlo. Si te sorprendes inventando algo, detente, no confirmes el cambio (commit), informa la afirmación falsa contrastándola con la realidad, y corrige cada copia de ella. ## No uses los choques entre reglas como excusa ni declares la tarea terminada a medias Más allá de la honestidad factual, evita la deshonestidad de comportamiento: formulaciones en las que cada afirmación por separado es defendible pero el conjunto induce a error. No fabriques un conflicto entre dos reglas para justificar el camino más fácil; cuando las reglas parecen entrar en conflicto, casi siempre prevalece la que exige el trabajo más difícil y más seguro. No elijas selectivamente qué directriz citar mientras existe otra que la contradice; concílialas abiertamente. No reportes un estado que las reglas dicen que hay que corregir en silencio: si un pipeline compartido está roto, arréglalo e informa del éxito en lugar de narrar la avería. "Ya estaba roto" o "no es mi regresión" es una descripción, no una excusa: la responsabilidad sobre las ramas compartidas se transfiere con cada cambio. No pidas permiso para una acción que las reglas ya exigen: actuar vale más que preguntar, así que simplemente haz el trabajo exigido y sigue avanzando en los asuntos pendientes hasta que te redirijan. No declares la victoria a mitad de la tarea; la señal honesta enumera lo que aún falta junto con lo que ya está hecho. Cuando la brevedad entra en conflicto con una regla de corrección o de seguridad, gana la regla de seguridad: es mejor ser detallado pero correcto que conciso pero inseguro. Cuando detectes uno de estos patrones, nómbralo, haz el trabajo que la regla realmente exigía, y recuerda que la disculpa no es el trabajo. ## Guarda decisiones y planes en la base de conocimiento compartida, no solo en el chat Trata una base de conocimiento compartida como el hogar duradero de los resultados estructurados, porque el chat no es duradero. Léela primero para conocer decisiones previas, diseños y contexto antes de comenzar un trabajo estructurado, y escribe en ella los resultados duraderos en lugar de dejarlos solo en una conversación. Enruta según el tipo de documento: las decisiones de arquitectura y los registros de diseño, los planes por fases, los runbooks y los procedimientos de guardia (on-call), y las auditorías, análisis y traspasos (handoffs) tienen cada uno un destino designado; la documentación de referencia se publica junto con el código en vivo, y las especificaciones limitadas a un directorio viven en el README de ese directorio. Mantén fuera de todo artefacto confirmado (commit) los identificadores privados o de uso exclusivamente local: alias personales, nombres de rol (role-play), rutas específicas de una máquina. Usa nombres de marcador de posición neutros en las pruebas y en las muestras, y un identificador real únicamente donde de verdad se refiera a una cuenta pública. Cuando el almacén duradero no esté disponible, recurre a un enlace compartible y regístralo para que una sesión posterior pueda archivarlo en el lugar correcto.