Communitygithub.com

xfoundries/software-architecture-skills

Conseil architectural sensible au contexte pour les systèmes métier utilisant la conception pilotée par le domaine (DDD), l'architecture en couches, l'architecture en oignon, l'architecture hexagonale / ports et adaptateurs, et CQRS.

Qu'est-ce que software-architecture-skills ?

Cette compétence fournit des conseils architecturaux automatisés pour les projets d'applications métier basés sur le framework JFoundry. Elle aide les développeurs à respecter les architectures cibles (hexagonale, oignon, en couches, CQRS) sans dévier de l'intention du framework. La compétence couvre la création de projets, la sélection de styles architecturaux, l'organisation des modules Maven, la génération de squelettes et l'ajout de tests ArchUnit. Elle est particulièrement utile pour les équipes utilisant DDD et souhaitant une séparation claire entre le domaine, l'application et l'infrastructure. Fonctionne avec Java 21, Maven, Spring Boot, MyBatis-Plus, et intègre des workflows pour l'Outbox/Inbox fiables.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Utiliser JFoundry

Objectif

Utilisez cette compétence pour construire des applications métier sur JFoundry sans dériver de l'architecture prévue par le framework. Elle est destinée aux projets applicatifs, et non à la modification des composants internes de JFoundry.

Par défaut, créez un nouveau projet Maven Java 21 avec architecture hexagonale, sauf si l'utilisateur choisit explicitement l'architecture en oignon. Ne définissez pas Spring Boot comme framework d'exécution par défaut ; choisissez Spring uniquement lorsque l'utilisateur sélectionne Spring Framework, Spring Boot ou un starter spécifique à Spring. Préférez copier d'abord les modèles fournis, puis adapter les noms et les packages.

Workflow de première utilisation

  1. Identifiez la forme du projet : module applicatif unique, application Maven multi-module, ou modules séparés domaine/application/infrastructure. Préférez le multi-module Maven pour les projets DDD classiques.
  2. Choisissez un style architectural principal. Préférez l'architecture hexagonale pour les nouveaux projets métier ; choisissez l'architecture en oignon uniquement lorsque l'utilisateur la demande ou que le code existant l'utilise déjà. Ne mélangez pas hexagonale et oignon dans la même portée d'analyse ArchUnit.
  3. Lisez references/dependencies.md, choisissez le BOM en fonction de l'exécution, et copiez les extraits de modèles Maven correspondants depuis assets/templates/maven/.
  4. Lisez references/architecture.md et copiez la structure de package correspondante depuis assets/templates/structure/.
  5. Copiez un modèle de test d'architecture depuis assets/templates/java/, remplacez PACKAGE_NAME, et ajoutez-le dans le répertoire de test du projet métier.
  6. Lisez references/repository-and-ports.md avant de créer des repositories d'agrégats, des ports de lecture, des ports de requête, des ports de consultation, des modèles de lecture ou des ports de maintenance.
  7. Lisez references/persistence-data-converters.md avant d'implémenter AggregateData, DataConverter, des objets de données MyBatis-Plus ou des convertisseurs MapStruct.
  8. Lisez references/outbox-inbox.md uniquement lorsque le projet nécessite une publication fiable d'événements externes ou une consommation de messages idempotente.
  9. Exécutez la commande de vérification Maven la plus pertinente, généralement mvn test, ou une commande limitée à un module comme mvn -pl <module> test.

