heredar-estilo-legado

Heredar Estilo Legado

Previene la deriva de estilo de código de IA en proyectos legacy escaneando el código base en busca de convenciones implícitas en 4 dimensiones meta-arquitectónicas, resolviendo conflictos con el usuario uno a la vez, y cristalizando el consenso en un archivo .ai-style-rules.md ejecutable. Totalmente agnóstico en cuanto a lenguaje y framework.

Cuándo Activar

• El usuario escribe /heredar-estilo-legado
• El usuario menciona incorporar IA a un proyecto legacy escrito a mano
• El usuario está preocupado porque el código generado por IA "derive" de las convenciones existentes del proyecto
• El usuario quiere extraer y codificar las reglas de codificación implícitas de su proyecto

Cuándo Usar

Usa esta habilidad cuando necesites preservar el estilo de un proyecto legacy y prevenir la deriva de estilo generada por IA. Consulta Cuándo Activar más arriba para las condiciones de activación.

Prerrequisitos

• Git (recomendado; los proyectos sin Git recurren a marcas de tiempo de archivos para el modo incremental)
• Acceso de lectura/escritura a la raíz del proyecto (genera .ai-style-rules.md y opcionalmente CLAUDE.md)

Flujo de Trabajo

Paso 0 — Modo de Detección Automática

Verificar silenciosamente la existencia de .ai-style-rules.md en la raíz del proyecto:

¿Existe el archivo?	Modo
No	Rama A — Escaneo Completo por Primera Vez
Sí	Rama B — Sniffing Incremental

Anuncia el modo en una línea y continúa — nunca pidas al usuario que elija.

Rama A — Escaneo Completo por Primera Vez

1. Medir la escala, elegir un nivel de escaneo

git ls-files | grep -cE '\.(js|ts|jsx|tsx|vue|py|go|rs|java|kt|rb|php|cs|swift|c|cpp|h)$'

Nivel	Archivos fuente	Estrategia
Pequeño	≲ 50	Lectura completa de cada archivo fuente
Mediano	50–500	Capa de infraestructura = lectura completa; capa de negocio = muestrear 2–3 por dimensión
Grande	≳ 500	Muestreo estricto + límite de presupuesto; resumen --stat primero, luego lecturas dirigidas

2. Escanear en 4 dimensiones

1. Anatomía de Archivos — orden de declaraciones dentro del archivo (imports → tipos → lógica principal → helpers → export)
2. Estado y Flujo de Control — convenciones de nomenclatura para estado asíncrono, paginación, banderas
3. Infraestructura — dónde viven los utilitarios transversales (interceptores, formateadores, middleware)
4. Manejo de Errores — try/catch vs interceptor global vs retorno Result; hábitos de verificación de nulos

3. Aplicar reducción de ruido por umbral de señal

Antes de interrumpir al usuario, evaluar la fuerza de la señal:

• Señal débil → suprimir automáticamente: minoría <5% Y count <10 → la mayoría gana, la minoría va a los NO HACER
• Señal fuerte → interrogar: división casi pareja, o bifurcación semántica en una dimensión central
• Excepción de proyecto pequeño: fuentes ≲50, "3 vs 2" NO es una mayoría → interrogarlo

4. Resolver conflictos uno a la vez (Protocolo de Interrogación)

Para cada conflicto de señal fuerte, presentar EXACTAMENTE UNA pregunta con 4 opciones:

Evidencia: pathA usa estilo X, pathB usa estilo Y ADVERTENCIA: Riesgo: mezclar ambos fractura el estilo del proyecto Elige: 1 seguir X 2 seguir Y 3 esto es evolución, actualizar reglas 4 Tengo una nueva regla

Suspender hasta que el usuario responda, luego proceder al siguiente conflicto. Nunca apilar preguntas.

5. Generar .ai-style-rules.md con tres secciones obligatorias:

• [Archivos Dorados] — rutas de ejemplares reales anotadas con lo que demuestran
• [Reglas de Nomenclatura y Control de Estado] — convenciones concretas y verificables
• [NO HACER] — anti-patrones que no deben propagarse

6. Instalar el gancho persistente

Preguntar al usuario por la fuerza de aplicación (usar AskUserQuestion):

