pragmatic-architecture-refactor

name	pragmatic-architecture-refactor
description	Guía estratégica para la migración incremental hacia una arquitectura limpia sin alterar su comportamiento externo. Requiere cargar activamente la skill `pragmatic-architecture-guidelines` para garantizar las buenas prácticas arquitectónicas durante la refactorización.

🗺️ Mapa de Flujo de Refactorización

CÓDIGO ACOPLADO             PASO A PASO                     HEXAGONAL PRAGMÁTICO
┌──────────────────┐        1. Extraer Lógica Pura         ┌──────────────────┐
│ Comando CLI      │ ─────> 2. Crear Interfaz (Puerto) ──> │ Dominio (Puro)   │
│  - Lee Disco     │        3. Mover I/O a Adaptador       ├──────────────────┤
│  - Cambia Datos  │                                       │ Puerto / Adapter │
│  - Guarda Disco  │                                       └──────────────────┘
└──────────────────┘

---

🔄 Pasos de Ejecución

Paso 1: Identificar y Aislar los "Efectos Secundarios"

Analiza el archivo o script heredado e identifica todas las líneas que interactúan con factores externos al proceso lógico.

• Puntos Críticos a Buscar:
  • Peticiones de red o llamadas de API (fetch, axios, SDKs de terceros).
  • Operaciones de sistemas de archivos (fs.readFileSync, fs.writeFileSync, path.join).
  • Lecturas globales de entorno (process.env).
  • Captura de inputs o salidas por consola (readline, prompts, console.log).

Paso 2: Asegurar con Tests de Caracterización (TDD Inverso)

• Acción: Antes de modificar o cortar una sola línea de código, escribe un test que ejecute el script actual con una entrada controlada y valide que produce la salida actual (incluso si la salida actual tiene un formato heredado o "sucio").
• Foco de Validación: [Cargar SKILL: pragmatic-architecture-guidelines -> Consultar REGLA 4 (Boy Scout)]. Esta prueba es tu seguro de vida. Garantiza que tienes una base estable para aplicar la Regla del Boy Scout y dejar el código mejor sin alterar su comportamiento externo.

Paso 3: Extraer la Lógica de Negocio (El Núcleo Puro)

Separa el procesamiento de datos de las operaciones de Entrada/Salida (I/O).

• Acción: Selecciona el bloque de código intermedio encargado de transformar, validar, filtrar o procesar los datos extraídos en el Paso 1.
• Refactor: Córtalo y muévelo a una función o clase pura dentro de un archivo independiente en src/domain/. Ejecuta inmediatamente el test del Paso 2 para comprobar que no has roto nada.
• Regla Estricta: Esta nueva función de dominio debe recibir parámetros con datos primitivos o estructurados limpios y retornar un resultado plano. No puede contener lógica asíncrona ligada a infraestructura ni promesas externas.
• Foco de Validación: [Cargar SKILL: pragmatic-architecture-guidelines -> Consultar REGLA 1: Capa de Dominio Pura]. Fuerza a que esta nueva pieza extraída sea limpia, síncrona, libre de dependencias y legible.

Paso 4: Crear el Puerto de Salida

Determina las necesidades de información que la lógica pura requiere del mundo exterior.

• Acción: Diseña una interfaz (interface) de TypeScript en src/ports/ que firme los métodos necesarios para proveer o persistir dichos datos estructurados de forma agnóstica a la tecnología.
• Foco de Validación: [Cargar SKILL: pragmatic-architecture-guidelines -> Consultar REGLA 2: Capa de Puertos]. Comprueba que la interfaz use tipos limpios.

Paso 5: Aislar el Código Antiguo en un Adaptador

Encapsula el código técnico original para que sirva al dominio de forma controlada.

• Acción: Traslada las líneas de código de infraestructura identificadas en el Paso 1 (aquellas que invocaban el SDK o interactuaban con el disco) a una clase dentro de src/infrastructure/.
• Implementación: Asegúrate de que esta clase implemente la interfaz del puerto correspondiente (implements PortName). Su responsabilidad exclusiva será traducir el formato "sucio" u originario del tercero al formato estructurado y limpio que exige nuestro dominio.
• Foco de Validación: [Cargar SKILL: pragmatic-architecture-guidelines -> Consultar REGLA 3: Capa de Infraestructura]. Comprueba que el adaptador se encargue de mapear las respuestas sucias del exterior a entidades de dominio.

Paso 6: El "Cableado" Final y Verificación

Reconecta los componentes asegurando la preservación del comportamiento original.

• Acción: Vuelve al archivo original (ej. el comando CLI o script principal).
• Orquestación: 1. Instancia el nuevo adaptador de infraestructura. 2. Invoca el adaptador para recuperar los datos requeridos. 3. Envía los datos recuperados a la función o entidad pura de dominio. 4. Pasa el resultado arrojado por el dominio al adaptador encargado de la salida (ej. guardar en base de datos, escribir en disco o imprimir en terminal).
• Foco de Validación: [Cargar SKILL: pragmatic-architecture-guidelines -> Consultar REGLA 4 (Boy Scout)]. Ejecuta la suite de pruebas unitarias o de integración para validar que el comportamiento de la aplicación de cara al usuario final permanezca inalterado.Una vez comprobado que el test del Paso 2 sigue en verde, realiza una última pasada de limpieza en el punto de entrada original eliminando variables muertas, simplificando flujos y garantizando que el archivo final queda ostensiblemente más ordenado, legible y robusto que cuando lo abriste.

---

⚠️ Reglas Antipatrón a Evitar durante la Refactorización

• No arrastrar SDKs: Si un parámetro de la función de dominio expone un tipo propio de una librería de terceros (ej. NotionResponse), la refactorización ha fallado. Modela un tipo genérico propio.
• No saltearse el Puerto: Evita conectar el archivo original directamente a la infraestructura sin pasar por la abstracción de la interfaz en la capa de puertos.