Communitygithub.com

xfoundries/software-architecture-skills

Guía de arquitectura basada en el dominio para sistemas empresariales, empleando Diseño Guiado por el Dominio (DDD), Arquitectura en Capas, Arquitectura Cebolla, Hexagonal / Puertos y Adaptadores, y CQRS.

¿Qué es software-architecture-skills?

Esta skill proporciona una guía arquitectónica sensible al contexto para construir sistemas empresariales utilizando jfoundry, asegurando que los proyectos se mantengan alineados con la arquitectura prevista del framework. Soporta múltiples estilos arquitectónicos, incluyendo Hexagonal, Cebolla (Onion), en Capas, y CQRS, y está diseñada para proyectos de aplicación, no para modificar el núcleo interno del framework. La skill se enfoca en proyectos Java 21 con Maven como gestor de dependencias predeterminado, prefiriendo la arquitectura Hexagonal a menos que el usuario solicite explícitamente Cebolla. Proporciona una serie de pasos detallados para el flujo de trabajo inicial, plantillas empaquetadas para pruebas de arquitectura, gestión de dependencias y estructuras de paquetes, así como referencias detalladas para modelar persistencia, puertos, adaptadores, y patrones como Outbox e Inbox. Al utilizar esta skill, los desarrolladores mantienen el código del dominio libre de detalles de infraestructura, y las decisiones arquitectónicas son validadas tempranamente mediante pruebas ArchUnit.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add xfoundries/software-architecture-skills

Preguntar en tu IA favorita

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

Documentación

Usar JFoundry

Propósito

Utilice esta skill para construir aplicaciones empresariales sobre jfoundry sin desviarse de la arquitectura prevista del framework. Está destinada a proyectos de aplicación, no a modificar el núcleo interno de jfoundry.

Por defecto, cree un nuevo proyecto Maven con Java 21 utilizando Arquitectura Hexagonal, a menos que el usuario elija explícitamente Cebolla (Onion). No establezca Spring Boot como framework de ejecución por defecto; elija Spring solo cuando el usuario seleccione Spring Framework, Spring Boot o un starter específico de Spring. Prefiera copiar primero las plantillas empaquetadas y luego adaptar nombres y paquetes.

Flujo de Trabajo Inicial

  1. Identifique la forma del proyecto: módulo de aplicación único, aplicación Maven multi-módulo, o módulos separados de dominio/aplicación/infraestructura. Prefiera Maven multi-módulo para proyectos DDD normales.
  2. Elija un estilo arquitectónico principal. Prefiera Hexagonal para nuevos proyectos empresariales; elija Cebolla solo cuando el usuario lo solicite o el código base ya lo utilice. No mezcle Hexagonal y Cebolla en el mismo ámbito de análisis de ArchUnit.
  3. Lea references/dependencies.md, elija el BOM según el runtime y copie los fragmentos de plantilla Maven correspondientes desde assets/templates/maven/.
  4. Lea references/architecture.md y copie la estructura de paquetes coincidente desde assets/templates/structure/.
  5. Copie una plantilla de prueba de arquitectura desde assets/templates/java/, reemplace PACKAGE_NAME y agréguela bajo el conjunto de fuentes de prueba del proyecto empresarial.
  6. Lea references/repository-and-ports.md antes de crear repositorios de agregados, puertos del lado de lectura, puertos de consulta, puertos de búsqueda, modelos de lectura o puertos de mantenimiento.
  7. Lea references/persistence-data-converters.md antes de implementar AggregateData, DataConverter, objetos de datos de MyBatis-Plus o convertidores de MapStruct.
  8. Lea references/outbox-inbox.md solo cuando el proyecto necesite publicación confiable de eventos externos o consumo de mensajes idempotente.
  9. Ejecute el comando de verificación Maven más pequeño relevante, normalmente mvn test, o un comando con ámbito de módulo mvn -pl <module> test.

