ddd-refactoring

DDDリファクタリング

既存コード（貧血ドメインモデル・トランザクションスクリプト・レイヤー混在）を DDD へ段階的にリファクタリングする戦略立案と実行を支援する。

位置づけ: anti-pattern-detector エージェントが問題を検出し、本スキルが修正を導く。リファクタリング前にまず anti-pattern-detector で現状を把握することを推奨する。

進め方の原則

1. テストで保護してから動かす: 既存の振る舞いを characterization test（現状の入出力を固定するテスト）で記録してから変更する。テストがないコードはリファクタリングしない
2. 小さく刻む: 1回の変更は1つのパターン適用に限定し、各ステップでテストが通ることを確認する
3. 振る舞いを変えない: リファクタリングと機能変更を同じ変更に混ぜない
4. 価値の高い場所から: 変更頻度が高く、ビジネス上重要なモジュール（コアドメイン）から着手する。触らないコードは無理に直さない

戦略の選択

どの戦略で進めるか？
│
├─ 対象が小さい（数クラス〜1モジュール）
│  └→ 直接リファクタリング（後述のロードマップを順に適用）
│
├─ 対象が大きいが、モジュール境界が明確
│  └→ モジュール単位の段階的リファクタリング
│     （重要度の高いモジュールから1つずつ）
│
├─ 対象が大きく、境界も不明確（巨大な泥団子）
│  └→ Strangler Fig パターン
│     （新しいモデルを隣に作り、徐々に置き換える）
│
└─ 書き直しの誘惑がある
   └→ 原則避ける。全面書き直しは仕様の暗黙知を失う

段階的リファクタリングのロードマップ

リスクの小さい順に適用する。各ステップは独立して価値があり、途中で止めても改善が残る。

Step 1: ユビキタス言語の確立

コードを変更する前に、ドメインの言葉を整理する（ubiquitous-language スキルを参照）。

• ドメインエキスパートの語彙とコード上の名前のズレを一覧化する
• 名前変更（rename）は最も安全なリファクタリングであり、ここから始める

Step 2: Value Object の抽出

プリミティブ型をドメインの型に置き換える（value-object スキルを参照）。

• 影響範囲が局所的でリスクが低く、検証ロジックの重複が消える
• まず1つの VO（例: Money）を導入し、利用箇所を段階的に置き換える

Step 3: ロジックのエンティティへの移動（貧血モデルの解消）

サービスクラスに漏れたビジネスロジックをエンティティ・VO に移す（entity-design / domain-service スキルを参照）。

手順:
1. サービスのメソッドから「主語が特定のエンティティ」のロジックを特定する
2. エンティティに新メソッドを追加し、サービスから委譲する（旧メソッドは残す）
3. テストが通ることを確認する
4. 呼び出し元を新メソッドに切り替え、旧メソッドを削除する
5. 公開セッターを1つずつ削除し、ビジネスメソッドに置き換える

Step 4: 集約境界の確立

トランザクション境界と整合性の単位を定義する（aggregate-design スキルを参照）。

• 集約ルートを特定し、子エンティティへの外部アクセスをルート経由に限定する
• 集約間の直接参照を ID 参照に置き換える
• 非ルートエンティティのリポジトリを削除し、ルートのリポジトリに統合する

Step 5: レイヤー責務の是正

ドメイン層からインフラ依存を排除する（domain-classifier / architecture-checker を参照）。

• ドメイン層の ORM アノテーション・外部クライアント依存を特定する
• リポジトリインターフェース（ポート）をドメイン層に定義し、実装をインフラ層に移す
• コントローラからのリポジトリ直接呼び出しをアプリケーションサービス経由に改める

Step 6: ドメインイベントの導入

集約をまたぐ処理を結果整合性に分離する（domain-event スキルを参照）。

• 1トランザクションで複数集約を更新している箇所を特定する
• 主集約の更新でドメインイベントを発行し、他集約の更新はイベントハンドラに移す

アンチパターン別修正レシピ

anti-pattern-detector の検出結果に対応する修正手順:

アンチパターン	修正レシピ	適用ステップ
Anemic Domain Model	ロジックをサービスからエンティティへ段階的に移動	Step 3
Repository per Entity	集約ルートを特定し、子のリポジトリを統合	Step 4
Leaking Infrastructure	ポート定義とマッピング層の導入でインフラ依存を分離	Step 5
God Aggregate	不変条件の分析に基づき集約を分割、参照を ID 化	Step 4
Skipping Ports	アプリケーションサービスを導入し呼び出し経路を是正	Step 5
CRUD Thinking	ユビキタス言語によるメソッドの再命名から着手	Step 1, 3
Premature CQRS	複雑性に見合わない分離を統合し単純化	個別判断
Cross-Aggregate Transaction	ドメインイベントによる結果整合性へ分離	Step 6

Strangler Fig パターン

巨大で境界の不明確なレガシーに対しては、新モデルを隣に育てて置き換える。

1. 境界を定める
   新しいモデルを適用する範囲（コンテキスト）を決める
   （bounded-context スキルを参照）

2. ファサード/腐敗防止層を置く
   レガシーと新モデルの間に変換層を設け、
   新モデルがレガシーの構造に汚染されないようにする

3. 新規機能・変更箇所から新モデルに実装する
   既存機能は動かしたまま、入口で新旧に振り分ける

4. レガシー側の利用を計測し、ゼロになった部分を削除する

安全のためのチェックリスト

各ステップの完了時に確認する:

• 変更前後でテストがすべて通る
• 1つの変更に1つのパターン適用のみ含まれている
• 公開APIの振る舞いが変わっていない（変える場合は別変更として明示）
• 削除候補の旧コード（委譲だけのメソッド等）を放置していない
• anti-pattern-detector を再実行し、対象の検出が解消している

擬似コード例

examples/ ディレクトリに具体例がある:

• examples/refactoring-example.pseudo — 貧血モデル+トランザクションスクリプトを段階的に改善する Before/After