ddd-architecture-evaluator

DDD アーキテクチャ評価ツール

アーキテクチャの評価と進化 — DDD の健全性を体系的に評価し、技術的負債を定量化して、アーキテクチャの進化を計画します。構造化された再現可能なプロセスにより、あらゆるプロジェクトタイプ（Java/Go/Python/TS/.NET）に対応します。

読むタイミング

このドキュメントを参照してプロセスを確認したら、評価を開始できます。ユーザーがアーキテクチャ評価、DDD の成熟度、技術的負債の定量化、アーキテクチャの進化について尋ねた場合に参照します：

• 「プロジェクトのアーキテクチャを評価してください」→ ワークフローを直接開始
• 「私たちの DDD はどの程度できていますか」→ 成熟度評価から開始
• 「技術的負債が多すぎる場合、どうすればよいですか」→ 技術的負債の定量化から開始
• 「MVC から DDD に移行する必要があります」→ 進化ロードマップから開始

ワークフロー

Step 1: Assess Maturity
  → Run 5-level DDD maturity checklist (L1 → L5)
  → Identify current level vs target level (L3 is sufficient for most projects)
  → Output: Maturity level + per-level pass/fail + key gaps

Step 2: Evaluate Fitness
  → Score 5 dimensions: Business Alignment (25%), Team Fit (25%),
    Technology Fit (20%), Evolution Capability (15%), Delivery Efficiency (15%)
  → Calculate weighted fitness score
  → Output: Dimension scores + total fitness + green/yellow/orange/red rating

Step 3: Quantify Debt
  → Structural debt (P0, weight 0.5) — layer violations, circular deps, anemic entities
  → Design debt (P1, weight 0.3) — oversized aggregates, missing VOs/events
  → Testing debt (P2, weight 0.2) — domain unit test coverage
  → Output: Total debt score + health rating (green/mild/moderate/severe)

Step 4: Plan Evolution
  → 4-phase roadmap: Emergency (1-2w) → Short-term (2-4w) →
    Mid-term (1-3m) → Long-term (ongoing)
  → Migration risk assessment with Strangler Fig strategy
  → Output: Phased roadmap + risk matrix + next assessment date

対応範囲

✅ 得意な分野

分野	提供内容
DDD 成熟度評価	L1-L5 の段階別チェックリスト + スコア計算 + 主要なギャップ分析
アーキテクチャ適合性の 5 次元評価	Business / Team / Technology / Evolution / Delivery の加重スコア
技術的負債の定量化	構造・設計・テストの 3 種類の負債 + 加重スコア + 4 段階の健全性評価
アーキテクチャ進化ロードマップ	4 段階の進化計画 + 各段階の所要時間見積もり + 優先順位付け
移行リスク評価	Strangler Fig による段階的な移行案 + リスクマトリクス + ロールバック戦略
定期的なアーキテクチャ健全性チェック	構造化された評価レポート + 改善項目の追跡 + 次回評価時期の提案

⚠️ 条件が必要

1. レビュー可能なコードがあること：プロジェクトがすでに一定期間稼働しており、実際のコードベースがあること（新規プロジェクトには ddd-architecture-selector の使用を推奨します）
2. チームがプロジェクトの背景を提供できること：アーキテクチャドキュメント、コード構成、チーム規模などの情報が必要です
3. 評価目標が明確であること：評価の焦点（全体的な成熟度 / 特定モジュールの評価 / 移行の実現可能性）を指定することを推奨します

❌ 対象外 / 範囲外

1. コードレベルのレビュー → ddd-code-reviewer を使用します（アンチパターンの検出、レイヤー分離の適合性チェック）
2. 新規プロジェクトのアーキテクチャ選定 → ddd-architecture-selector を使用します（5 種類のアーキテクチャの比較判断マトリクス）
3. DDD の入門学習 → ddd-architecture-awesome を使用します（概念のクイックリファレンス、リッチモデルと貧血モデルの比較）
4. アーキテクチャの具体的な実装 → ddd-architecture-layered / onion / hexagonal / clean / cola をそれぞれ使用します

