ddd-architecture-clean

DDD アーキテクチャ — Clean

Robert C. Martin（Uncle Bob）によるクリーンアーキテクチャ：ユースケース中心で、厳格な依存関係ルールを採用します。ソースコードの依存関係は内側のみを向く必要があります。

クイックスタート

要件を直接伝えてください。例：「クリーンアーキテクチャのプロジェクト骨格を作成して」／「注文モジュールに CreateOrder UseCase を、エンティティからコントローラーまで実装して」／「プロジェクトの依存関係の方向が正しいか確認して」／「3 層アーキテクチャからクリーンアーキテクチャへ移行し、まず注文モジュールを移行して」。

情報が不足している場合は、まず参考案を提示し、その後、補足が必要な具体的な情報を列挙します。

ワークフロー

ステップ 1：基本概念を確認する

チーム内で、DDD のエンティティ、値オブジェクト、集約ルートについて共通の理解があることを確認します。不明確な場合は、まず ddd-architecture-awesome を参照してください。

ステップ 2：エンタープライズビジネスルールを定義する

集約ルートを特定 → エンティティと値オブジェクトを設計 → ビジネスルールを実装 → ドメインイベントを定義します。01-core-entities、注文エンティティの例を参照してください。

ステップ 3：UseCase のポートを定義する

各 UseCase に独立した Input Port → Output Port → UseCase DTO を定義します。02-usecase-portsを参照してください。

ステップ 4：UseCase Interactor を実装する

Interactor を記述 → エンティティとポート呼び出しを調整 → ドメインイベントを発行します。03-interactors、注文作成の例を参照してください。

ステップ 5：アダプター層を実装する

Controller → Presenter → Repository Impl → Gateway Impl → DI 設定。04-adapters、05-framework-configを参照してください。

ステップ 6：検証とテスト

エンタープライズ層の単体テスト → UseCase の統合テスト → Adapter の統合テスト → ArchUnit による検証。06-dependency-rules、07-testing-strategyを参照してください。

使用する場合／使用しない場合

✅ 適している	❌ 適していない
企業の中核システム（注文、決済、在庫）	一時的なスクリプト、小規模なツール
ビジネスルールがデリバリー方式から独立している	フロントエンドの比重が大きく、バックエンドが軽量な単純 CRUD
モジュールの厳格な物理的分離が必要（15～50 人のチーム）	5 人未満のチーム、迅速な反復が必要
マイクロサービス内部の標準アーキテクチャ	単純な 3 層アーキテクチャで十分
UseCase 駆動の複雑なビジネス処理	複雑なビジネスロジックのない管理画面

対応範囲

カテゴリ	能力	説明
✅ 得意	厳密にレイヤー分割されたエンタープライズシステム	15～50 人のチーム、モジュール間を強く分離
✅ 得意	UseCase 駆動設計	各ユースケースに独立した Interactor と Port
✅ 得意	依存関係ルールの自動チェック	ArchUnit によるレイヤー準拠の全自動検証
✅ 得意	複数言語での実装	Java/Go/TypeScript/C# で実装可能
⚠️ 条件あり	チームが Interactor パターンを理解している	そうでない場合、学習コストが高く、トレーニングが必要
⚠️ 条件あり	プロジェクトに一定の規模がある	小規模なプロジェクトには Layered/Onion のほうが適しています
⚠️ 条件あり	DDD のドメインモデルとの併用が必要	Clean Architecture 単独では抽象的すぎます
❌ 対象外	単純な CRUD プロジェクト	ddd-architecture-layered を使用してください
❌ 対象外	中国語圏の Spring Boot エコシステム	ddd-architecture-cola を使用してください
❌ 対象外	可視化された同心円モデルが必要	ddd-architecture-onion を使用してください
❌ 対象外	ポートとアダプターの概念が必要	ddd-architecture-hexagonal を使用してください

対象ユーザー

ユーザーの種類	使用方法
バックエンドアーキテクト／技術責任者	そのまま使用し、技術選定を行ってワークフローの 6 ステップに沿って導入します
Java 開発者	examples/ のコードテンプレートを参考に、手順に沿って UseCase を実装します
DDD 初心者	まず ddd-architecture-awesome を読んで概念を理解してから、この Skill に戻ってください
複数言語のチーム（Go/TypeScript/C#）	アーキテクチャルールは共通です。references/ の言語非依存の内容を参考にしてください

