Communitygithub.com

xfoundries/software-architecture-skills

Quellenbewusste Architekturanleitung für geschäftsdomänenbasierte Systeme unter Verwendung von Domain-Driven Design, Layered Architecture, Onion Architecture, Hexagonal Architecture / Ports and Adapters und CQRS.

Was ist software-architecture-skills?

Diese Skill hilft Entwicklern, Geschäftsanwendungen mit dem jfoundry-Framework architekturkonform zu erstellen. Sie vermeidet Abweichungen von der vorgesehenen Architektur, indem sie klare Regeln und bewährte Vorlagen bereitstellt. Standardmäßig wird eine neue Java 21 Maven-Anwendung mit Hexagonaler Architektur erstellt, es sei denn, der Benutzer wählt explizit eine andere Architektur (z. B. Onion). Der Skill unterstützt Entwickler durch einen detaillierten Arbeitsablauf, der die Projektform, die Auswahl des Architekturstils, die Verwendung von ArchUnit-Tests und das Befolgen von Referenzdokumenten für Persistenz, Outbox/Inbox und Repository-Ports umfasst. Er ist für die Verwendung mit Claude Code, Cursor und anderen KI-gestützten Entwicklungstools optimiert und enthält gebündelte Vorlagen für Maven-Abhängigkeiten, Paketstrukturen und Architekturtests. Die Kernregeln betonen die Trennung von Domänencode von Framework- und Infrastrukturdetails, die Implementierung von Geschäftsverhalten in der Domäne und die Verwendung von ArchUnit-Tests als integralen Bestandteil des Projektskeletts.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add xfoundries/software-architecture-skills

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

jfoundry verwenden

Zweck

Verwenden Sie diesen Skill, um Geschäftsanwendungen auf jfoundry zu erstellen, ohne von der vorgesehenen Architektur des Frameworks abzuweichen. Er ist für Anwendungsprojekte gedacht, nicht für Änderungen an den jfoundry-Framework-Interna.

Standardmäßig ein neues Java 21 Maven-Projekt mit Hexagonaler Architektur erstellen, es sei denn, der Benutzer wählt explizit Onion. Nicht standardmäßig das Laufzeit-Framework auf Spring Boot setzen; wählen Sie Spring nur, wenn der Benutzer Spring Framework, Spring Boot oder einen Spring-spezifischen Starter auswählt. Bevorzugen Sie das Kopieren der gebündelten Vorlagen, dann Anpassen von Namen und Paketen.

Erstmaliger Workflow

  1. Identifizieren Sie die Projektform: einzelnes Anwendungsmodul, Multi-Modul-Maven-App oder separate Domain-/Anwendungs-/Infrastrukturmodule. Bevorzugen Sie Multi-Modul-Maven für normale DDD-Projekte.
  2. Wählen Sie einen primären Architekturstil. Bevorzugen Sie hexagonal für neue Geschäftsprojekte; wählen Sie Onion nur, wenn der Benutzer danach fragt oder die Codebasis es bereits verwendet. Mischen Sie nicht Hexagonal und Onion im gleichen ArchUnit-Analysebereich.
  3. Lesen Sie references/dependencies.md, wählen Sie die BOM nach Laufzeit aus und kopieren Sie die passenden Maven-Vorlagenausschnitte aus assets/templates/maven/.
  4. Lesen Sie references/architecture.md und kopieren Sie die passende Paketstruktur aus assets/templates/structure/.
  5. Kopieren Sie eine Architekturtestvorlage aus assets/templates/java/, ersetzen Sie PACKAGE_NAME und fügen Sie sie unter dem Testquellsatz des Geschäftsprojekts hinzu.
  6. Lesen Sie references/repository-and-ports.md, bevor Sie Aggregat-Repositories, Read-Side-Ports, Query-Ports, Lookup-Ports, Read-Modelle oder Wartungsports erstellen.
  7. Lesen Sie references/persistence-data-converters.md, bevor Sie AggregateData, DataConverter, MyBatis-Plus-Datenobjekte oder MapStruct-Konverter implementieren.
  8. Lesen Sie references/outbox-inbox.md nur, wenn das Projekt eine zuverlässige Veröffentlichung externer Ereignisse oder idempotenten Nachrichtenempfang benötigt.
  9. Führen Sie den kleinsten relevanten Maven-Verifikationsbefehl aus, normalerweise mvn test oder einen modulbezogenen mvn -pl <Modul> test.

