architecture-patterns

出典の明記：wshobson/agents を原典とするスキルの内容です。 （MIT License, Copyright (c) 2024 Seth Hobson。ライセンス全文は同じディレクトリの LICENSE.txt をご覧ください）。 使用、変更、再配布にあたっては、当該 MIT ライセンスの条件に従い、著作権表示を保持してください。

日本語の説明

このスキルでは、フルスタック開発に関するベストプラクティスとパターンを案内します。

---

name: architecture-patterns description: Clean Architecture、Hexagonal Architecture、Domain-Driven Design など、実績のあるバックエンドアーキテクチャパターンを実装します。新しいマイクロサービスのクリーンアーキテクチャを設計する場合、モノリスをリファクタリングして境界づけられたコンテキストを導入する場合、ヘキサゴナルアーキテクチャやオニオンアーキテクチャのパターンを実装する場合、またはアプリケーションレイヤー間の依存関係の循環をデバッグする場合に、このスキルを使用してください。

アーキテクチャパターン

Clean Architecture、Hexagonal Architecture、Domain-Driven Design など、実績のあるバックエンドアーキテクチャパターンを習得し、保守性、テスト容易性、拡張性に優れたシステムを構築します。

入力： アーキテクチャを設計するサービス境界またはモジュール。 生成物： 明確な依存関係のルール、インターフェース定義、テスト境界を備えたレイヤー構造。

このスキルを使用する場面

• 新しいバックエンドサービスやマイクロサービスをゼロから設計するとき
• ビジネスロジックが ORM モデルや HTTP の関心事と絡み合ったモノリシックアプリケーションをリファクタリングするとき
• システムをサービスに分割する前に、境界づけられたコンテキストを確立するとき
• インフラストラクチャコードがドメイン層に入り込むことで発生した依存関係の循環をデバッグするとき
• ユースケースのテストに実行中のデータベースを必要としない、テスト容易性の高いコードベースを作成するとき
• ドメイン駆動設計の戦術的パターン（集約、値オブジェクト、ドメインイベント）を実装するとき

主な概念

1. Clean Architecture（Uncle Bob）

レイヤー（依存関係は内側に向かいます）：

• エンティティ：フレームワークをインポートしない、ビジネスモデルの中核
• ユースケース：アプリケーションのビジネスルール。エンティティを編成します
• インターフェースアダプター：コントローラー、プレゼンター、ゲートウェイ。ユースケースと外部形式の間を変換します
• フレームワークとドライバー：UI、データベース、外部サービス。すべて最外周に配置されます

主な原則：

• 依存関係は内側にのみ向かい、内側のレイヤーは外側のレイヤーについて何も知りません
• ビジネスロジックはフレームワーク、データベース、提供メカニズムから独立しています
• すべてのレイヤー境界は抽象インターフェースを介して越えます
• UI、データベース、外部サービスなしでテストできます

2. ヘキサゴナルアーキテクチャ（ポートとアダプター）

構成要素：

• ドメインコア：ビジネスロジックを配置する場所で、フレームワークに依存しません
• ポート：コアと外部とのやり取りを定義する抽象インターフェース（駆動側と被駆動側）
• アダプター：ポートの具体的な実装（PostgreSQL アダプター、Stripe アダプター、REST アダプター）

メリット：

• コアに手を加えずに実装を切り替えられます（例：PostgreSQL を DynamoDB に置き換える）
• テストではインメモリアダプターを使用できるため、Docker は不要です
• 技術選定を境界部分まで先送りできます

3. ドメイン駆動設計（DDD）

戦略的パターン：

• 境界づけられたコンテキスト：サブドメインごとに一貫性のあるモデルを分離します。システム全体で単一のモデルを共有することは避けます
• コンテキストマッピング：コンテキスト間の関係（腐敗防止層、共有カーネル、オープンホストサービス）を定義します
• ユビキタス言語：コード内の用語を、ドメインの専門家が使う用語と一致させます

戦術的パターン：

• エンティティ：安定した識別子を持ち、時間の経過とともに変化するオブジェクト
• 値オブジェクト：属性によって識別される不変オブジェクト（Email、Money、Address）
• 集約：整合性の境界。外部からアクセスできるのはルートのみです
• リポジトリ：集約を永続化し、再構成します。ストレージ方式を抽象化します
• ドメインイベント：ドメイン内で発生した出来事を記録し、集約間の調整に使用します

詳細なパターンと実例

詳細なパターンのドキュメントは references/details.md にあります。上記の概要だけでは不十分な場合は、そのファイルを読んでください。

テスト — インメモリアダプター

Clean Architecture が正しく適用されていることを示す特徴は、実際のデータベース、Docker、ネットワークを使わず、通常の単体テストですべてのユースケースを実行できることです。

# tests/unit/test_create_user.py
import asyncio
from typing import Dict, Optional
from domain.entities.user import User
from domain.interfaces.user_repository import IUserRepository
from use_cases.create_user import CreateUserUseCase, CreateUserRequest