Règles principales

  • Maintenez le code du domaine libre de Spring, MyBatis, modèles de persistance, clients de courtiers de messages et API de cycle de vie du framework.
  • Modélisez le comportement métier dans le domaine lorsque les règles et les invariants sont significatifs ; utilisez des scripts CRUD ou de transaction plus simples pour les zones de faible complexité.
  • Pour un comportement domaine non trivial, confirmez les hypothèses concernant l'agrégat, la commande, l'invariant, l'événement, le repository et le port de lecture avant de coder ; gardez les questions ouvertes sur le domaine visibles.
  • Placez les starters Spring Boot uniquement dans le module d'assemblage boot/exécution, jamais dans les modules domaine ou application.
  • Placez l'orchestration des cas d'utilisation et le workflow transactionnel dans la couche application.
  • Exprimez les besoins sortants comme des ports secondaires. Placez MyBatis, JPA, Redis, les clients HTTP, les clients MQ et autres détails technologiques dans les adaptateurs d'infrastructure.
  • Dans les projets JFoundry hexagonaux ou en oignon, les adaptateurs primaires (contrôleurs, écouteurs de messages, commandes CLI, planificateurs) doivent appeler des ports primaires ou des services d'application, pas directement les adaptateurs secondaires.
  • Utilisez les repositories d'agrégats pour le cycle de vie des agrégats et le chargement des agrégats côté commande. Pour les lectures non basées sur des agrégats, préférez les ports de lecture et répartissez-les en rôles lookup/read-model/maintenance uniquement lorsque cette distinction est utile au projet.
  • Gardez les convertisseurs de données de persistance locaux à l'infrastructure. Privilégiez les interfaces @Mapper MapStruct avec INSTANCE ; gardez toEntity(...) explicite et appelez restore(...) sur l'agrégat.
  • Activez l'Outbox uniquement pour une publication fiable vers un processus ou un courtier externe. Utilisez la distribution d'événements domaine locale lorsque les événements restent dans le même processus.
  • Activez l'Inbox uniquement lorsqu'un consommateur doit gérer les doublons de manière sécurisée.
  • Ajoutez les tests ArchUnit tôt. Ils font partie du squelette du projet, pas d'un nettoyage tardif.

Modèles fournis

Copiez les modèles plutôt que de les réécrire de mémoire :

  • 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

Remplacez les espaces réservés tels que PACKAGE_NAME et JFOUNDRY_VERSION. Gardez les extraits optionnels optionnels ; n'ajoutez pas les starters Outbox, Inbox, MyBatis-Plus ou courtier sauf si le cas d'utilisation le nécessite.

Acheminement des références

  • Lisez references/first-use.md lorsque l'utilisateur démarre un nouveau projet ou demande comment invoquer cette compétence.
  • Lisez references/architecture.md pour les rôles des packages, les annotations, la direction des dépendances et la sélection du style architectural.
  • Lisez references/dependencies.md pour la sélection des starters et les extraits Maven.
  • Lisez references/repository-and-ports.md avant de modéliser la persistance, les repositories d'agrégats, les modèles de lecture ou les ports de requête.
  • Lisez references/persistence-data-converters.md avant d'écrire des implémentations DataConverter, des objets de données de persistance ou des règles de correspondance MapStruct.
  • Lisez references/outbox-inbox.md avant d'ajouter l'externalisation d'événements, les adaptateurs de courtier, les tables Outbox, les répartiteurs ou l'idempotence des consommateurs.
  • Lisez references/testing.md avant d'ajouter ou de modifier des tests d'architecture.

Prompt initial courant

Lorsque vous guidez un nouveau projet, commencez par demander le package de base, la forme du projet/module, la pile d'exécution, le choix de persistance et si une messagerie externe est nécessaire. Si l'utilisateur n'a pas de préférence, poursuivez avec :

  • Java 21
  • Maven
  • aucun framework d'exécution pour l'instant
  • architecture hexagonale
  • BOM jfoundry-dependencies
  • starter jfoundry-domain-starter
  • starter jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() et JFoundryRules.jmoleculesDdd()

Exemple de saisie utilisateur pour un nouveau projet métier :

Utilisez $use-jfoundry pour créer l'architecture initiale d'un nouveau projet Java 21.
Package de base : com.example.order
Forme du projet : multi-module Maven
Exécution : non décidée
Persistance : MyBatis-Plus
Messagerie : Kafka plus tard, pas dans le squelette initial
Architecture : par défaut sauf si vous devez choisir

Si des détails manquent, posez une question concise ou suivez les valeurs par défaut ci-dessus lorsque le choix présente un faible risque.

Skills associés