Communitygithub.com

xfoundries/software-architecture-skills

ドメイン駆動設計、レイヤードアーキテクチャ、オニオンアーキテクチャ、ヘキサゴナルアーキテクチャ(ポートとアダプター)、CQRSに基づいた、ソース認識型のビジネスドメインシステム向けアーキテクチャガイダンスを提供します。

software-architecture-skills とは?

このスキルは、jfoundryフレームワーク上でビジネスアプリケーションを構築する際に、フレームワークが想定するアーキテクチャから逸脱しないように開発を支援するものです。主にJava 21とMavenプロジェクトを対象としており、特に断りがない限りヘキサゴナルアーキテクチャをデフォルトとします。Spring Bootはユーザーが明示的に選択した場合のみ使用します。このスキルは、プロジェクトの形状(単一モジュール、マルチモジュール、またはドメイン/アプリケーション/インフラストラクチャ別モジュール)を識別し、バンドルされたテンプレートから適切なMaven依存関係、パッケージ構造、アーキテクチャテストをコピーするためのステップバイステップのワークフローを提供します。さらに、ArchUnitテストを早期に導入し、集約リポジトリや永続化データコンバータの設計に関する詳細なリファレンス資料を参照するよう推奨します。このスキルは、Claude Codeやそれに類似したAIエージェント向けに設計されており、ユーザーは自然言語でプロジェクトの初期アーキテクチャとコード生成を依頼できます。

対応~Claude Code~Codex CLI~Cursor
npx skills add xfoundries/software-architecture-skills

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

JFoundryを使用する

目的

このスキルを使用して、jfoundry上でビジネスアプリケーションを構築し、フレームワークが意図するアーキテクチャから逸脱しないようにします。これはアプリケーションプロジェクト用であり、jfoundryフレームワーク内部を変更するためではありません。

ユーザーが明示的にオニオンを選択しない限り、ヘキサゴナルアーキテクチャを使用した新しいJava 21 Mavenプロジェクトをデフォルトとします。ランタイムフレームワークをSpring Bootにデフォルト設定しないでください。ユーザーがSpring Framework、Spring Boot、またはSpring固有のスターターを選択した場合のみSpringを選択します。バンドルされたテンプレートを最初にコピーし、その後名前とパッケージを適応させることを推奨します。

初回ワークフロー

  1. プロジェクトの形状を特定します: 単一アプリケーションモジュール、マルチモジュールMavenアプリ、またはドメイン/アプリケーション/インフラストラクチャモジュールの分離。通常のDDDプロジェクトではマルチモジュールMavenを推奨します。
  2. 1つの主要なアーキテクチャスタイルを選択します。新しいビジネスプロジェクトにはヘキサゴナルを推奨します。ユーザーから要求された場合、またはコードベースですでに使用されている場合にのみオニオンを選択します。同じArchUnit分析スコープ内でヘキサゴナルとオニオンを混在させないでください。
  3. references/dependencies.mdを読み、ランタイムに応じてBOMを選択し、assets/templates/maven/から対応するMavenテンプレートスニペットをコピーします。
  4. references/architecture.mdを読み、assets/templates/structure/から対応するパッケージ構造をコピーします。
  5. assets/templates/java/から1つのアーキテクチャテストテンプレートをコピーし、PACKAGE_NAMEを置き換えて、ビジネスプロジェクトのテストソースセットに追加します。
  6. 集約リポジトリ、リードサイドポート、クエリポート、ルックアップポート、リードモデル、またはメンテナンスポートを作成する前に、references/repository-and-ports.mdを読んでください。
  7. AggregateData、DataConverter、MyBatis-Plusデータオブジェクト、またはMapStructコンバーターを実装する前に、references/persistence-data-converters.mdを読んでください。
  8. 信頼性の高い外部イベント公開またはべき等なメッセージ消費がプロジェクトに必要な場合にのみ、references/outbox-inbox.mdを読んでください。
  9. 最も小さい関連するMaven検証コマンド(通常はmvn test、またはモジュールスコープのmvn -pl <module> test)を実行します。

