Clean architecture en la práctica: guía para quien entrega software

La clean architecture es una de esas ideas que todo el mundo cita y pocos aplican con criterio. Un bando la ignora y vive en un barro de dependencias; el otro la aplica como dogma y convierte un CRUD en cuarenta archivos de ceremonia. En Lasting Dynamics la usamos en sistemas en producción desde hace años y la enseñamos en nuestra academy — esta guía es como la explicamos internamente: la regla que importa, los límites que importan, y la honestidad de decir cuándo no usarla.

La única regla que importa de verdad

Quita los diagramas de círculos concéntricos y la clean architecture (Robert C. Martin, 2012 — con la arquitectura hexagonal o de ports & adapters y la onion architecture como parientes cercanos) se reduce a una sola regla:

Las dependencias apuntan hacia dentro: la lógica de negocio no sabe nada de bases de datos, frameworks, UI ni servicios externos.

Todo lo demás — entities, use cases, interface adapters — es una forma de organizar esa regla en capas. La idea central: el código que decide qué hace tu sistema no importa tu ORM y no sabe que HTTP existe. Los detalles técnicos dependen de las decisiones de negocio, nunca al revés.

¿Por qué es la regla correcta? Porque los detalles cambian y las reglas de negocio permanecen. En una década de proyectos de clientes hemos cambiado de ORM, de base de datos, de proveedor de pagos y de framework de frontend — varias veces. Las reglas de negocio de los clientes sobrevivieron a todo. Una arquitectura que acopla lo segundo a lo primero paga cada cambio, con intereses.

Cómo se ve en un proyecto real

Olvida los cuatro círculos por un momento; en un servicio típico la sustancia es esta:

src/
  domain/          ← entidades y reglas de negocio. Cero imports externos.
  application/     ← use cases que orquestan el dominio. DECLARAN
                     interfaces para lo que necesitan (repository, mailer…)
  infrastructure/  ← implementaciones concretas: Postgres, Stripe, SMTP.
                     Implementan las interfaces de application.
  interface/       ← handlers HTTP, CLI, UI: traducen el mundo exterior
                     en llamadas a los use cases.

El mecanismo que lo sostiene todo es la inversión de dependencias: un use case declara interface ApplicationRepository { save(app): ... } y no le importa si detrás hay Postgres, un archivo o un mock en los tests. La implementación concreta vive fuera y se inyecta.

Los beneficios son inmediatos y medibles:

• Testabilidad. Los use cases se testean en milisegundos, sin base de datos ni red. Las suites rápidas son las que la gente escribe y ejecuta de verdad.
• Sustituibilidad. Cambiar de ORM o de proveedor toca infrastructure/, no las reglas.
• Intención legible. application/submit-application.ts te dice qué hace el sistema; el código se convierte en documentación del negocio.

Dónde se equivoca la gente (en las dos direcciones)

Error 1 — El dogma de las capas. Cuatro capas, mappers entre cada una, DTOs en cada salto: para un formulario que inserta una fila, eso son 300 líneas de ceremonia alrededor de 10 de lógica. La clean architecture protege la lógica de negocio; si la lógica de negocio es "guárdalo y muéstralo", no hay nada que proteger. Un CRUD tiene derecho a seguir siendo un CRUD.

Error 2 — Los límites falsos. Capas que existen en los nombres de las carpetas pero no en las dependencias: un "dominio" que importa el ORM, un use case que lee req.headers. Es lo peor de los dos mundos — la ceremonia sin los beneficios. El test es mecánico: ¿qué importa tu dominio? Si la respuesta no es "nada externo", tus límites son decorativos.

Error 3 — Abstracción preventiva en todas partes. Interfaces para cosas que nunca van a cambiar, "por si acaso". Las abstracciones se pagan en indirección; ponlas donde el cambio es plausible (almacenamiento, servicios externos, canales de I/O), no en todas partes por principio.

Error 4 — Confundir clean architecture con microservicios. Son ortogonales. Un monolito con límites internos limpios es una arquitectura excelente — y normalmente el punto de partida correcto. Los buenos límites internos son además exactamente lo que hace posible extraer un servicio mañana, si algún día hace falta.

Cuándo compensa y cuándo es overkill

Compensa cuando: hay lógica de negocio real (reglas, estados, cálculos, políticas), el sistema va a vivir años, trabaja en él más de una persona, o los detalles técnicos son inestables (más frecuente de lo que se admite).

Es overkill cuando: es un prototipo, una herramienta interna de usar y tirar, un CRUD fino sobre una base de datos — o cuando el equipo aún no tiene el criterio para trazar los límites correctos, porque unos límites mal puestos cuestan más que ninguno.

La versión honesta de la buena práctica: empieza simple, pero mantén la regla de las dependencias como brújula. Incluso en un proyecto pequeño, mantener la lógica fuera de los controllers HTTP cuesta casi nada y deja abiertas todas las opciones futuras.

En la era de los agentes AI importa más, no menos

Un detalle que se ha vuelto central: las herramientas de agentic coding funcionan drásticamente mejor sobre codebases con límites claros. Un agente que cambia una regla de negocio en un sistema con el dominio aislado toca un archivo y sus tests; en el espagueti toca veinte archivos y tú cruzas los dedos. Los límites arquitectónicos son también la forma en que la AI sabe dónde meter mano — como lo contamos en nuestra guía de Claude Code: la estructura la decides tú, la AI la rellena.

Cómo se aprende esto de verdad

La clean architecture no se aprende con diagramas — se aprende trazando límites en sistemas reales y con alguien más experimentado diciéndote exactamente por qué el tuyo está en el sitio equivocado. Ese es el formato de la Lasting Dynamics Academy: la arquitectura de software está en el curriculum junto a patrones de diseño, RDBMS y testing, entrenada con tareas reales y una review semanal con el mentor. Gratuita, en remoto total, con plazas limitadas, y todo el que la completa recibe una oferta de trabajo. Si esta guía te ha sonado a ingeniería sensata, las solicitudes están abiertas.

FAQ

¿Clean architecture y arquitectura hexagonal son lo mismo? Parientes muy cercanos: hexagonal (ports & adapters), onion y clean comparten la idea central — dominio en el centro, dependencias hacia dentro, detalles en los bordes. Las diferencias son de terminología y de granularidad de las capas. Elige una y sé consistente; discutir sobre los nombres es tiempo perdido.

¿Se aplica al frontend? El principio sí: separar el estado y la lógica de negocio de los componentes de UI (que son tan "detalle" como la base de datos). El aparato completo de capas suele ser demasiado; la regla de las dependencias por sí sola aporta la mayor parte del valor.

¿Por dónde empiezo en un codebase existente? Por la próxima pieza de lógica que tengas que tocar: extráela a una función pura, dale una interfaz para sus dependencias, cúbrela de tests. La clean architecture en un sistema legacy se conquista un límite cada vez, no con un big bang.