セキュリティと安全に関する説明

この Skill は非侵襲的な分析フレームワークです。評価時にコードベースへアクセスしたり、プロジェクトデータを収集したり、情報をアップロードしたりすることはありません。評価結果はすべて、ユーザーが提供したコンテキストに基づいて現在の会話内で作成され、保存も第三者への送信もされません。プロジェクト構成の情報を開示するかどうかは、ユーザー自身が判断します。

DDD 成熟度の 5 段階モデル

レベル	名称	焦点	合格基準
L1	Ad Hoc（初期レベル）	3 層 + 貧血エンティティ + すべてのロジックが Service にある	≥ 5/7
L2	Aware（認識レベル）	部分的なリッチモデル + VO を使用 + チームの認識	≥ 3/5
L3	Applied（実践レベル）	集約境界 + Domain の依存関係ゼロ + リッチエンティティ	≥ 5/7
L4	Scaled（スケールレベル）	複数の BC + CQRS + ArchUnit による CI 自動化	≥ 5/7
L5	Optimized（最適化レベル）	継続的な進化 + ES + ADR + 負債ダッシュボード	≥ 5/7

段階別の完全なチェックリストは maturity-levels-detail.md を参照してください。

アーキテクチャ適合性の 5 次元評価

次元	重み	スコア 1-5	確認項目
ビジネスとの整合性	25%	1-5	アーキテクチャはビジネスの複雑さに合っていますか？過剰設計または設計不足になっていませんか？
チームとの適合性	25%	1-5	チームは規約を理解し、遵守していますか？違反率はどの程度ですか？
テクノロジーとの適合性	20%	1-5	技術スタックはアーキテクチャをサポートしていますか？摩擦が生じる箇所はありますか？
進化への対応力	15%	1-5	新しい BC を追加できますか？リファクタリングコストはどの程度ですか？モジュール間の結合度はどの程度ですか？
デリバリー効率	15%	1-5	機能のデリバリーサイクルは業界のベースラインと比べてどうですか？アーキテクチャのオーバーヘッドはどの程度ですか？

Total Fitness = BA×0.25 + TF×0.25 + TechF×0.20 + EC×0.15 + DE×0.15

Score interpretation:
  ≥ 4.0 → 🟢 Excellent
  3.0-3.9 → 🟡 Adequate
  2.0-2.9 → 🟠 Concerning
  < 2.0  → 🔴 Critical

完全な採点基準と評価用プロンプトについては、fitness-assessment-template.md を参照してください。

技術的負債の定量化

カテゴリ別内訳

カテゴリ（優先度）	重み	指標
構造的負債（P0）	0.5	レイヤー違反率、循環依存の数、貧血エンティティの割合、フレームワーク漏出率
設計上の負債（P1）	0.3	過大な集約の割合、ドメインイベント欠落率、VO 欠落率、集約間参照
テストの負債（P2）	0.2	ドメインの単体テストカバレッジ、集約ルートのテストカバレッジ、統合テストカバレッジ

計算方法

負債合計 = 構造的負債×0.5 + 設計上の負債×0.3 + テストの負債×0.2

スコア	評価	対応
≤ 20	🟢 健全	対応不要
21–40	🟡 軽度	定期的に返済
41–60	🟠 中程度	今四半期中に計画を策定
> 60	🔴 深刻	直ちにリファクタリングを開始

詳細な方法論と計算例は debt-calculation-guide.md を参照してください。

4段階の進化ロードマップ

Traditional 3-Layer → DDD 4-Layer → DDD + Rich Domain → Hexagonal/Clean → Microservices + DDD

フェーズ	期間	焦点	主なアクション
1. 緊急対応（問題の封じ込め）	1-2 weeks	P0 違反の修正	レイヤー違反を削減し、循環依存を解消し、集約をまたぐ参照を修正します
2. 短期（小規模なリファクタリング）	2-4 weeks	コアドメインの充実	コア集約をリッチ化し、VO（Money/Phone/Address）を導入し、ドメインイベントを追加します
3. 中期（アーキテクチャのアップグレード）	1-3 months	アーキテクチャのアップグレード	モノリスをBCに分割し、CQRSを採用し（L1から開始）、必要に応じてパターンをアップグレードします
4. 長期（継続的な進化）	継続的	継続的な進化	毎月の適合性チェック、技術的負債のダッシュボード、ADRの記録、チーム向けDDDトレーニングを実施します