コアルール

  • ドメインコードは、Spring、MyBatis、永続化モデル、メッセージブローカークライアント、フレームワークライフサイクルAPIに依存しないようにします。
  • ルールと不変条件が意味を持つ場合はドメインでビジネス動作をモデル化します。複雑性の低い領域では、より単純なCRUDまたはトランザクションスクリプトを使用します。
  • 重要なドメイン動作については、コーディング前に集約、コマンド、不変条件、イベント、リポジトリ、リードサイドポートの仮定を確認し、未解決のドメイン質問を可視化したままにします。
  • Spring Bootスターターは、boot/runtimeアセンブリモジュールにのみ配置し、ドメインやアプリケーションモジュールには決して配置しないでください。
  • ユースケースのオーケストレーションとトランザクション向けワークフローはアプリケーション層に配置します。
  • 送信依存関係はセカンダリポートとして表現します。MyBatis、JPA、Redis、HTTPクライアント、MQクライアント、その他の技術的詳細はインフラストラクチャアダプターに配置します。
  • jfoundryのヘキサゴナルまたはオニオンプロジェクトでは、コントローラー、メッセージリスナー、CLIコマンド、スケジューラーなどのプライマリアダプターは、プライマリポートまたはアプリケーションサービスを呼び出さなければならず、セカンダリアダプターを直接呼び出してはいけません。
  • 集約リポジトリは、集約のライフサイクルとコマンドサイドの集約読み込みに使用します。非集約読み込みには、リードサイドポートを推奨し、その区別がプロジェクトに役立つ場合にのみ、ルックアップ/リードモデル/メンテナンスロールに分割します。
  • 永続化データコンバーターはインフラストラクチャローカルに保ちます。MapStructの@MapperインターフェースとINSTANCEを推奨します。toEntity(...)を明示的にし、集約のrestore(...)を呼び出します。
  • Outboxは、外部プロセスまたはブローカーへの信頼性の高い公開にのみ有効にします。イベントがプロセス内に留まる場合は、ローカルドメインイベントディスパッチを使用します。
  • Inboxは、コンシューマーが重複配信を安全に処理する必要がある場合にのみ有効にします。
  • ArchUnitテストは早期に追加します。これらはプロジェクトの骨格の一部であり、後からのクリーンアップではありません。

バンドルテンプレート

テンプレートは記憶から書き換えるのではなく、コピーします:

  • 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

PACKAGE_NAMEやJFOUNDRY_VERSIONなどのプレースホルダーを置き換えます。オプションのスニペットはオプションのままにします。ユースケースで必要でない限り、Outbox、Inbox、MyBatis-Plus、またはブローカースターターを追加しないでください。

リファレンスルーティング

  • ユーザーが新しいプロジェクトを開始する場合、またはこのスキルの呼び出し方法を尋ねられた場合は、references/first-use.mdを読んでください。
  • パッケージの役割、アノテーション、依存関係の方向、アーキテクチャスタイルの選択については、references/architecture.mdを読んでください。
  • スターターの選択とMavenスニペットについては、references/dependencies.mdを読んでください。
  • 永続化、集約リポジトリ、リードモデル、クエリポートをモデル化する前に、references/repository-and-ports.mdを読んでください。
  • DataConverterの実装、永続化データオブジェクト、MapStructマッピングルールを記述する前に、references/persistence-data-converters.mdを読んでください。
  • イベント外部化、ブローカーアダプター、Outboxテーブル、ディスパッチャー、コンシューマーのべき等性を追加する前に、references/outbox-inbox.mdを読んでください。
  • アーキテクチャテストを追加または変更する前に、references/testing.mdを読んでください。

よくある最初のプロンプト

新しいプロジェクトをガイドする際は、まずベースパッケージ、プロジェクト/モジュールの形状、ランタイムスタック、永続化の選択、および外部メッセージングが必要かどうかを尋ねます。ユーザーに好みがない場合は、以下をデフォルトとして進めます:

  • Java 21
  • Maven
  • まだランタイムフレームワークをバインドしない
  • ヘキサゴナルアーキテクチャ
  • jfoundry-dependencies BOM
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() および JFoundryRules.jmoleculesDdd()

新しいビジネスプロジェクト向けの推奨ユーザープロンプト:

$use-jfoundryを使用して、新しいJava 21ビジネスプロジェクトの初期アーキテクチャを作成してください。
ベースパッケージ: com.example.order
プロジェクト形状: マルチモジュールMaven
ランタイム: 未定
永続化: MyBatis-Plus
メッセージング: Kafkaは後で、初期スケルトンには含めない
アーキテクチャ: 選択が必要でなければデフォルト

詳細が不足している場合は、簡潔な質問を1つするか、選択リスクが低い場合は上記のデフォルトで進めてください。

関連スキル