modular-monolith-architecture

モジュラーモノリスアーキテクチャ — プロジェクトスキャフォルダー

適切なモジュール境界、内部 API、共有カーネル、インフラストラクチャを備え、業界のベストプラクティスに沿った本番環境対応のモジュラーモノリスプロジェクトを生成します。

概要

モジュラーモノリスとは、疎結合で凝集度の高いモジュール（それぞれが境界づけられたコンテキストを表します）で構成された、単一のデプロイ可能なアプリケーションです。モノリスのシンプルさ（単一のデプロイ、ACID トランザクション、プロセス内呼び出し）と、マイクロサービス形式のモジュール性（明確な境界、チームの自律性、独立した開発）を兼ね備えています。

このスキルでは、次の要素を備えた完全なプロジェクトをスキャフォールディングします。

• モジュールの分離：各モジュールが独自のドメイン、データアクセス、API サーフェスを所有します
• モジュール間通信：内部の詳細ではなく、公開されたコントラクト／インターフェースを介して行います
• 共有カーネル：横断的関心事（認証、ロギング、イベント）を共有レイヤーに配置します
• モジュールごとのデータベーススキーマ：単一の RDBMS 内で論理的に分離します
• 移行に対応した境界：後からモジュールをマイクロサービスとして切り出せます

ワークフロー

ステップ 1：要件の収集

ユーザーが指定していない場合は、次の項目を尋ねます。

1. 言語／フレームワーク（例：C#/ASP.NET Core、Java/Spring Boot、TypeScript/NestJS、Python/Django、Go）
2. プロジェクト名
3. ビジネスモジュール（例：Product、Order、Payment、Shipping、Notification）
4. データベースの希望（PostgreSQL、MySQL、SQL Server、開発用の SQLite）
5. 追加機能：イベントバス、API ゲートウェイ、Docker、CI/CD

ユーザーが $ARGUMENTS を指定した場合は、次のように解析します。$ARGUMENTS[0] = 言語／フレームワーク、$ARGUMENTS[1] = プロジェクト名、残り = モジュール名。

ステップ 2：プロジェクト構成の生成

選択したフレームワークのアーキテクチャリファレンスを確認します。

• 詳細な構成パターンについては、references/project-structures.md を参照してください
• モジュール設計パターンについては、references/module-design.md を参照してください
• 比較と選択ガイドについては、references/architecture-guide.md を参照してください
• イベント駆動パターンとイベントバスの設計については、references/event-driven-patterns.md を参照してください
• モジュール間通信とコントラクトのバージョニングについては、references/api-versioning-communication.md を参照してください
• 具体的なスキャフォールド例については、examples/dotnet-scaffold.md および examples/nestjs-scaffold.md を参照してください

次の重要なルールに従ってプロジェクトを生成します。

モジュールのルール

1. 各モジュールに、内部レイヤー（Domain/Application/Infrastructure/API）を含む独自のディレクトリを用意します
2. モジュール間の通信には、公開されたコントラクト（インターフェース／DTO）のみを使用します。別のモジュールの内部型は決して参照しません
3. 各モジュールに、独自のデータベーススキーマまたはマイグレーションフォルダーを用意します
4. 各モジュールが独自のサービス／依存関係を登録します
5. モジュール間に循環依存を作りません

共有カーネルのルール

1. 横断的関心事のみを含めます。基底エンティティ、共通値オブジェクト、イベントバスインターフェース、認証の抽象化が該当します
2. 薄く保ちます。大きくなった場合は、何かがモジュールに属していることを示します
3. いずれのモジュールに固有のビジネスロジックも含めません

インフラストラクチャのルール

1. エントリーポイントを単一にします（Program.cs / main.ts / main.py / main.go）
2. コンポジションルートで、すべてのモジュールを連携させます
3. データベースコンテキスト／セッションは共有しますが、スキーマは分離します
4. 非同期のモジュール間通信にはイベントバスを使用します（プロセス内で実行し、後からメッセージブローカーに置き換えられるようにします）

ステップ 3：コードを生成する

各モジュールについて、以下を生成します。