カスタマイズ：呼び出す際に技術スタック（Java/Go/TS）とモジュール名（注文／決済など）を伝えると、それに応じたコードテンプレートを生成します。

コアアーキテクチャ

Enterprise ← UseCase ← Adapter ← Framework

詳しい原則（4 層構造、アーキテクチャの比較、データフロー）については、architecture-principlesを参照してください。ディレクトリ構造については、directory-structureを参照してください。

開発規約

規約	説明	違反例
Entity はフレームワークに依存しない	Spring/JPA/Jackson を import してはいけません	@Entity が core/entity/ にある
UseCase ごとに独立したポートを定義する	1 つの UseCase = 1 つの Input Port インターフェース	複数の UseCase が同じインターフェースを共有している
Interactor は調整のみを行い、ビジネスロジックを実装しない	ビジネス上の if/else は Entity に記述する必要があります	Interactor に状態遷移の判定がある
Output Port は UseCase で定義する	Repository インターフェースは usecase 層に定義します	Adapter が Repository インターフェースを定義している
データ変換は Adapter 層で行う	Controller DTO を UseCase に渡してはいけません	@RequestBody DTO を Interactor に直接渡している
トランザクションは Framework 層で管理する	@Transactional は adapter/repository のみに指定します	Entity メソッドに @Transactional がある

詳しい規約については、references/06-dependency-rules.mdを参照してください。

よくある落とし穴

#	落とし穴	現象	正しい対応
1	UseCase にビジネスロジックを含める	Interactor に if/else による状態判定がある	Entity/Domain Service に切り出す
2	Input Port を共有する	複数の UseCase が同じインターフェースを共用する	UseCase ごとに独立した Input Port を設ける
3	Controller の DTO がレイヤーを越える	フレームワークの DTO が UseCase 層に渡される	Adapter 層で DTO ↔ Domain の変換を行う
4	Entity に @Entity 注釈が付いている	JPA 注釈が Enterprise 層に漏れている	Adapter 層に独立した JPA Entity を作成する
5	Interactor が Adapter を直接呼び出す	Output Port を介さず実装クラスを呼び出す	Output Port インターフェースを介して呼び出す
6	Output Port を Adapter 層に配置する	UseCase が Adapter パッケージに依存する	Output Port インターフェースは UseCase 層で定義する
7	UseCase が Entity オブジェクトを返す	Interactor が DTO ではなく Order を返す	UseCase 専用の Output DTO を返す
8	単純なクエリを過剰に設計する	読み取り操作にも完全な Input→Interactor→Output の流れを使う	単純なクエリは Repository を直接呼び出す
9	Adapter にビジネスロジックを含める	Controller に if/else がある	ビジネスロジックはすべて Enterprise 層に置く
10	ArchUnit によるチェックがない	依存関係違反を自動検出できない	CI に ArchUnit テストを組み込む
11	ドメインオブジェクトが可変である	ValueObject に setter メソッドがある	すべての値オブジェクトを不変にする (record/final)
12	UseCase の粒度が適切でない	Interactor が大きすぎる (200+ 行)	1 つの Interactor で扱う業務操作は 1 つだけにする
13	ドメインイベントを無視する	重要な操作の後にイベントが発行されない	状態変更時には必ずドメインイベントを発生させる
14	UseCase 層にトランザクションがある	Interactor に @Transactional が付いている	トランザクションは Adapter/Repository 層に置く
15	Entity のコンストラクターが公開されている	Entity に public コンストラクターを使う	static factory メソッド（Order.create() など）を使う

よくある質問