移行リスク評価

移行前チェックリスト

• ☐ アーキテクチャを文書化済み（C4 / ADR）
• ☐ ビジネスの複雑さを評価済み
• ☐ チームのDDD知識を評価済み
• ☐ 移行範囲を定義済み（全面移行か段階的移行か）
• ☐ 目標アーキテクチャについて合意済み（チーム＋関係者）
• ☐ ロールバック計画を策定済み（≤ 4 hours）

ストラングラーフィグ — 新機能は目標アーキテクチャへ、既存機能は維持しつつ段階的に置き換え、コア集約は最初に移行します。

リスクマトリクス

リスクレベル	影響	対応
高	コアビジネスロジック	カナリアリリース＋自動ロールバック
中	非コア機能	トラフィックミラーリングによる並行稼働
低	読み取り専用／クエリ	パフォーマンスを検証して直接切り替え

移行評価テンプレートの全容については、migration-risk-checklist.mdを参照してください。

注意点

よくある評価上の落とし穴については、references/gotchas.mdを参照してください。

FAQ

質問	回答
評価の頻度は？	四半期ごとの評価を推奨します。新機能の開発が頻繁に妨げられる場合、技術的負債がデリバリーに影響している場合、重大なビジネス変更がある場合は評価を実施してください。
1回の評価にどのくらいかかりますか？	小規模なら1-2h、中規模なら0.5-1日、大規模なら2-3日です。初回は時間がかかりますが、次回以降はベースラインを再利用できます。
すべてのプロジェクトでレベル5が必要ですか？	いいえ。ほとんどの業務システムではレベル3で十分です。レベル4-5は、金融や取引の中核システムに適しています。
進捗をどのように測定しますか？	ベースラインを設定し、各回で成熟度の変化、技術的負債スコア、改善項目の完了率（目標 ≥ 80%）を比較します。
評価後の次のステップは？	P0の修正 → コアドメインのリッチ化 → アーキテクチャのアップグレード → 継続的な進化です。各段階の後に簡易レビューを行います。

キーワード

DDDの成熟度、アーキテクチャ適合性、技術的負債、アーキテクチャの進化、移行評価、ストラングラーフィグ、境界づけられたコンテキスト、CQRS、イベントソーシング、アーキテクチャ決定記録、ADR、技術的負債の定量化、アーキテクチャ評価、成熟度モデル、技術的負債の定量化、アーキテクチャの進化、移行リスク、アーキテクチャ適合度、レイヤー準拠

参考資料

• maturity/assessment-workflow.md — 成熟度評価の準備、セッションのワークフロー、よくある落とし穴
• maturity/maturity-levels-detail.md — レベルごとの詳細なチェックリストとスコアリング
• fitness/scoring-rubric.md — コンテキストに基づく調整を含むスコアリング基準
• fitness/fitness-assessment-template.md — 5次元のスコアリング基準とプロンプト
• debt/repayment-strategies.md — 技術的負債の返済戦略と優先順位付けマトリクス
• debt/debt-calculation-guide.md — 例を含む技術的負債の算出方法
• migration/strangler-fig-detailed.md — ストラングラーフィグ移行計画の詳細
• migration/migration-risk-checklist.md — 移行準備状況チェックリストとリスクマトリクス
• evolution-cases.md — 実際の進化事例（Eコマース、FinTech、SaaS）
• code-smells-diagnosis.md — アーキテクチャのアンチパターンと診断
• migration-path.md — MVCからDDDへの6段階の移行パス
• partme-11-ddd-refactoring.md — エンタープライズモデリングを用いたDDDリファクタリング事例
• gotchas.md — よくある評価上の落とし穴（スコアリングの偏り、移行コスト、チームの能力など）