Kernregeln

  • Halten Sie den Domänencode frei von Spring, MyBatis, Persistenzmodellen, Message-Broker-Clients und Framework-Lebenszyklus-APIs.
  • Modellieren Sie Geschäftsverhalten in der Domäne, wenn Regeln und Invarianten sinnvoll sind; verwenden Sie einfachere CRUD- oder Transaktionsskripte für Bereiche mit geringer Komplexität.
  • Bestätigen Sie bei nicht-trivialem Domänenverhalten Annahmen zu Aggregat, Befehl, Invariante, Ereignis, Repository und Read-Side-Port vor der Codierung; halten Sie offene Domänenfragen sichtbar.
  • Platzieren Sie Spring Boot-Starter nur im Boot/Laufzeit-Assembly-Modul, niemals in Domänen- oder Anwendungsmodulen.
  • Platzieren Sie Use-Case-Orchestrierung und transaktionsorientierte Workflows in der Anwendungsschicht.
  • Drücken Sie ausgehende Anforderungen als sekundäre Ports aus. Platzieren Sie MyBatis, JPA, Redis, HTTP-Clients, MQ-Clients und andere Technologiedetails in Infrastrukturadaptern.
  • In jfoundry-Hexagonal- oder -Onion-Projekten müssen primäre Adapter wie Controller, Nachrichten-Listener, CLI-Befehle und Scheduler primäre Ports oder Anwendungsdienste aufrufen, nicht sekundäre Adapter direkt.
  • Verwenden Sie Aggregat-Repositories für den Aggregat-Lebenszyklus und das Laden von Befehlsseiten-Aggregaten. Für Nicht-Aggregat-Lesevorgänge bevorzugen Sie Read-Side-Ports und teilen Sie diese nur in Lookup-/Read-Modell-/Wartungsrollen auf, wenn diese Unterscheidung dem Projekt hilft.
  • Halten Sie Persistenzdaten-Konverter infrastrukturlokal. Bevorzugen Sie MapStruct @Mapper-Schnittstellen mit INSTANCE; halten Sie toEntity(...) explizit und rufen Sie Aggregat restore(...) auf.
  • Aktivieren Sie Outbox nur für zuverlässige Veröffentlichung an einen externen Prozess oder Broker. Verwenden Sie lokalen Domänenereignisversand, wenn Ereignisse prozessintern bleiben.
  • Aktivieren Sie Inbox nur, wenn ein Consumer doppelte Zustellung sicher verarbeiten muss.
  • Fügen Sie ArchUnit-Tests früh hinzu. Sie sind Teil des Projektskeletts, keine späte Bereinigung.

Gebündelte Vorlagen

Kopieren Sie Vorlagen, anstatt sie aus dem Gedächtnis neu zu schreiben:

  • 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

Ersetzen Sie Platzhalter wie PACKAGE_NAME und JFOUNDRY_VERSION. Behalten Sie optionale Ausschnitte optional bei; fügen Sie Outbox-, Inbox-, MyBatis-Plus- oder Broker-Starter nur hinzu, wenn der Anwendungsfall sie benötigt.

Referenz-Routing

  • Lesen Sie references/first-use.md, wenn der Benutzer ein neues Projekt startet oder fragt, wie dieser Skill aufgerufen wird.
  • Lesen Sie references/architecture.md für Paketrollen, Annotationen, Abhängigkeitsrichtung und Auswahl des Architekturstils.
  • Lesen Sie references/dependencies.md für Starter-Auswahl und Maven-Ausschnitte.
  • Lesen Sie references/repository-and-ports.md, bevor Sie Persistenz, Aggregat-Repositories, Read-Modelle oder Query-Ports modellieren.
  • Lesen Sie references/persistence-data-converters.md, bevor Sie DataConverter-Implementierungen, Persistenzdatenobjekte oder MapStruct-Mapping-Regeln schreiben.
  • Lesen Sie references/outbox-inbox.md, bevor Sie Ereignisexternalisierung, Broker-Adapter, Outbox-Tabellen, Dispatcher oder Consumer-Idempotenz hinzufügen.
  • Lesen Sie references/testing.md, bevor Sie Architekturtests hinzufügen oder ändern.

Häufiger erster Prompt

Wenn Sie ein neues Projekt anleiten, fragen Sie zuerst nach dem Basispaket, der Projekt-/Modulform, dem Laufzeit-Stack, der Persistenzauswahl und ob externe Nachrichtenübermittlung erforderlich ist. Wenn der Benutzer keine Präferenz hat, fahren Sie fort mit:

  • Java 21
  • Maven
  • noch keine Laufzeit-Framework-Bindung
  • Hexagonale Architektur
  • jfoundry-dependencies BOM
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() und JFoundryRules.jmoleculesDdd()

Vorgeschlagener Benutzerprompt für ein neues Geschäftsprojekt:

Verwende $use-jfoundry, um die anfängliche Architektur für ein neues Java 21-Geschäftsprojekt zu erstellen.
Basispaket: com.example.order
Projektform: Multi-Modul-Maven
Laufzeit: unentschieden
Persistenz: MyBatis-Plus
Nachrichtenübermittlung: Kafka später, nicht im anfänglichen Skelett
Architektur: Standard, es sei denn, Sie müssen wählen

Wenn Details fehlen, stellen Sie eine präzise Frage oder fahren Sie mit den obigen Standardwerten fort, wenn die Wahl ein geringes Risiko darstellt.

Verwandte Skills