#	質問	回答
1	Clean Architecture と六角形アーキテクチャの違いは何ですか？	整潔アーキテクチャは UseCase を構成の中心とし、4 層の厳密な分離を重視します。六角形アーキテクチャは Port/Adapter による抽象化を用い、駆動側と被駆動側のポートの対称性を重視します。中心となる目標は同じで、内側の層が外側の層に依存しないことです。
2	Interactor と Domain Service はいつ使いますか？	Interactor は UseCase 層で処理を調整します（Entity を呼び出し、Port を呼び出します）。Domain Service は Enterprise 層で複数のエンティティにまたがる業務ルール（PricingService など）をカプセル化します。
3	Service ではどこにビジネスロジックを書きますか？	どこにも書きません。Entity には業務メソッド（pay/cancel）があり、DomainService は複数のエンティティにまたがるルールをカプセル化します。Interactor は調整のみを行い、判断はしません。
4	UseCase ごとに独立した Input Port が必要ですか？	はい。これはインターフェース分離の原則（ISP）に従うものです。IOrderService のような大きなインターフェースはアンチパターンです。
5	1 つの UseCase に複数の出力がある場合はどうしますか？	出力ごとに独立した Output Port を設けます。たとえば、OrderRepository は永続化、EventPublisher はイベント、PaymentGateway は決済を担当します。
6	Entity 層から Repository インターフェースを参照できますか？	できません。Enterprise 層は Output Port の存在を一切認識してはなりません。Repository インターフェースは UseCase 層で定義します。
7	単純なクエリも UseCase 層を通しますか？	いいえ。読み取り専用の操作は Repository を直接呼び出してかまいません（クエリは状態を変更しません）。書き込み操作は必ず UseCase を通します。
8	複数の UseCase はどのように構成しますか？	業務上の集約ごとに構成します。order/usecase/ の下に、Order 関連の CreateOrder/PayOrder/CancelOrder をすべて配置します。
9	Interactor でトランザクションをどのように処理しますか？	Framework 層で宣言的トランザクション（@Transactional）を使い、Interactor の呼び出しを囲みます。
10	JPA Entity と Domain Entity は分ける必要がありますか？	はい。JPA Entity（@Entity）は Adapter 層に、Domain Entity（純粋な POJO）は Enterprise 層に配置します。Converter を介して変換します。
11	3 層アーキテクチャからの移行にはどのくらいかかりますか？	小規模 (6 週間) / 中規模 (12 週間) / 大規模 (20 週間) です。Strangler Fig パターンを使い、UseCase ごとに段階的に移行します。
12	依存関係のルールが破られないようにするにはどうしますか？	Framework モジュールに ArchUnit テストを記述します（examples/04-archunit-test.md を参照）。CI でコミットのたびに自動チェックします。
13	値オブジェクトとエンティティの違いは何ですか？	値オブジェクトは不変で、ID を持たず、属性で等価性を判定します（Money など）。エンティティは可変で、一意の ID を持ち、ID で等価性を判定します（Order など）。
14	ドメインイベントは同期と非同期のどちらで発行しますか？	Interactor 内でイベントを同期的に収集し、EventPublisher Port に発行します。非同期処理は Adapter で実装します（メッセージキューへの書き込みなど）。
15	Adapter 層に複数の実装を置けますか？	はい。1 つの Output Port に複数の Adapter 実装を用意できます（JPA/MyBatis/InMemory）。Spring Profile で切り替えます。

キーワード

Clean Architecture, 整潔架構, Robert C. Martin, Uncle Bob, Enterprise Business Rules, Use Case, Interactor, Input Port, Output Port, Interface Adapter, Dependency Rule, 依存倒置, インターフェース分離, DDD, ドメイン駆動設計, レイヤーアーキテクチャ, 厳密なレイヤー分離, ユースケース駆動, ドメインモデル, エンティティ, 値オブジェクト, 集約ルート, ドメインイベント, ArchUnit, 依存関係ルールのチェック

参考資料

内部

