CommunityProgramación y desarrollogithub.com

A Arquitectura Hexagonal

Analiza un código base existente en cualquier lenguaje o framework y produce un plan de refactorización por fases, sin cambios disruptivos, para migrarlo a Arquitectura Hexagonal (Puertos y Adaptadores). Úsalo cuando el usuario solicite refactorizar, migrar o reestructurar un servicio, API o monolito hacia arquitectura hexagonal, puertos y adaptadores o arquitectura limpia, preservando los contratos existentes.

¿Qué es A Arquitectura Hexagonal?

Esta habilidad guía a un agente de IA (como Claude Code, Cursor o Codex) para que analice en profundidad un repositorio existente y diseñe un plan de refactorización atómico y por fases hacia Arquitectura Hexagonal (Patrón Puertos y Adaptadores). Es especialmente útil cuando se necesita desacoplar la lógica de negocio de frameworks web, ORMs, bases de datos, brokers de mensajes o SDKs externos, todo ello sin romper ningún contrato externo ni comportamiento observable existente. La habilidad sigue el principio fundamental de 'cero cambios disruptivos', asegurando que rutas, métodos HTTP, códigos de estado, esquemas de payload, encabezados, formatos de error y formas de mensajes permanezcan idénticos durante todo el proceso. El flujo de trabajo incluye un descubrimiento inicial del código base (stack, puntos de entrada, dependencias externas, flujo de ejecución), el diseño de la estructura hexagonal objetivo (dominio, aplicación, infraestructura) con capas y responsabilidades claras (dominio puro sin dependencias de framework, casos de uso en aplicación, y adaptadores concretos en infraestructura). Finalmente, se produce un plan de ejecución por fases (caracterización, extracción del dominio, implementación de casos de uso y adaptadores, y limpieza) con puntos de control de validación para garantizar que no se introduzcan regresiones. Soporta cualquier lenguaje y ecosistema (TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust) adaptando las convenciones de directorios, nombres, tipado y herramientas de prueba.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrandalisse/skills/tree/HEAD/skills/to-hexagonal-architecture

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace A Arquitectura Hexagonal?

Analiza en profundidad un repositorio existente y diseña un plan de refactorización atómico y por fases para migrarlo a Arquitectura Hexagonal (Puertos y Adaptadores) sin romper ningún contrato externo ni comportamiento observable.

Responde en el mismo idioma de la solicitud del usuario. Opera estrictamente en Modo Plan: inspecciona el código base primero y entrega el plan completo antes de modificar cualquier archivo.

Cuándo Usarlo

  • El usuario solicita migrar o refactorizar un proyecto existente hacia Arquitectura Hexagonal o Puertos y Adaptadores.
  • El usuario quiere desacoplar la lógica de negocio de frameworks web, ORMs, bases de datos, brokers de mensajes o SDKs externos.
  • El usuario pide un plan de refactorización arquitectónica seguro, incremental y con cero cambios disruptivos.

Principios Fundamentales

  1. Cero Cambios Disruptivos (Regla de Oro): Preserva cada contrato externo existente. Las rutas, métodos HTTP, códigos de estado, esquemas de payload de solicitud/respuesta, encabezados, formatos de error, banderas de CLI o formas de mensajes de cola deben permanecer idénticos.
  2. Caracterización Antes de Refactorizar: Nunca muevas o elimines lógica de producción hasta que pruebas automatizadas de contrato/caracterización cubran los endpoints o puntos de entrada existentes.
  3. Regla de Dependencia Estricta: Las dependencias del código fuente siempre deben apuntar hacia adentro, hacia el domain. La capa de dominio debe tener cero importaciones de frameworks web, controladores de bases de datos, ORMs, bibliotecas de serialización o SDKs externos.
  4. Adaptación Idiomática del Stack: Adapta las rutas de directorios, convenciones de nomenclatura, construcciones de tipado y ejecutores de pruebas al lenguaje y ecosistema detectados del proyecto (por ejemplo, TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).

Flujo de Trabajo

Paso 1: Descubrimiento del Código Base

Escanea el repositorio antes de proponer cualquier árbol de carpetas o pasos de migración:

  1. Stack y Herramientas: Inspecciona los manifiestos de dependencias, configuraciones de compilador/linter y ejecutores de pruebas para identificar el lenguaje, framework, biblioteca de validación, ORM/constructor de consultas y enfoque de DI.
  2. Puntos de Entrada y Contratos: Inventaria todos los puntos de entrada principales (rutas HTTP, resolutores GraphQL, servicios gRPC, consumidores de mensajes, trabajos cron), sus esquemas de validación, middlewares/interceptores y manejadores de errores globales.
  3. Dependencias Externas: Inventaria todos los efectos secundarios impulsados (bases de datos, cachés, clientes HTTP/RPC, colas, almacenamiento de archivos, configuración de entorno, registradores).
  4. Flujo de Ejecución Actual: Traza cómo fluyen los datos actualmente desde el punto de entrada hasta la persistencia/llamada externa y de vuelta, notando dónde se mezclan las reglas de negocio con detalles de transporte o persistencia.

Paso 2: Diseñar la Estructura Hexagonal Objetivo