Reglas Fundamentales

  • Mantenga el código del dominio libre de Spring, MyBatis, modelos de persistencia, clientes de intermediarios de mensajes y las APIs del ciclo de vida del framework.
  • Modele el comportamiento empresarial en el dominio cuando las reglas e invariantes sean significativas; use CRUD más simple o scripts de transacción para áreas de baja complejidad.
  • Para comportamiento de dominio no trivial, confirme las suposiciones sobre agregados, comandos, invariantes, eventos, repositorios y puertos del lado de lectura antes de codificar; mantenga visibles las preguntas abiertas del dominio.
  • Coloque los starters de Spring Boot solo en el módulo de ensamblaje boot/runtime, nunca en los módulos de dominio o aplicación.
  • Coloque la orquestación de casos de uso y el flujo de trabajo transaccional en la capa de aplicación.
  • Exprese las necesidades salientes como puertos secundarios. Coloque MyBatis, JPA, Redis, clientes HTTP, clientes MQ y otros detalles de tecnología en los adaptadores de infraestructura.
  • En proyectos Hexagonal o Cebolla de jfoundry, los adaptadores primarios, como controladores, oyentes de mensajes, comandos CLI y programadores, deben llamar a puertos primarios o servicios de aplicación, no directamente a adaptadores secundarios.
  • Use repositorios de agregados para el ciclo de vida del agregado y la carga de agregados del lado de comandos. Para lecturas que no son de agregados, prefiera puertos del lado de lectura y divídalos en roles de búsqueda/modelo de lectura/mantenimiento solo cuando esa distinción ayude al proyecto.
  • Mantenga los convertidores de datos de persistencia local a la infraestructura. Prefiera interfaces @Mapper de MapStruct con INSTANCE; mantenga explícito toEntity(...) y llame a restore(...) del agregado.
  • Habilite Outbox solo para publicación confiable a un proceso externo o intermediario. Use el envío de eventos de dominio local cuando los eventos permanezcan dentro del proceso.
  • Habilite Inbox solo cuando un consumidor deba manejar de manera segura la entrega duplicada.
  • Agregue pruebas ArchUnit temprano. Son parte del esqueleto del proyecto, no una limpieza tardía.

Plantillas Empaquetadas

Copie las plantillas en lugar de reescribirlas de memoria:

  • assets/templates/java/HexagonalArchitectureTest.java
  • assets/templates/java/OnionSimpleArchitectureTest.java
  • assets/templates/maven/dependency-management-core.xml
  • assets/templates/maven/dependency-management-spring.xml
  • assets/templates/maven/domain-module-dependencies.xml
  • assets/templates/maven/application-module-dependencies.xml
  • assets/templates/maven/infrastructure-mybatis-plus-dependencies.xml
  • assets/templates/maven/architecture-test-dependencies.xml
  • assets/templates/maven/spring-boot-app-dependencies.xml
  • assets/templates/maven/spring-boot-mybatis-plus-dependencies.xml
  • assets/templates/maven/outbox-dependencies.xml
  • assets/templates/maven/outbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/inbox-dependencies.xml
  • assets/templates/maven/inbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/broker-dependencies.xml
  • assets/templates/structure/hexagonal-package-structure.txt
  • assets/templates/structure/onion-simple-package-structure.txt

Reemplace marcadores de posición como PACKAGE_NAME y JFOUNDRY_VERSION. Mantenga los fragmentos opcionales como opcionales; no agregue starters de Outbox, Inbox, MyBatis-Plus o intermediarios a menos que el caso de uso los necesite.

Enrutamiento de Referencias

  • Lea references/first-use.md cuando el usuario esté iniciando un nuevo proyecto o pregunte cómo invocar esta skill.
  • Lea references/architecture.md para conocer los roles de los paquetes, anotaciones, dirección de dependencias y selección del estilo arquitectónico.
  • Lea references/dependencies.md para la selección de starters y fragmentos Maven.
  • Lea references/repository-and-ports.md antes de modelar persistencia, repositorios de agregados, modelos de lectura o puertos de consulta.
  • Lea references/persistence-data-converters.md antes de escribir implementaciones de DataConverter, objetos de datos de persistencia o reglas de mapeo de MapStruct.
  • Lea references/outbox-inbox.md antes de agregar externalización de eventos, adaptadores de intermediarios, tablas Outbox, despachadores o idempotencia de consumidores.
  • Lea references/testing.md antes de agregar o cambiar pruebas de arquitectura.

Prompt Inicial Común

Al guiar un nuevo proyecto, comience preguntando por el paquete base, la forma del proyecto/módulo, la pila de runtime, la elección de persistencia y si se requiere mensajería externa. Si el usuario no tiene preferencia, proceda con:

  • Java 21
  • Maven
  • sin framework de runtime aún
  • Arquitectura Hexagonal
  • BOM jfoundry-dependencies
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() y JFoundryRules.jmoleculesDdd()

Prompt sugerido para un nuevo proyecto empresarial:

Use $use-jfoundry para crear la arquitectura inicial de un nuevo proyecto empresarial Java 21.
Paquete base: com.example.order
Forma del proyecto: Maven multi-módulo
Runtime: sin decidir
Persistencia: MyBatis-Plus
Mensajería: Kafka más adelante, no en el esqueleto inicial
Arquitectura: predeterminada a menos que necesite elegir

Si faltan detalles, haga una pregunta concisa o proceda con los valores predeterminados anteriores cuando la elección sea de bajo riesgo.

Skills relacionados