Marco de Arquitectura Limpia
Un enfoque disciplinado para estructurar software de manera que las reglas de negocio permanezcan independientes de frameworks, bases de datos y mecanismos de entrega. Aplica estos principios al diseñar la arquitectura del sistema, revisar los límites de los módulos o asesorar sobre la gestión de dependencias.
Principio Central
Las dependencias del código fuente deben apuntar hacia adentro — hacia las políticas de más alto nivel. Nada en un círculo interno puede saber nada acerca de un círculo externo. Esta única regla produce sistemas que son comprobables e independientes de frameworks, IU, base de datos y cualquier agencia externa. Las reglas de negocio son lo que importa; las bases de datos, los frameworks web y los mecanismos de entrega son detalles — cuando los detalles dependen de las políticas, puedes aplazar decisiones, intercambiar implementaciones y probar la lógica de negocio de forma aislada.
Puntuación
Objetivo: 10/10. Asigna un punto por cada una de las siete filas del Diagnóstico Rápido que la arquitectura cumpla (0-7), luego asigna a una banda de 0-10: 6-7 cumplidas = 9-10 (la Regla de Dependencia se cumple, la lógica de negocio es independiente del framework y la BD); 4-5 = 6-8 (el núcleo es comprobable pero algunos detalles se filtran hacia adentro); 2-3 = 3-5 (el framework o la persistencia dictan la estructura); 0-1 = 0-2 (sin límites — las reglas de negocio viven en controladores y modelos ORM). Reporta la puntuación, las filas de diagnóstico fallidas y la inversión específica necesaria para corregir cada una.
1. Regla de Dependencia y Círculos Concéntricos
Concepto central: Organiza la arquitectura como círculos concéntricos — Entidades (reglas de negocio empresariales) en el centro, luego Casos de Uso (reglas de negocio de la aplicación), luego Adaptadores de Interfaz, con Frameworks y Controladores en el exterior. Las dependencias del código fuente siempre apuntan hacia adentro.
Por qué funciona: Cuando las políticas de alto nivel no dependen de los detalles de bajo nivel, puedes intercambiar la base de datos, el framework web o el estilo de API sin tocar la lógica de negocio — el sistema se vuelve resistente a las partes más volátiles de la pila.
Perspectivas clave:
- Los círculos internos no pueden mencionar nombres de círculos externos — sin clases, funciones, variables o formatos de datos del exterior
- Los datos que cruzan un límite deben estar en la forma más conveniente para el círculo interno, nunca dictada por el externo
- La Inversión de Dependencia (interfaces definidas hacia adentro, implementadas hacia afuera) es el mecanismo que impone la regla
- El número de círculos no es fijo — cuatro es típico; la regla sigue siendo la misma
- Los frameworks son detalles, no arquitectura — pertenecen al círculo más externo
Aplicaciones de código:
| Contexto | Patrón | Ejemplo |
|---|---|---|
| Dirección de capas | Los círculos internos definen interfaces; los externos implementan | Interfaz UserRepository en Casos de Uso; PostgresUserRepository en Adaptadores |
| Cruce de datos | Los DTOs cruzan límites, no las entidades ORM | El Caso de Uso devuelve un DTO UserResponse, no un modelo ActiveRecord |
| Dirección de dependencia | Las importaciones siempre apuntan hacia adentro | El Controlador importa el Caso de Uso; el Caso de Uso nunca importa el Controlador |
Consulta references/dependency-rule.md cuando una importación de un círculo interno apunte hacia afuera y necesites el recorrido de código de los cuatro círculos, las reglas de cruce de datos y el procedimiento de inversión de dependencia en cuatro pasos para corregirlo.
2. Entidades y Casos de Uso
Concepto central: Las Entidades encapsulan las reglas de negocio a nivel empresarial — reglas que existirían incluso sin software. Los Casos de Uso contienen reglas específicas de la aplicación que orquestan el flujo de datos hacia y desde las Entidades.
Por qué funciona: Separar lo que el negocio hace (Entidades) de cómo la aplicación lo orquesta (Casos de Uso) permite reutilizar Entidades en múltiples aplicaciones y cambiar el comportamiento de la aplicación sin alterar las reglas de negocio centrales.
Perspectivas clave:
- Las Entidades no son filas de base de datos — son objetos o funciones puras que encapsulan reglas de negocio críticas
- Los Casos de Uso aceptan Modelos de Solicitud y devuelven Modelos de Respuesta — nunca objetos del framework
- Cada Caso de Uso es una operación única de la aplicación (
CreateOrder,ApproveExpense) - El patrón Interactor: una clase Caso de Uso implementa una interfaz de límite de entrada y llama a una interfaz de límite de salida
- Los cambios en un Caso de Uso nunca deben afectar a una Entidad; los cambios en una Entidad pueden propagarse a los Casos de Uso
Aplicaciones de código:
| Contexto | Patrón | Ejemplo |
|---|---|---|
| Diseño de Entidad | Reglas de negocio críticas, cero dependencias del framework | Order.calculateTotal() aplica reglas fiscales; no sabe nada sobre HTTP |
| Solicitud/Respuesta | Estructuras de datos simples cruzan el límite | CreateOrderRequest { items, customerId } — sin modelos ORM |
| Responsabilidad única | Un Caso de Uso por operación | PlaceOrder, CancelOrder, RefundOrder como clases separadas |
| Interactor | Implementa el Puerto de Entrada, llama al Puerto de Salida | PlaceOrderInteractor implements PlaceOrderInput |
Consulta references/entities-use-cases.md al diseñar un Interactor o decidir qué pertenece a una Entidad versus un Caso de Uso — tratamiento completo de Reglas de Negocio Empresariales vs. de Aplicación con ejemplos de modelos de solicitud/respuesta.
3. Adaptadores de Interfaz y Frameworks
Concepto central: Los Adaptadores de Interfaz convierten datos entre la forma conveniente para los Casos de Uso/Entidades y la forma requerida por las agencias externas. Los Frameworks y Controladores son la capa más externa — código de pegamento con el mundo exterior.
Por qué funciona: Cuando el framework web, ORM o cola de mensajes está confinado a los círculos externos, reemplazar cualquiera de ellos es un cambio localizado. La base de datos es un detalle; la web es un detalle; los detalles deben ser complementos para tus reglas de negocio, no el esqueleto de la aplicación.
Perspectivas clave:
- Los Controladores traducen HTTP a entrada del Caso de Uso; los Presentadores traducen la salida del Caso de Uso a modelos de vista
- Las Pasarelas implementan interfaces de repositorio definidas por los Casos de Uso — el círculo interno define el contrato, el externo lo cumple
- Las reglas de negocio nunca saben si los datos viven en SQL, NoSQL o archivos planos, o que la entrega es HTTP
- Trata a los frameworks con sospecha — quieren que te acoples a ellos; mantenlos a distancia
Aplicaciones de código:
| Contexto | Patrón | Ejemplo |
|---|---|---|
| Controlador | Mecanismo de entrega → entrada del Caso de Uso | OrderController.create(req) construye CreateOrderRequest, llama al Interactor |
| Presentador | Salida del Caso de Uso → modelo de vista | OrderPresenter.present(response) formatea para JSON/HTML |
| Pasarela | Interfaz de Repositorio implementada por BD | SqlOrderRepository implements OrderRepository |
| Límite del framework | El framework llama hacia adentro, nunca al revés | El manejador de ruta de Express llama al Controlador; el Controlador nunca importa Express |
Consulta references/adapters-frameworks.md al cablear controladores, presentadores o pasarelas, o al argumentar que la base de datos/web es un detalle — cubre la arquitectura de complementos y cómo confinar un framework a los bordes.
4. Principios de Componentes
Concepto central: Los componentes son las unidades de despliegue. Tres principios de cohesión gobiernan lo que va dentro de un componente; tres principios de acoplamiento gobiernan las relaciones entre componentes.
Por qué funciona: Los componentes mal compuestos crean efectos dominó donde un cambio obliga a redesplegar código no relacionado; los principios mantienen los cambios localizados y los lanzamientos independientes.
Perspectivas clave:
- REP (Equivalencia de Reutilización/Lanzamiento): las clases en un componente deben poder versionarse y lanzarse como una unidad
- CCP (Cierre Común): las clases que cambian por la misma razón al mismo tiempo pertenecen juntas — SRP para componentes
- CRP (Reutilización Común): no obligues a los usuarios a depender de clases que no usan
- ADP (Dependencias Acíclicas): el grafo de componentes no debe tener ciclos — rómpelos con DIP o un nuevo componente
- SDP (Dependencias Estables): depende en la dirección de la estabilidad
- SAP (Abstracciones Estables): los componentes estables deben ser abstractos; los inestables, concretos
Aplicaciones de código:
| Contexto | Patrón | Ejemplo |
|---|---|---|
| Agrupación de componentes | Agrupa clases que cambian juntas (CCP) | Todos los Casos de Uso relacionados con pedidos en un componente |
| Romper ciclos | Aplica DIP para invertir una arista de dependencia | Extraer una interfaz en un nuevo componente para romper el ciclo |
| Métricas de estabilidad | Inestabilidad I = Ce / (Ca + Ce) | Muchas dependencias entrantes, ninguna saliente → I cerca de 0 (estable) |
Consulta references/component-principles.md al agrupar clases en componentes desplegables o romper un ciclo de dependencia — cada uno de REP, CCP, CRP, ADP, SDP, SAP trabajados con la métrica de inestabilidad.
5. Principios SOLID
Concepto central: Cinco principios a nivel de clase y módulo — Responsabilidad Única, Abierto-Cerrado, Sustitución de Liskov, Segregación de Interfaz, Inversión de Dependencia — los bloques de construcción de nivel medio que hacen posible la Regla de Dependencia.
Por qué funciona: Cada principio aborda una forma específica en que las dependencias salen mal, previniendo la rigidez, fragilidad e inmovilidad que convierten las bases de código en pesadillas heredadas.
Perspectivas clave:
- SRP: un módulo tiene una razón para cambiar — sirve a un actor (no "hace una cosa")
- OCP: extiende el comportamiento añadiendo nuevo código, no modificando el existente — patrones de estrategia y complemento
- LSP: los subtipos deben ser utilizables a través de la interfaz base sin que el cliente lo sepa — violado por excepciones inesperadas o métodos ignorados
- ISP: los clientes no deben depender de métodos que no usan — las interfaces grandes crean acoplamiento innecesario
- DIP: los módulos de alto nivel y los de bajo nivel dependen de abstracciones definidas por el módulo de alto nivel
Aplicaciones de código:
| Contexto | Patrón | Ejemplo |
|---|---|---|
| Violación de SRP | Clase sirve a múltiples actores | Employee maneja nómina (CFO), informes (COO), persistencia (CTO) |
| OCP mediante estrategia | Nuevo comportamiento a través de nuevas clases | Añadir ExpressShipping implementando ShippingStrategy; Order intacto |
| Violación de LSP | Subtipo cambia el comportamiento esperado | Square extends Rectangle rompe el contrato setWidth()/setHeight() |
| Aplicación de ISP | Divide interfaces grandes en interfaces de rol | Printer, Scanner, Fax en lugar de un MultiFunctionDevice |
| Cableado de DIP | Alto nivel define interfaz; bajo nivel implementa | OrderService depende de PaymentGateway, no de StripeClient |
Consulta references/solid-principles.md al aplicar SRP/OCP/LSP/ISP/DIP a una clase específica o diagnosticar una violación — cada principio trabajado con ejemplos de código y el olor que previene.
6. Límites y Anatomía de Límites
Concepto central: Un límite es una línea entre cosas que importan y cosas que son detalles, implementada mediante polimorfismo: las dependencias cruzan apuntando hacia adentro mientras que el flujo de control puede cruzar en cualquier dirección.
Por qué funciona: Cada límite compra la opción de aplazar una decisión o intercambiar una implementación; la colocación estratégica de límites determina si un sistema es un placer o un dolor de mantener durante años.
Perspectivas clave:
- Los límites completos usan interfaces recíprocas en ambos lados; los límites parciales usan una estrategia o fachada más simple
- Patrón Objeto Humilde: divide el código del límite en una parte difícil de probar (cerca del límite) y una parte fácil de probar (la lógica)
- Los servicios no son automáticamente límites arquitectónicos — un microservicio con un modelo de datos compartido grande es un monolito con llamadas de red
- Las pruebas son el componente más aislado: dependen hacia adentro, nada depende de ellas
- Los límites prematuros son costosos, pero también lo son los que faltan — dibújalos en puntos de volatilidad probable
Aplicaciones de código:
| Contexto | Patrón | Ejemplo |
|---|---|---|
| Límite completo vs. parcial | Puertos recíprocos, o una estrategia solitaria | El Caso de Uso define PlaceOrderInput/PlaceOrderOutput; casos más simples toman una ShippingStrategy |
| Objeto Humilde | Separa la lógica comprobable de la infraestructura | PresenterLogic (comprobable) produce ViewModel; View (humilde) lo renderiza |
| Main como complemento | La raíz de composición ensambla el sistema | main() conecta todas las implementaciones concretas e inicia la aplicación |
Consulta references/boundaries.md al decidir dónde dibujar un límite, elegir entre completo y parcial, o aplicar el patrón Objeto Humilde — también cubre servicios como límites, límites de prueba y Main como el complemento definitivo.
Errores Comunes
| Error | Por qué Fall | Solución |
|---|---|---|
| ORM filtrándose en la lógica de negocio | Las Entidades se acoplan al esquema; cambios en BD reescriben reglas de negocio | Separa las entidades de dominio de los modelos de persistencia; mapea en la capa adaptadora |
| Reglas de negocio en controladores | No comprobable sin HTTP; duplicado entre endpoints | Mueve la lógica a Interactores de Casos de Uso; los controladores solo traducen y delegan |
| Arquitectura primero-framework | El framework dicta la estructura; intercambiarlo significa reescribir | Trata el framework como un complemento; estructura el código por capacidad de negocio |
| Dependencias circulares de componentes | Los cambios se propagan impredeciblemente; sin lanzamientos independientes | Aplica DIP o extrae un componente de abstracción compartido |
| Un Caso de Uso gigante por funcionalidad | Orquestadores inflados de mil líneas | Divide en Casos de Uso enfocados de una sola operación |
| Saltarse límites "porque es simple" | El acoplamiento se acumula silenciosamente hasta que el costo es enorme | Dibuja límites proactivamente en puntos de volatilidad probable |
| Microservicios como buena arquitectura automática | Un monolito distribuido es peor que un monolito limpio | Aplica la Regla de Dependencia dentro y entre servicios; los servicios son límites de despliegue, no arquitectónicos |
Diagnóstico Rápido
| Pregunta | Si No | Acción |
|---|---|---|
| ¿Puedes probar las reglas de negocio sin BD, servidor web o framework? | Las reglas están acopladas a la infraestructura | Extrae entidades y casos de uso detrás de interfaces; simula capas externas |
| ¿Todas las dependencias del código fuente apuntan hacia adentro? | Hay dependencias hacia afuera | Aplica Inversión de Dependencia: define la interfaz en el círculo interno; implementa en el externo |
| ¿Los casos de uso no importan desde frameworks? | Los casos de uso dependen de objetos del framework | Reemplaza importaciones de framework con parámetros de tipo/función definidos por el caso de uso |
| ¿Las entidades no tienen dependencias de frameworks? | Las entidades importan desde ORM, HTTP u otros frameworks | Elimina importaciones de framework; usa estructuras simples de datos/control |
| ¿Los controladores contienen solo lógica de traducción? | Los controladores contienen reglas de negocio | Mueve reglas de negocio a interactores de casos de uso |
| ¿Los presentadores son independientes del framework? | Los presentadores usan objetos del framework de IU | Aísla la lógica de presentación de los detalles del framework de IU |
| ¿Los adaptadores de base de datos implementan interfaces definidas por el caso de uso? | La capa de base de datos está ausente o expone directamente APIs de BD | Define interfaces de repositorio en la capa de caso de uso; haz que los adaptadores las implementen |
Este skill se publica bajo licencia MIT. Consulte el repositorio original de wondelai/skills (v1.4.0) para más información.