Mapea las tres capas concéntricas a la raíz de código fuente idiomática del proyecto (por ejemplo, src/ en TypeScript/Rust, internal/ en Go, src/main/<lang>/ en JVM, o el directorio del paquete principal en Python):

  • domain/ (Núcleo de Negocio Puro - cero dependencias de framework o E/S):
    • entities/ y value-objects/: Modelos de dominio que encapsulan reglas de negocio, invariantes y autovalidación.
    • ports/in/: Interfaces de puertos principales que definen contratos de casos de uso.
    • ports/out/: Interfaces de puertos secundarios que definen contratos de repositorio, servicio externo, publicador de eventos y LoggerPort.
    • errors/: Excepciones semánticas de dominio (por ejemplo, ResourceNotFoundError, DomainValidationError, ConflictError).
  • application/ (Orquestación de Casos de Uso):
    • use-cases/: Implementaciones de ports/in que coordinan entidades de dominio y ports/out.
    • dtos/: Estructuras de datos de entrada y salida inmutables, desacopladas de los payloads de transporte y las entidades de persistencia.
  • infrastructure/ (Detalles Técnicos y Adaptadores):
    • adapters/in/: Adaptadores principales (controladores/manejadores HTTP, manejadores de consumidores), esquemas de validación de transporte, mapeadores (TransportInput -> InputDTO y OutputDTO -> TransportOutput), y un mapeador de errores global que traduce domain/errors a las respuestas de error exactas del legado.
    • adapters/out/: Implementaciones concretas de ports/out (repositorios de base de datos, clientes HTTP, brokers) con mapeadores de persistencia/externos para que los modelos ORM o tipos SDK nunca se filtren al domain.
    • config/: Carga estricta y validación de inicio de variables de entorno y configuraciones de ejecución.
    • di/ (Raíz de Composición): Cableado explícito de adaptadores secundarios, casos de uso y adaptadores principales mediante inyección de constructor, evitando singletons ocultos o localizadores de servicios.
  • Separación del Arranque: Separa la construcción de la aplicación (buildApp / función de fábrica para pruebas de integración aisladas) del inicio del servidor/proceso (main / listen).

Paso 3: Aplicar Estándares de Ingeniería en el Plan

Asegura que cada fase del plan aplique:

  • Tipado Fuerte e Inmutabilidad: Prohíbe escapes sin tipo (como any o mapas sin tipo donde corresponden estructuras tipadas) y favorece DTOs y Value Objects inmutables (readonly, dataclasses congeladas, registros, tipos valor).
  • SOLID e Inyección de Constructor: Mantén las clases y funciones pequeñas con responsabilidades únicas; inyecta interfaces a través de constructores.
  • Observabilidad sin Acoplamiento: Preserva el registro estructurado y el contexto de correlación de solicitudes, manteniendo domain/ y application/ desacoplados de bibliotecas de registro específicas mediante LoggerPort.
  • Pruebas Piramidales:
    • Pruebas unitarias para domain/ (invariantes puras) y application/ (simulando ports/out).
    • Pruebas de integración/contrato que verifiquen los adaptadores principales reales contra el cableado de la aplicación utilizando el cliente de prueba en memoria nativo del stack (por ejemplo, fastify.inject, Supertest, FastAPI TestClient, Spring MockMvc o Go httptest).

Formato de Salida (Modo Plan)

Entrega la respuesta estructurada en estas secciones exactas:

  1. Diagnóstico de la Arquitectura Actual: Inventario conciso del stack detectado, puntos de entrada/endpoints, dependencias externas y principales puntos calientes de acoplamiento.
  2. Árbol de Directorios Objetivo: Estructura de carpetas propuesta completa utilizando los nombres de módulos y características reales encontrados en el repositorio.
  3. Plan de Ejecución por Fases: Cinco fases atómicas y verificables:
    • Fase 1 - Pruebas de Caracterización y Andamiaje Base: Crea pruebas de contrato que bloqueen el comportamiento actual, crea las carpetas objetivo, el cargador de configuración y la raíz de composición (di/).
    • Fase 2 - Extracción del Dominio: Extrae entidades, value objects, errores de dominio e interfaces de ports/in + ports/out con pruebas unitarias.
    • Fase 3 - Casos de Uso de Aplicación y Adaptadores Secundarios: Implementa casos de uso, DTOs, repositorios/clientes de adapters/out y mapeadores de persistencia.
    • Fase 4 - Adaptadores Principales y Traducción de Errores: Refactoriza controladores/manejadores para delegar en casos de uso a través de mapeadores, cablea la traducción de errores global y conecta di/.
    • Fase 5 - Limpieza del Legado y Verificación Final: Elimina archivos obsoletos, ejecuta el conjunto completo de pruebas, el linter y el verificador de tipos, y verifica cero desviaciones de contrato.
  4. Puntos de Control de Validación: Comando o verificación explícita al final de cada fase que demuestre que nada se rompió antes de avanzar a la siguiente fase.

Trampas Comunes

  • No edites código prematuramente: A menos que el usuario solicite explícitamente comenzar a ejecutar la Fase 1 de inmediato, primero entrega solo el plan para que puedan revisar los límites de los módulos.
  • Evita la sobre-abstracción en CRUD triviales: Aún así separa claramente domain, application e infrastructure, pero mantén los casos de uso de paso a través concisos en lugar de inventar complejidad de dominio artificial.
  • Iguala peculiaridades del legado: Si un endpoint existente devuelve un código de estado no estándar o un nombre de campo de error, documéntalo en la Fase 1 y presérvalo en el mapeador de errores de infrastructure para que los clientes existentes no se rompan.

Skills relacionados