class InMemoryUserRepository(IUserRepository):
    def __init__(self):
        self._store: Dict[str, User] = {}

    async def find_by_id(self, user_id: str) -> Optional[User]:
        return self._store.get(user_id)

    async def find_by_email(self, email: str) -> Optional[User]:
        return next((u for u in self._store.values() if u.email == email), None)

    async def save(self, user: User) -> User:
        self._store[user.id] = user
        return user

    async def delete(self, user_id: str) -> bool:
        return self._store.pop(user_id, None) is not None


async def test_create_user_succeeds():
    repo = InMemoryUserRepository()
    use_case = CreateUserUseCase(user_repository=repo)

    response = await use_case.execute(CreateUserRequest(email="[email protected]", name="Alice"))

    assert response.success
    assert response.user.email == "[email protected]"
    assert response.user.id is not None


async def test_duplicate_email_rejected():
    repo = InMemoryUserRepository()
    use_case = CreateUserUseCase(user_repository=repo)

    await use_case.execute(CreateUserRequest(email="[email protected]", name="Alice"))
    response = await use_case.execute(CreateUserRequest(email="[email protected]", name="Alice2"))

    assert not response.success
    assert "already exists" in response.error

トラブルシューティング

ユースケースのテストに実行中のデータベースが必要になる

ビジネスロジックがインフラストラクチャ層に漏れています。すべてのデータベース呼び出しを IRepository インターフェースの背後に移し、テストではインメモリ実装を注入してください（上記のテストのセクションを参照）。ユースケースのコンストラクターでは、具象クラスではなく抽象ポートを受け取る必要があります。

レイヤー間で循環インポートが発生する

よくある症状は、use_cases と adapters の間で ImportError: cannot import name X が発生することです。これは、ユースケースが抽象ポートではなく具象アダプタークラスをインポートすると起こります。次のルールを徹底してください。use_cases/ がインポートできるのは domain/（エンティティとインターフェース）だけです。adapters/ や infrastructure/ をインポートしてはいけません。

ドメインエンティティにフレームワークのデコレーターが現れる

ドメインエンティティに SQLAlchemy の Column() や Pydantic の Field() のアノテーションが現れる場合、そのエンティティはすでに純粋ではありません。adapters/repositories/ に個別の ORM モデルを作成し、リポジトリーの _to_entity() メソッドでドメインエンティティとの相互変換を行ってください。

すべてのロジックがコントローラーに集まる

コントローラーが HTTP の解析とレスポンスの整形を超えて大きくなった場合は、ロジックをユースケースクラスに切り出してください。コントローラーメソッドが行うのは、リクエストの解析、ユースケースの呼び出し、レスポンスのマッピングの3つだけです。

値オブジェクトのエラー検出が遅すぎる

__post_init__（Python）またはコンストラクターで不変条件を検証し、無効な Email や Money をそもそも構築できないようにしてください。これにより、ビジネスロジックの深部ではなく、境界で不正なデータを検出できます。

境界づけられたコンテキスト間でコンテキストが混在する

Order コンテキストが Identity コンテキストの User エンティティをインポートしている場合は、腐敗防止層を導入してください。Order コンテキストは独自の軽量な CustomerId 値オブジェクトを保持し、明示的なインターフェースを介してのみ Identity コンテキストを呼び出す必要があります。

高度なパターン

DDD の境界づけられたコンテキストの詳細なマッピング、複数サービスを含むプロジェクトツリー全体、腐敗防止層の実装、オニオンアーキテクチャとの比較については、次を参照してください。

• references/advanced-patterns.md

関連スキル

• microservices-patterns — モノリスをサービスに分解する際に、これらのアーキテクチャパターンを適用します
• cqrs-implementation — CQRS のコマンドとクエリーの分離における構造的な基盤として、Clean Architecture を使用します
• saga-orchestration — サガには明確に定義された集約境界が必要です。DDD の戦術的パターンによって、その境界を定義できます
• event-store-design — 集約が生成するドメインイベントは、イベントストアに直接送られます

ワークフロー

ステップ 1：要件分析

プロジェクトの要件と技術的な制約を理解します

ステップ 2：アーキテクチャ設計

システムアーキテクチャとコンポーネントの構成を設計します

ステップ 3：実装ガイダンス

具体的な実装の提案とコードパターンを提供します

ステップ 4：コードレビュー

コードの品質とベストプラクティスへの準拠状況をレビューします

ステップ 5：最適化の提案

パフォーマンスの最適化と改善の提案を行います

注意点

1. 過剰設計

単純なケースで複雑なデザインパターンを使用するのは避けてください

2. パフォーマンスの軽視

特に本番環境では、パフォーマンスの最適化を軽視しないでください

3. セキュリティへの配慮

セキュリティとデータ保護を常に考慮してください

4. テストカバレッジ

特に境界条件について、十分なテストカバレッジを確保してください

5. ドキュメントの保守

ドキュメントをコードと同期した状態に保ってください