clean-architecture

クリーンアーキテクチャのベストプラクティス

保守性とテスト容易性に優れたソフトウェアシステムを設計するための、クリーンアーキテクチャの原則に関する包括的なガイドです。Robert C. Martin 著『Clean Architecture: A Craftsman's Guide to Software Structure and Design』に基づいています。アーキテクチャへの影響度に応じて優先順位付けされた、8 カテゴリ、42 のルールを掲載しています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• 新しいソフトウェアシステムやモジュールを設計するとき
• レイヤー間の依存関係を構成するとき
• ビジネスロジックとインフラストラクチャの境界を定義するとき
• アーキテクチャ上の違反がないかコードをレビューするとき
• 密結合したシステムを、よりクリーンな構造へリファクタリングするとき

優先順位別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	依存関係の方向	CRITICAL	dep-
2	エンティティの設計	CRITICAL	entity-
3	ユースケースの分離	HIGH	usecase-
4	コンポーネントの凝集性	HIGH	comp-
5	境界の定義	MEDIUM-HIGH	bound-
6	インターフェースアダプター	MEDIUM	adapt-
7	フレームワークの分離	MEDIUM	frame-
8	テストアーキテクチャ	LOW-MEDIUM	test-

クイックリファレンス

1. 依存関係の方向（CRITICAL）

• dep-inward-only - ソースコードの依存関係は内側にのみ向ける
• dep-interface-ownership - インターフェースは実装側ではなくクライアント側に属する
• dep-no-framework-imports - 内側のレイヤーではフレームワークをインポートしない
• dep-data-crossing-boundaries - 境界を越えるデータには単純なデータ構造を使う
• dep-acyclic-dependencies - コンポーネント間の循環依存を排除する
• dep-stable-abstractions - 変わりやすい具象ではなく、安定した抽象に依存する

2. エンティティの設計（CRITICAL）

• entity-pure-business-rules - エンティティには企業のビジネスルールのみを含める
• entity-no-persistence-awareness - エンティティは永続化の方法を知ってはならない
• entity-encapsulate-invariants - ビジネス上の不変条件をエンティティ内にカプセル化する
• entity-value-objects - ドメインの概念には値オブジェクトを使う
• entity-rich-not-anemic - 貧血したデータ構造ではなく、豊かなドメインモデルを構築する

3. ユースケースの分離（HIGH）

• usecase-single-responsibility - 各ユースケースの変更理由を 1 つにする
• usecase-input-output-ports - ユースケースの入力ポートと出力ポートを定義する
• usecase-orchestrates-not-implements - ユースケースはビジネスルールを実装せず、エンティティを統括する
• usecase-no-presentation-logic - ユースケースにプレゼンテーションロジックを含めない
• usecase-explicit-dependencies - すべての依存関係をコンストラクターで明示的に宣言する
• usecase-transaction-boundary - ユースケースでトランザクション境界を定義する

4. コンポーネントの凝集性（HIGH）

• comp-screaming-architecture - 構造からフレームワークではなくドメインが伝わるようにする
• comp-common-closure - 一緒に変更されるクラスをまとめる
• comp-common-reuse - クライアントに未使用コードへの依存を強制しない
• comp-reuse-release-equivalence - 凝集性のある単位でコンポーネントをリリースする
• comp-stable-dependencies - 安定性の高い方向に依存する

5. 境界の定義（中〜高）

• bound-humble-object - アーキテクチャ上の境界では、控えめなオブジェクトを使用します
• bound-partial-boundaries - 完全な分離が時期尚早な場合は、部分的な境界を使用します
• bound-boundary-cost-awareness - 境界のコストと無知のコストを比較検討します
• bound-main-component - main をアプリケーションのプラグインとして扱います
• bound-defer-decisions - フレームワークとデータベースに関する決定を先送りにします
• bound-service-internal-architecture - サービスには内部クリーンアーキテクチャが必要です

6. インターフェースアダプター（中）

• adapt-controller-thin - コントローラーを薄く保ちます
• adapt-presenter-formats - プレゼンターはビュー向けにデータをフォーマットします
• adapt-gateway-abstraction - ゲートウェイによって外部システムの詳細を隠します
• adapt-mapper-translation - レイヤー間の変換にはマッパーを使用します
• adapt-anti-corruption-layer - 外部システム向けに腐敗防止層を構築します

7. フレームワークの隔離（中）

• frame-domain-purity - ドメイン層にはフレームワークへの依存が一切ありません
• frame-orm-in-infrastructure - ORM の使用はインフラストラクチャ層に留めます
• frame-web-in-infrastructure - Web フレームワークに関する関心事はインターフェース層に留めます
• frame-di-container-edge - 依存性注入コンテナーは境界部分に配置します
• frame-logging-abstraction - ドメインインターフェースの背後でロギングを抽象化します

8. テストアーキテクチャ（低〜中）

• test-tests-are-architecture - テストはシステムアーキテクチャの一部です
• test-testable-design - 最初からテスト可能性を考慮して設計します
• test-layer-isolation - 各層を個別にテストします
• test-boundary-verification - テストでアーキテクチャ上の境界を検証します

使用方法

詳しい説明やコード例については、個々のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報