architecture-paradigm-modular-monolith

モジュラーモノリスのパラダイム

使用する場面

• 大規模なコードベースを、明確に境界づけられたモジュールに整理するとき
• 分散システムの複雑さを伴わずに、マイクロサービスの境界を設けたいチーム

使用しない場面

• すでにマイクロサービスとして分散されている場合
• モジュールの境界を設けることで不要な複雑さが生じる、小規模なアプリケーション

このパラダイムを採用する場面

• 分散システムの運用負荷を伴わずに、マイクロサービスと同様のチームの自律性を実現したい場合。
• 内部モジュール間の複雑に絡み合った依存関係によって、リリースの速度が低下している場合。
• 現時点ではモノリシックアーキテクチャのほうが運用しやすい一方で、将来的にサービスベースのモデルへ移行する明確な必要性がある場合。

導入手順

1. モジュールを特定する：個別のビジネス機能、またはドメイン駆動設計における境界づけられたコンテキストに沿って、モジュールの境界を定義します。
2. 内部をカプセル化する：言語レベルの可視性修飾子（例：public/private）、個別のパッケージ、または名前空間を使用して、各モジュールの実装詳細を隠します。
3. 公開コントラクトを公開する：各モジュールは、明確に定義されたファサード、API、またはイベントを通じて機能を公開します。モジュール間でのデータベーステーブルへの直接アクセスや実装の直接呼び出しは禁止します。
4. アーキテクチャの適合性を確保する：モジュール間に禁止された依存関係やパッケージ参照が導入された場合、ビルドを失敗させる自動テストを実装します。
5. 進化に備える：変更の結合度やデプロイ範囲などの指標を継続的に追跡し、モジュールを個別のサービスに分割するかどうか、またその時期について、情報に基づいて判断します。

主な成果物

• モジュールの境界を図示し、共有コードに関するルールを定義するアーキテクチャ決定記録（ADR）。
• モジュール間のすべての連携ポイントについての正式なコントラクト文書（例：OpenAPI 仕様、イベントスキーマ）。
• 境界を強制するための自動依存関係チェックと、各モジュール専用の CI/CD ジョブ。

リスクと緩和策

• 「大きな泥団子」への逆戻り：
  • 緩和策：厳格に強制しなければ、モジュールの境界は必然的に損なわれます。境界違反をビルド失敗として扱い、規律あるコードレビューを徹底します。
• 共有データベースのボトルネック：
  • 緩和策：共有データベースへの高い競合がボトルネックになることがあります。スキーマの所有権を明確にし、ビューを使ったアクセスでデータの可視性を制限するか、データ複製戦略を実装して結合度を下げます。

トラブルシューティング

よくある問題

スキルが読み込まれない YAML フロントマターの構文と必須フィールドを確認してください。

トークン制限を超過する 段階的開示を使用し、詳細をモジュールに移してください。

モジュールが見つからない SKILL.md 内のモジュールパスが正しいことを確認してください。

具体的なコンポーネント

このパラダイムの実装でよく使われるツールや抽象化の用語です。依存関係ではなく、tools: フロントマターでもありません。

• dependency-analyzer：禁止された依存関係を検出するためのモジュール依存関係グラフビルダー
• module-boundary-enforcer：モジュール境界を越えたインポートがあるとビルドを失敗させるツール
• refactoring-planner：将来的な分割に向けた抽出準備度に基づいて、モジュールを順位付けするツール

完了条件

• ADR でモジュールの境界とビジネス機能の対応を示し、共有コードのルールを定義し、モジュールを個別のサービスとして抽出する条件を明記している。
• 各モジュールが文書化されたファサード、API、またはイベントを通じてのみ機能を公開しており、モジュール間でのデータベーステーブルへの直接アクセスが存在しない（スキーマの所有権レビューで確認済み）。
• 自動依存関係チェックによって、禁止されたモジュール間インポートがあると CI ビルドが失敗し、そのような違反のテストケースが少なくとも 1 つ文書化されている。
• 変更の結合度（常に一緒に変更されるモジュール）の指標を追跡し、結合度が 50% を超えるモジュールの組み合わせに対して、境界の見直し候補としてフラグを立てている。