$ ls ~/exeal/patterns

Patrones de ingeniería que usamos de verdad

Biblioteca de patrones de ingeniería de software de Exeal. Cada patrón cuenta el problema, la solución y en qué punto de madurez está.

  • 24 patrones
  • 19 tags
Madurez:
En prueba

Reglas de arquitectura como tests

Las reglas de arquitectura que solo viven en un documento se erosionan PR a PR, y un agente que trabaja dentro de una funcionalidad las rompe sin que nada falle, porque todo compila y los tests pasan. La solución escribe cada regla como un test que inspecciona el código compilado y devuelve la lista de violaciones, con su propio check en CI, un mensaje que dice cómo arreglarlo y unas excepciones que solo pueden encoger.

En prueba

Issue tracker como fuente única del estado del trabajo

El estado del trabajo (qué está hecho, qué se decidió, qué va primero) acaba repartido entre ficheros de los repos, una herramienta aparte y la cabeza de alguien, y ni las personas ni los agentes pueden fiarse de ninguna copia. La solución es llevarlo todo a un issue tracker con MCP y API, modelado para que cada pregunta habitual sea una consulta, y dejar en los repos solo el diseño, enlazado al issue que lleva su estado.

En prueba

Home repo y skills compartidas entre repos

En una empresa con varios repositorios, un agente lanzado dentro de uno no sabe nada de los demás ni del negocio, y las skills que necesitaría en todos acaban viviendo en uno solo. La solución es un home repo que los conoce a todos: guarda el conocimiento que no pertenece a ningún repo, enlaza al resto sin copiar sus hechos y publica las skills comunes como plugins que cada repo activa con el mismo bloque de configuración.

Explorando

Gestión del backlog con skills

Con agentes haciendo el trabajo, el backlog crece más deprisa de lo que una persona puede priorizar y refinar, y su criterio para decir «esto no merece la pena» solo existe en el chat. La solución es escribir ese criterio como una rúbrica con ejemplos y repartir triaje, refinamiento y redacción de issues en skills donde el agente investiga y propone, un script aplica, y la persona decide por lotes.

Adoptado

De iniciativa a slices ejecutables: PRD, tech spec y plan de slices

Una iniciativa grande entregada tal cual a un agente acaba en un PR enorme, con alcance que nadie pidió y decisiones de negocio tomadas sobre la marcha. La solución es bajarla por etapas, cada una con su documento y su puerta: un PRD que valida negocio, una tech spec que fija el diseño, un plan de slices verticales derivado de un modelo de complejidad, y cada slice convertida en un issue que un agente implementa en su worktree, test-first y con su propio PR.

Explorando

Baseline de calidad que solo encoge

En un repo con deuda, un límite estricto deja el CI en rojo desde el primer día y uno laxo deja crecer la deuda, y un agente que solo quiere el check en verde acaba ampliando la lista de excepciones en vez de arreglar el código. La solución congela la deuda de hoy en ficheros versionados, juzga cada PR contra la versión de su rama base y falla si algo empeora, de modo que la lista solo puede encoger y subirla queda en manos de una persona.

Adoptado

Tests de persistencia del repositorio real

Cuando la lógica de negocio se testea contra un repositorio fake en memoria, la implementación real (SQL, EF Core) puede quedar sin probar — queries que no traducen bien, constraints que el fake no reproduce. La solución es un puñado de tests que ejercitan esa implementación real contra un Postgres real con Testcontainers.

Adoptado

Tests de aceptación de frontend sobre una imagen Docker ya construida

Una suite de Playwright que arranca contra el código fuente o `vite dev` no ejercita el Dockerfile, nginx ni el entrypoint que inyecta configuración en tiempo de arranque — todo eso puede romperse solo en la imagen empaquetada. La solución corre Playwright contra la imagen Docker del frontend ya construida y el mecanismo api-lite como backend, verificando el artefacto que de verdad se despliega.

Adoptado

Tests de aceptación de backend sobre una imagen Docker ya construida

Un backend se despliega como imagen Docker, pero los tests contra el código fuente nunca ejercitan el Dockerfile, las variables de entorno del contenedor ni si las migraciones corren al arrancar. La solución es un proyecto de tests separado, sin dependencia de código fuente, que levanta esa imagen ya construida junto a sus dependencias reales con Testcontainers y la estimula solo por sus interfaces públicas.

Adoptado

Snapshot de contrato OpenAPI aceptado explícitamente

Un contrato OpenAPI generado del código nadie lo escribe ni lo revisa a propósito, así que un refactor puede cambiarlo como efecto secundario sin que nadie se entere hasta que se rompe en producción. La solución versiona ese contrato como snapshot aprobado, lo compara en un test automatizado, y solo un comando explícito puede actualizarlo tras revisión.

Adoptado

Skill Verify: verificación basada en riesgo

Un agente que da una tarea por terminada en cuanto el diff "tiene buena pinta" puede dejar pasar bugs reales o, al contrario, sobre-verificar corriendo infraestructura innecesaria. La solución convierte la verificación en una decisión basada en una matriz de riesgo, con un script de comandos deterministas y una skill que elige la evidencia mínima necesaria.