文件	内容
references/architecture-principles.md	四層構造、依存ルール、アーキテクチャの比較、データフロー、ディレクトリ構造
references/01-core-entities.md	Enterprise 層のエンティティ、値オブジェクト、ドメインイベント、例外テンプレートとテスト
references/02-usecase-ports.md	Input/Output Port の定義、DTO 設計、ポート設計ルール
references/03-interactors.md	Interactor の実装テンプレート、複雑なオーケストレーション、クエリ Interactor、テスト
references/04-adapters.md	Controller、Repository Impl、Gateway アダプターの実装
references/05-framework-config.md	Spring DI 設定、Security、Persistence、複数 Profile
references/06-dependency-rules.md	依存ルールのマトリックス、ArchUnit の全テストセット、CI 統合
references/07-testing-strategy.md	レイヤー別テスト戦略、Test Doubles、カバレッジ目標
references/08-migration-guide.md	3 層からクリーンアーキテクチャへの移行ガイド、Strangler Fig パターン
examples/01-order-entity.md	Order エンティティの完全なコード + 状態遷移 + 単体テスト
examples/02-create-order-usecase.md	CreateOrder UseCase の完全な実装 + テスト + Test Doubles
examples/03-repository-implementation.md	Repository Adapter の JPA 実装 + 統合テスト
examples/04-archunit-test.md	ArchUnit の依存ルールをテストする完全なスイート
examples/05-domain-event-handling.md	ドメインイベントの定義、公開、消費の完全な実装
examples/06-monolith-simple.md	モノリス Clean 簡易版：単一モジュールのパッケージレベルの 4 層、ディレクトリツリー + 依存方向 + ArchUnit
examples/07-monolith-complex.md	モノリス Clean 複雑版：複数集約 + 複数 Interactor、共有カーネル + ドメイン分離
examples/08-monolith-multi-module.md	モノリス Clean マルチモジュール版：Maven のモジュールレベルのレイヤー分割、コンパイル時に依存方向を強制
examples/09-microservice-simple.md	マイクロサービス Clean 簡易版：パッケージレベルの 4 層 + イベントバス + Kafka アダプター
examples/10-microservice-complex.md	マイクロサービス Clean 複雑版：CQRS + Saga + Outbox + 複数サブドメイン
examples/11-microservice-multi-module.md	マイクロサービス Clean マルチモジュール版：6 モジュール + API 契約を独立して公開
examples/12-microservice-complex-multi.md	マイクロサービス Clean 複雑マルチモジュール版：8 モジュール + 全パターンのマトリックス + サブドメインのオーケストレーション

外部

• The Clean Architecture — Robert C. Martin（2012）
• Clean Architecture: A Craftsman's Guide — Robert C. Martin（2017）
• Domain-Driven Design: The Blue Book — Eric Evans（2003）
• Get Your Hands Dirty on Clean Architecture — Tom Hombergs
• thombergs/buckpal — Java リファレンス実装
• Hexagonal Architecture — Alistair Cockburn

DDD Skills エコシステム

前提／後続	Skill
← 前提	ddd-architecture-selector — アーキテクチャ選定（Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector）
→ 後続	ddd-domain-designer — ドメインモデリング（Install: npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer）
→ 後続	ddd-code-reviewer — コードレビュー（Install: npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer）
→ 後続	ddd-architecture-evaluator — アーキテクチャ評価（Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-evaluator）
🔗 関連	ddd-architecture-hexagonal — ヘキサゴナルアーキテクチャ（Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-hexagonal）
🔗 関連	ddd-architecture-layered — レイヤードアーキテクチャ（Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-layered）

🧭 DDD スキルの道のり

📍 現在地：ddd-architecture-clean — ステップ 3：整潔アーキテクチャの実装

awesome(入門) → selector(選定) → clean(整潔アーキテクチャ) + layered/onion/hexagonal/cola → domain-designer/cqrs/api-designer → code-reviewer → testing/devops/evaluator → architecture-doc

**← ddd-architecture-selector | → ddd-domain-designer | 🔗 ddd-api-designer · ddd-testing-strategist | 🏠 ddd-architecture-awesome

（各スキルは npx skills add full-stack-skills/ddd-skills --skill <name> でインストールします）

---

セキュリティと安定性

• すべてのコードテンプレートは教育目的です。本番環境では、プレースホルダーの認証情報を環境変数に置き換えてください。
• 整潔アーキテクチャの依存関係ルール（内側にのみ依存する）は、ドメインコードが I/O にアクセスするのを本質的に防ぐため、セキュリティ上の利点が組み込まれています。
• Interactor パターンにより、各 UseCase をフレームワークやデータベースに依存せず、個別にテストできます。
• 実行可能なスクリプトは含まれていません。この Skill では、アーキテクチャのガイダンスとコード生成パターンのみを提供します。