• ドメインレイヤー：エンティティ、値オブジェクト、ドメインイベント、リポジトリーインターフェース
• アプリケーションレイヤー：ユースケース／コマンド／クエリー、DTO、バリデーション
• インフラストラクチャレイヤー：リポジトリー実装、データベース設定、マイグレーション
• API レイヤー：コントローラー／ハンドラー、リクエスト／レスポンスモデル、モジュール登録

さらに、以下も生成します。

• 共有カーネル：基底クラス、イベントバス、共通の抽象化
• ホスト／エントリーポイント：コンポジションルート、ミドルウェア、設定
• テスト：モジュールの単体テスト、統合テスト、コントラクトテスト、アーキテクチャ境界テスト。references/testing-strategies.mdを参照してください。
• オブザーバビリティ：モジュール単位のロギング、ヘルスチェック、トレーシングの設定。references/observability.mdを参照してください。
• Docker（リクエストされた場合）：データベースを含む Dockerfile と docker-compose
• README.md：アーキテクチャの概要、実行方法、モジュールの追加方法（examples/README-template.mdを使用）

ステップ 4：検証する

生成後、以下を確認します。

1. どのモジュールも、別のモジュールの内部型を直接参照していないこと
2. 各モジュールに専用のスキーマ／マイグレーションフォルダーがあること
3. 共有カーネルにビジネスロジックが含まれていないこと
4. プロジェクトが正常にビルド／コンパイルできること
5. 生成されたテストを実行すること

CI 統合用の検証スクリプトは scripts/にあります。

• scripts/validate-boundaries.sh <modules-dir> — モジュール間の境界違反を検出します
• scripts/validate-shared-kernel.sh <shared-dir> <modules-dir> — 共有カーネルがモジュールを参照していないことを確認します
• scripts/check-circular-deps.sh <modules-dir> — モジュール間の循環依存を検出します

ステップ 5：移行ガイダンス

ユーザーがモジュールをマイクロサービスに切り出す方法について尋ねた場合は、手順を詳しく説明したガイドとしてreferences/migration-to-microservices.mdを参照してください。ガイドでは、以下を取り上げています。

• 切り出すタイミング（根拠に基づく兆候）
• 切り出し前のチェックリスト
• サービスの作成、実装の切り替え、レジリエンスの追加
• ロールバック戦略

適用すべき主な原則

原則	意味	適用方法
高凝集性	モジュールがそのドメインに必要なすべてを含む	モジュールごとにドメイン＋アプリケーション＋インフラストラクチャ＋APIを配置する
疎結合	モジュール同士が互いの内部に依存しない	共有コントラクト／インターフェース経由でのみ通信する
単一責任	各モジュールが1つの境界づけられたコンテキストを持つ	モジュールディレクトリーごとに1つのビジネスドメインを配置する
データのカプセル化	モジュールが自身のデータを所有する	モジュールごとに別のDBスキーマを設け、モジュール間クエリーを行わない
依存関係の明示	すべてのモジュール依存関係が可視化されている	必要なコントラクトを列挙したモジュール登録ファイルを用意する
ドメイン駆動設計	モジュールがビジネスドメインに沿っている	技術レイヤーではなく、ビジネス機能に基づいて命名する

呼び出し例

/modular-monolith dotnet ECommerceApp Product Order Payment Shipping
/modular-monolith spring-boot MyShop catalog basket checkout
/modular-monolith nestjs SaasApp tenant billing notification
/modular-monolith go FinanceApp accounts transactions reporting

これを使用しない場合

ユーザーが以下を説明している場合は、代わりにマイクロサービスを提案してください。

• 完全に独立したデプロイサイクルを必要とするチーム
• 多言語の技術スタックが必要な要件（Python の ML ＋ Go の API ＋ Java のエンタープライズシステム）
• サービスごとに極めて高いスケーリング要件がある
• すでに Kubernetes インフラストラクチャと成熟した DevOps 体制がある

以下の場合は、シンプルなモノリスを提案してください。

• 個人開発者、またはごく小規模なチーム（開発者 1～3 人）
• ドメインの境界が不明確なプロトタイプ／MVP
• 明確に異なるビジネスドメインが3つ未満のアプリケーション