Adoptado

Skill Run: entorno local determinista para un agente

Un agente que levanta un proyecto en local redescubre cada vez qué variables necesita, en qué orden arrancar y qué superficie hace falta, y suele levantar de más o de menos. La solución separa un script determinista con modos explícitos de una skill que le dice al agente cuándo usar cada modo.

Adoptado

One build, many deploys para imágenes de frontend

Un frontend Vite plancha sus variables de entorno en el bundle durante el build, obligando a construir una imagen distinta por cada entorno. La solución inyecta esas variables en el arranque del contenedor con envsubst, para que una sola imagen construida sirva a todos los entornos.

Adoptado

Monorepo multi-app con pipeline independiente por app

Cuando frontend, backend y admin viven en repos separados, cualquier cambio que cruce esa frontera exige coordinar varios PRs y decidir el orden de merge y de deploy entre repos. La solución empaqueta todas las apps del producto en un único repositorio, con un pipeline independiente por app gateado por un glob de rutas.

En prueba

Host fino y módulos deep

Sin fronteras reales entre piezas, cualquier clase puede depender de cualquier otra, lo que impide testear en aislamiento y obliga a cargar contexto de todo el sistema para tocar una sola funcionalidad. La solución construye la app como un host casi vacío que enchufa módulos con una interfaz narrow pública y una implementación deep interna al ensamblado.

Adoptado

Gestión de errores explícita con un Result tipado

Usar excepciones tanto para denegaciones de negocio esperadas como para fallos técnicos de infraestructura mezcla ambos casos en el mismo mecanismo y deja que cada controlador invente su propio mapeo a HTTP. La solución es un tipo Result<T>/ApplicationError que representa los fracasos esperados como valores de retorno, con un único punto que los mapea a su respuesta HTTP.

Adoptado

Fake OIDC: proveedor de autenticación de mentira

Levantar en local o en tests una API que exige OIDC real obliga a gestionar credenciales de un proveedor externo, o lleva a saltarse la autenticación y dejar de ejercitar el pipeline real. La solución es un proveedor OIDC de mentira que habla el subconjunto real del protocolo, para login determinista tanto en desarrollo como en tests de aceptación.

Explorando

DSM Snapshot: matriz de dependencias entre módulos versionada

En una arquitectura modular sin fronteras forzadas por el compilador, un import de conveniencia puede cruzar una frontera prohibida o crear un ciclo sin que nadie lo note hasta meses después. La solución versiona la matriz de dependencias entre módulos como snapshot aprobado y la compara en cada build, exigiendo revisión consciente ante cualquier cambio.

Adoptado

Comandos de mantenimiento en apps .NET

Las tareas de mantenimiento puntuales (backfills, purgas, recálculos) suelen acabar como SQL suelto que salta las invariantes de dominio, o como un programa aparte que diverge con el tiempo de la configuración real. La solución son comandos descubiertos por reflection que reutilizan el mismo bootstrap de DI/config que la app real, sin levantar HTTP.

Explorando

CLI de seed de escenarios de prueba contra base de datos local

Llegar a mano a un estado de negocio concreto (un pedido rechazado por scoring, una verificación fallida) exige arrastrar el flujo real por integraciones externas lentas o que no se pueden disparar a demanda en local. La solución es un CLI aparte que borra y repuebla Postgres local con un catálogo fijo de escenarios, dejando el sistema en un estado conocido y reproducible.

Adoptado

CLAUDE.md como mapa de contexto para el agente

Un CLAUDE.md que vuelca arquitectura, reglas de negocio y contrato de API crece sin límite y se desincroniza, porque nada obliga a actualizarlo en el mismo commit que invalida su contenido. La solución es un CLAUDE.md corto que apunta a la documentación real y dice cuándo leer cada documento, sin explicarla.

En prueba

Arquitectura hexagonal (puertos y adaptadores) en .NET

Cuando el dominio llama directamente a la base de datos o al framework web, los casos de uso dejan de ser testeables sin infraestructura real y la frontera arquitectónica se erosiona sin que el compilador lo note. La solución aísla el core en un proyecto sin dependencias de infraestructura, exponiendo puertos primarios y secundarios que implementan proyectos separados.

Adoptado

Arquitectura en capas para frontend React

En una SPA React sin fronteras internas, la lógica de negocio, el estado y el JSX se mezclan en el mismo componente, encareciendo los tests y acoplando negocio a UI. La solución separa cuatro capas — API, store, casos de uso y componentes presentacionales — cada una testeable con la herramienta más barata que le sirve.

Adoptado

API Lite: un segundo host con infraestructura en memoria

Un frontend o una suite de Playwright que depende del backend real arrastra Postgres, colas y proveedores externos, haciendo el desarrollo lento y los tests no deterministas. API Lite es un segundo host de la misma API con toda la infraestructura sustituida por implementaciones en memoria, para desarrollo y tests deterministas.