La arquitectura hexagonal no tiene nada de nuevo: Alistair Cockburn la documentó en 2005. Lo que ha cambiado es quién escribe el código hoy. En mis proyectos offshore en Vietnam, un desarrollador senior asistido por Claude Code produce entre tres y cuatro veces más líneas que hace dos años, y sin una frontera técnica clara, esa velocidad construye acoplamiento al mismo ritmo que construye funcionalidades.
- 🏗️ Dominio protegido, la lógica de negocio no depende de ningún framework ni base de datos.
- ⚠️ IA sin barandillas, el código generado a toda prisa por una IA agrava el acoplamiento cuando no hay una frontera clara.
- 🔑 Puertos y adaptadores, cada entrada y salida pasa por una interfaz definida por el dominio.
- 🚀 Veredicto de campo, al imponerla a mis equipos offshore, hace que Claude Code sea más fiable.
No defiendo la arquitectura hexagonal por purismo académico. La defiendo porque se ha convertido en la única red que evita que un código generado a toda prisa convierta tu producto en deuda técnica inmanejable en seis meses. Esa es la tesis que desarrollo aquí, con lo que observo en el terreno con mis clientes y en mis propios equipos.
La IA ha hecho el código rápido de producir, no menos peligroso
Hoy, alguien sin formación de ingeniero puede generar un endpoint de API, una consulta SQL y un componente React en pocos minutos con Claude Code o Cursor. Lo que estas herramientas no generan automáticamente es la frontera entre lo que pertenece a tu negocio y lo que pertenece a tu infraestructura.
Sin esa frontera, cada llamada directa a Prisma en un controlador, cada fetch() plantado en medio de una función de negocio, se va acumulando. El código funciona en la demo. Se vuelve imposible de mantener en cuanto quieres cambiar de base de datos, conectar un segundo frontend o simplemente escribir un test que no dependa de la red.
El vibe coding es útil para prototipar, peligroso para construir un producto sin supervisión técnica. Un estudio de McKinsey, citado a menudo en el sector, estima que la deuda técnica puede absorber entre el 20 % y el 40 % del presupuesto de TI de una empresa a lo largo de la vida de un sistema, según los trabajos de McKinsey Digital. Un código escrito diez veces más rápido sin arquitectura no reduce esa cifra: la acelera.
¿Por qué el vibe coding agrava un acoplamiento que nadie ve?
El acoplamiento no rompe nada el día en que se escribe. Rompe tres meses después, cuando un cambio de proveedor de pagos obliga a tocar cuarenta archivos en lugar de dos. Una IA que genera código sin restricción arquitectónica reproduce el camino más corto, no el más sano, porque es lo que le pide el prompt medio.
¿Qué es exactamente la arquitectura hexagonal?
Imagina tu aplicación como un hexágono. En el centro, el dominio: las reglas de negocio, las entidades, los casos de uso. Nada de ese centro sabe que existen PostgreSQL, Stripe o tu framework de frontend. Alrededor, los puertos, es decir, interfaces definidas por el propio dominio, que describen cómo acepta ser controlado y cómo espera recibir sus datos.
Los adaptadores llegan después para conectar esos puertos con el mundo real: un adaptador REST para la entrada del usuario, un adaptador de PostgreSQL para la persistencia, un adaptador de Stripe para el pago. El canal de YouTube CodelyTV resume bien la regla de dependencia: la infraestructura puede conocer el dominio, nunca al revés, y el dominio solo se conoce a sí mismo.
Alex Hyett, en su canal, recuerda el origen del término: Cockburn observó que interactuar con una base de datos e interactuar con una API externa sigue siempre el mismo esquema. En lugar de codificar ese vínculo de forma rígida, se define un contrato desde el lado del dominio, y cualquier adaptador puede cumplirlo. Es esa inversión la que hace que el núcleo de la aplicación sea testeable sin base de datos, sin red, sin mocks complicados.
¿Cómo funcionan en la práctica los puertos y los adaptadores?
Un puerto de entrada expone un caso de uso: "crear un usuario". Un puerto de salida describe una necesidad: "persistir un usuario". El dominio llama a esas interfaces sin saber quién las implementa. Augusto Galego, desarrollador senior brasileño, lo ilustra de forma sencilla en su vídeo: desde el punto de vista del servicio de negocio, escribir en una base de datos o publicar un mensaje en una cola no supone ninguna diferencia, solo importa el contrato.
Por qué se la impongo ahora a mis equipos offshore
Transparencia: dirijo una consultora offshore en Vietnam, así que tengo un sesgo evidente sobre este tema. Es también por eso que conozco sus límites reales, no solo los argumentos comerciales que se repiten en las reuniones de preventa.
En mayo de 2026, un equipo de tres desarrolladores vietnamitas que supervisas migró un backend en Node a una arquitectura hexagonal en doce días, antes de conectar Claude Code al dominio aislado para acelerar la escritura de los siguientes casos de uso. Resultado observado: las sugerencias de la IA se quedaban dentro del puerto que le tocaba cumplir, porque el contrato la obligaba a ello. Sin esa frontera, la misma herramienta habría propuesto importar directamente el cliente de Stripe en una función de cálculo de comisión, algo que un junior habría aceptado sin pestañear.
Creo que un desarrollador que usa Claude Code sigue siendo un ingeniero, no un simple operador de prompts, siempre que la arquitectura le impida tomar el atajo más rápido. Un equipo senior bien organizado, asistido por IA dentro de un dominio protegido, produce un código que un equipo sin estructura no alcanza a igualar, ni con el doble de plantilla.
¿Qué ocurre cuando la IA escribe contra un dominio mal aislado?
La IA nunca rechaza una mala idea si el código de alrededor no la prohíbe estructuralmente. Sin puerto ni adaptador, mezcla lógica de negocio y llamada de red en el mismo archivo, porque es el patrón más frecuente en su corpus de entrenamiento. La arquitectura hexagonal no hace más inteligente a la IA: reduce el espacio de errores que puede cometer sin que nadie lo note antes de que llegue a producción.
Hexagonal, clean, onion: el debate que nunca se cierra
Un hilo abierto en r/softwarearchitecture, titulado "Hexagonal vs Clean vs Onion, ¿cuál es realmente la más sólida?", resume bien la confusión reinante. Otro desarrollador, en ese mismo foro, lleva el matiz más lejos en el hilo "Layered Architecture != Hexagonale, Onion and Clean Architecture": para él, la arquitectura en capas clásica es una macroarquitectura que moldea la organización de los equipos, mientras que hexagonal, onion y clean describen sobre todo cómo estructurar el interior de la capa de negocio.
Estoy de acuerdo con ese planteamiento. No son alternativas intercambiables, son variaciones sobre una misma idea: aislar el negocio, invertir las dependencias hacia ese centro. El canal Código Fonte TV recuerda incluso que el nombre "hexagonal" viene únicamente de la ilustración elegida por Cockburn, no de un número mágico de seis puertos obligatorios.
«La arquitectura no protege contra la IA. Protege contra los desarrolladores, humanos o aumentados, que usan la IA sin entender lo que construyen.»
Vincent Roye, agosto de 2026
| Criterio | Hexagonal | Clean Architecture | Onion | Arquitectura en capas |
|---|---|---|---|---|
| Acoplamiento al framework | Muy bajo | Muy bajo | Bajo | Alto |
| Testabilidad del dominio | Alta sin mocks pesados | Alta | Alta | Depende de la capa |
| Curva de aprendizaje para un equipo junior | Media | Alta | Media | Baja |
| Resistencia al código de IA mal supervisado | Alta, contrato explícito | Alta | Media | Baja |
| Coste de migración desde un legacy | Progresivo, puerto a puerto | Alto, reescritura amplia | Progresivo | Nulo, ya es el sistema existente |
FUENTE: hilos de r/softwarearchitecture, blog.octo.com · ACTUALIZADO 08/2026
¿Hay que elegir realmente entre hexagonal, clean y onion?
No, y es una trampa creer que hay que zanjar el tema de una vez por todas. El blog OCTO, referencia francesa en la materia, describe tres principios suficientes para empezar: separar de forma explícita la entrada del usuario, la lógica de negocio y la salida técnica, hacer que las dependencias apunten hacia esa lógica de negocio, aislar las fronteras mediante puertos y adaptadores. Estos tres principios se aplican tanto si llamas al resultado hexagonal, clean u onion.
Las trampas que convierten la arquitectura hexagonal en una fábrica de complejidad
En un hilo de r/androiddev, un desarrollador en busca de un catálogo de patrones resume una frustración real: demasiados artículos venden la arquitectura hexagonal como una solución universal sin decir nunca cuándo cuesta más de lo que aporta. Tiene razón en desconfiar.
En un CRUD sencillo, sin lógica de negocio significativa, apilar puertos y adaptadores para tres entidades añade indirección sin beneficio medible. He visto equipos junior pasar dos semanas creando interfaces para un único adaptador concreto, justo lo contrario del objetivo perseguido.
La regla que aplico con mis equipos es simple: la arquitectura hexagonal se justifica en cuanto la lógica de negocio supera la mera fontanería, o en cuanto sabes de antemano que la infraestructura va a cambiar. Una startup que sabe que tendrá que migrar de Firebase a un backend propio en dieciocho meses gana aislando su dominio desde el principio. Un script interno desechable no lo necesita.
El veredicto
La arquitectura hexagonal no es un estándar que marcar para tranquilizar a un cliente o a un inversor. Es una decisión que determina si tu código generado por IA sigue bajo control humano o se acumula como deuda invisible hasta el día en que ya nadie quiere tocarlo. Recomiendo adoptarla en cuanto un proyecto supera la fase de prototipo y la lógica de negocio tiene un valor real que proteger.
En los proyectos que superviso, ya no es una opción estética. Es la condición para que desarrolladores senior, potenciados por Claude Code, sigan siendo más productivos y más fiables que un equipo con el doble de personal sin esa disciplina. Para la implementación práctica en el terreno offshore, he detallado el tema en nuestra guía completa sobre arquitectura hexagonal, y si buscas entender dónde la IA realmente sustituye a un desarrollador (y dónde no), este artículo completa directamente el argumento. En cuanto a la implementación con las propias herramientas de IA, el blog AI First cubre los casos de uso concretos en la empresa.
Preguntas frecuentes
¿Qué es la arquitectura hexagonal en una frase?
Es una forma de organizar el código que coloca la lógica de negocio en el centro y obliga a que todas las dependencias técnicas (base de datos, API, frameworks) pasen por interfaces definidas por ese centro, nunca al revés. El dominio solo se conoce a sí mismo y puede probarse sin ninguna infraestructura real.
¿Qué diferencia hay entre arquitectura hexagonal y Clean Architecture?
Ambas comparten el mismo principio de inversión de dependencias hacia el negocio. La Clean Architecture, popularizada por Robert C. Martin, añade capas concéntricas más explícitas y una terminología propia (entidades, casos de uso, adaptadores de interfaz). En la práctica, ambas se sustituyen fácilmente entre sí en un proyecto real.
¿La arquitectura hexagonal ralentiza el desarrollo cuando se usa IA?
Añade algo de código al principio, sobre todo las interfaces de los puertos. Pero una vez aislado el dominio, un asistente como Claude Code produce sugerencias más pertinentes porque trabaja dentro de un contrato claro, con menos ambigüedad sobre qué pertenece al negocio y qué pertenece a la infraestructura.
¿Hay que usar siempre una arquitectura hexagonal?
No. En un script desechable o un CRUD sin lógica de negocio real, la indirección añadida cuesta más de lo que aporta. Se justifica cuando el dominio tiene un valor que proteger a largo plazo, o cuando sabes que un componente técnico (base de datos, proveedor de pagos) cambiará algún día.
¿Cómo migrar un proyecto existente a una arquitectura hexagonal?
De forma progresiva, puerto a puerto, nunca reescribiendo todo de golpe. Se empieza aislando un caso de uso con alto valor de negocio, se define su puerto de entrada y de salida, se conecta el adaptador existente detrás de esa interfaz, y se repite con el siguiente componente sin tocar el resto del sistema.
Fuentes
- Hexagonal Architecture: What You Need To Know - Simple Explanation , Alex Hyett
- Learn Hexagonal Architecture in 10 minutes , CodelyTV - Redescubre la programación
- Arquitetura Hexagonal | Explicação de um Dev Sr. , Augusto Galego
- Hexagonal Architecture (Simplified Explanation of Ports & Adapters) // Programmer's Dictionary , Código Fonte TV
- Architecture Hexagonale : trois principes et un exemple d'implémentation , blog.octo.com
- Hexagonal vs Clean vs Onion Architecture , Which Is Truly the Most Solid? , r/softwarearchitecture
- Layered Architecture != Hexagonale, Onion and Clean Architecture , r/softwarearchitecture
- Looking for a pattern catalogue for app architecture , r/androiddev