Opción	Mecanismo
1 Gancho suave (recomendado)	Escribir referencia @.ai-style-rules.md en el CLAUDE.md del proyecto
2 Gancho duro	Gancho suave + Gancho `PreToolUse[Write
3 Sin gancho	Mantener el archivo de reglas; el usuario lo referencia manualmente

Rama B — Sniffing Incremental

1. Leer el .ai-style-rules.md existente; si tiene una huella de commit, git diff <último_hash> HEAD --stat para identificar el delta
2. Leer cambios recientes de Git (git log -3 --stat → inspeccionar archivos sospechosos bajo demanda)
3. Para diffs sobredimensionados (>cientos de archivos): solo resumen --stat + muestrear los cambios más grandes
4. Comparar el código nuevo contra las reglas registradas → los conflictos pasan por el Protocolo de Interrogación
5. Agregar registro de evolución al final de .ai-style-rules.md (nunca sobrescribir reglas antiguas)

Aplicación por Turno

Cuando .ai-style-rules.md está en contexto (cargado a través de CLAUDE.md), cada tarea de escritura de código debe comenzar con una declaración de cumplimiento en la cadena de razonamiento, nombrando el ejemplar que se sigue y los NO HACER que se evitan.

Cómo Funciona

Esta habilidad detecta automáticamente si es una ejecución por primera vez o incremental mediante la presencia de .ai-style-rules.md:

• Primera vez (Rama A) — Mide la escala del proyecto, escanea el código base en 4 dimensiones meta-arquitectónicas (Anatomía de Archivos, Estado y Flujo de Control, Infraestructura, Manejo de Errores), aplica reducción de ruido por umbral de señal para suprimir conflictos débiles, resuelve conflictos de señal fuerte uno a la vez con el usuario, genera .ai-style-rules.md con Archivos Dorados / Reglas de Nomenclatura / NO HACER, y ofrece ganchos de aplicación opcionales.
• Incremental (Rama B) — Lee las reglas existentes, verifica los diffs recientes de Git en busca de patrones nuevos o conflictivos, ejecuta el mismo protocolo de interrogación uno a la vez para cualquier conflicto encontrado, y agrega registros de evolución sin sobrescribir las reglas existentes.
• Aplicación por Turno — Cuando está enganchado a través de CLAUDE.md, cada tarea de escritura de código comienza con una declaración de cumplimiento que nombra el ejemplar seguido y los NO HACER evitados.

Especificación de Salida

• .ai-style-rules.md en la raíz del proyecto (con huella de commit + nivel de escala en el encabezado)
• Opcionalmente CLAUDE.md con una referencia @.ai-style-rules.md
• Registros de evolución añadidos como entradas ### [AAAA-MM-DD] Registro de Evolución de Estilo

Anti-Patrones

• FALLO: NO omitir el paso de medición de escala — muestrear un proyecto de 30 archivos lo "desnutre"; escanear completamente un repositorio de 5,000 archivos lo revienta
• FALLO: NO apilar múltiples preguntas de conflicto a la vez — la interrogación es estrictamente uno a la vez
• FALLO: NO sobrescribir reglas antiguas en modo incremental — siempre añadir registros de evolución
• FALLO: NO predeterminar "gancho duro" sin preguntar — la fuerza de aplicación es decisión del usuario
• FALLO: NO juzgar la sintaxis o la calidad del stack tecnológico — esta habilidad alinea solo meta-arquitectura
• FALLO: NO copiar errores de los archivos ejemplares — reutilizar estructura, señalar defectos

Mejores Prácticas

• Anunciar el modo detectado (primera vez vs incremental) y el nivel de escala en una línea antes de escanear
• Para proyectos grandes, leer primero los resúmenes --stat, luego Read dirigido a archivos sospechosos
• Dejar que el umbral de señal maneje el ruido — una división de nomenclatura 843 vs 8 debe resolverse automáticamente sin interrupción del usuario
• Ante la duda sobre la fuerza de la señal, inclinarse por preguntar
• El gancho suave de CLAUDE.md (@.ai-style-rules.md) suele ser suficiente; gancho duro solo si el usuario quiere aplicación mecánica

Habilidades Relacionadas

• init — inicializar un nuevo CLAUDE.md con documentación del código base
• code-review — revisar diffs por corrección y problemas de estilo
• simplify — revisar código en busca de oportunidades de reutilización y simplificación

Ejemplos

1. Incorporación por primera vez

   • Usuario: "Ayúdame a incorporar IA a este código base antiguo sin cambiar su estilo."
   • Acción: Ejecutar Rama A escaneo completo → medir escala → escanear 4 dimensiones → interrogar conflictos → generar .ai-style-rules.md → ofrecer fuerza de gancho (suave/duro/ninguno).

2. Actualización incremental después de cambios en el equipo

   • Usuario: "Agregamos un nuevo módulo; mantén las reglas de estilo existentes intactas."
   • Acción: Ejecutar Rama B sniffing incremental → comparar deltas de Git con reglas registradas → interrogar cualquier nuevo conflicto → agregar registro de evolución sin sobrescribir.

3. Aplicar NO HACER a través de CLAUDE.md

   • Usuario: "Asegúrate de que todo el código nuevo se mantenga consistente con las reglas del proyecto."
   • Acción: Gancho suave instalado → .ai-style-rules.md se carga automáticamente cada sesión → cada tarea de escritura de código comienza con declaración de cumplimiento, reutilizando patrones ejemplares y evitando los NO HACER.