modularity-review

name	modularity-review
description	既存コードの結合構造を 3 次元（統合強度・距離・変動性）で分析し、不均衡を検出する。 既存システムのモジュール境界を見直したいとき、分散モノリスや泥団子の兆候を調査したいとき、 リファクタリング前に結合構造を把握したいとき。

Modularity Review

既存コードのモジュール間結合を構造的に分析し、不均衡を検出するワークフロー skill です。design-and-plan（balanced-coupling-design）が「これから作るもの」の設計に使うのに対し、この skill は「すでにあるもの」の構造診断に使います。 ゴール駆動で使うため、最初に達成したいゴール、成功条件、確認手段を短く固定します。

こんなときに使う

• 既存システムのモジュール間結合を客観的に評価したいとき
• 分散モノリス化の兆候（高強度 + 高距離の統合が増えている）を調査したいとき
• 泥団子化の兆候（低凝集、責務の不明瞭な大きなモジュール）を調査したいとき
• リファクタリング前に、どの結合を優先的に改善すべきかを特定したいとき
• design-and-plan の設計レビューで検出した構造的課題を深掘りしたいとき

ワークフロー: 結合構造分析

ステップ 1 — 問題領域の理解

分析対象のシステム/コードベースを理解する。

やること:

• 対象範囲を確認する（全体 or 特定モジュール群）
• 既存のモジュール（パッケージ、プロジェクト、サービス等）を列挙する
• 各モジュールの表面的な責務を整理する
• 業務領域とモジュールの対応関係を把握する
• 可能であれば、業務領域をサブドメインに分類する（Core / Supporting / Generic）

入力:

• 分析対象のコードベースまたはアーキテクチャ文書
• ユーザーからの問題意識や分析目的（あれば）

出力: モジュール一覧と業務領域マッピング

ステップ 2 — 統合マッピング

モジュール間の統合を特定し、3 次元で評価する。

やること:

1. モジュール間の統合（依存関係、データフロー、API 呼び出し、イベント、共有リソース等）を列挙する
2. 各統合を 3 次元で評価する:
   • 統合強度: 共有する知識の量
     • Contract — 契約（API インターフェース）のみ共有
     • Model — ドメインモデルの構造を共有
     • Functional — 実装の一部（共通ライブラリ、ユーティリティ）を共有
     • Intrusive — 他モジュールの内部に直接依存（DB 共有、内部型の参照等）
   • 距離: 変更を同期するコスト
     • 技術的距離（同一プロセス / 別プロセス / 別サービス / 別チームの別サービス）
     • 組織的距離（同一チーム / 同一部門 / 別部門）
   • 変動性: サブドメイン分類に基づく変更確率
3. 暗黙的な統合も探す: 共有 DB、設定ファイル共有、グローバル状態、命名規約への依存等

出力: 統合マップ（テーブル形式）

ステップ 3 — バランスルール適用と不均衡検出

統合マップにバランスルールを適用し、構造的リスクを特定する。

バランスルール: BALANCE = (統合強度 XOR 距離) OR NOT 変動性

• 強度が高いなら距離は低くあるべき（= 密な結合はモジュール統合で距離を縮める）
• 距離が大きいなら強度は低くあるべき（= 遠い統合は契約で疎結合にする）
• 変動性が低いなら、多少の不均衡は許容範囲

不均衡の分類:

• Critical: 高強度 + 高距離 + 高変動性 → 変更のたびに高コストな同期が必要
• Significant: 中程度の変動性で不均衡、または暗黙的な結合が隠れている
• Minor: 低変動性で不均衡 → 認知負荷は上がるが実害は小さい

出力: 不均衡リスト（統合 / 3 次元評価 / 重大度 / 根拠）

ステップ 4 — レビュー文書と是正提案

分析結果をレビュー文書にまとめ、是正策を提案する。

レビュー文書に含めるもの:

• 分析概要: 対象範囲、モジュール数、統合数
• サブドメイン分類表: 業務領域 / 分類 / 根拠 / 変動性
• 結合評価表: 統合 / 統合強度 / 距離 / 変動性 / バランス? / 重大度
• 不均衡リスト: Critical / Significant / Minor の各項目と根拠
• 是正提案: 各不均衡に対する改善案と優先度
  • 契約の導入（統合強度を下げる）
  • モジュール統合（距離を縮める）
  • 境界の再定義（責務の分離 or 統合）
  • 腐敗防止層（モデル変換装置）の導入
• 保留事項: 分析で不足した情報、追加調査が必要な領域

出力の型

レビュー文書

# Modularity Review: [対象システム/モジュール名]

## 分析概要
- 対象範囲: [全体 / 特定モジュール群]
- モジュール数: N
- 統合数: M
- 分析日: YYYY-MM-DD

## サブドメイン分類表
| 業務領域 | 分類 | 根拠 | 変動性 |
|---------|------|------|--------|
| ... | Core / Supporting / Generic | ... | High / Medium / Low |

## 結合評価表
| 統合 | 統合強度 | 距離 | 変動性 | バランス? | 重大度 |
|-----|---------|------|--------|----------|--------|
| A → B | Contract / Model / Functional / Intrusive | ... | ... | ✅ / ❌ | Critical / Significant / Minor |

## 不均衡リスト

### Critical
- [統合名]: [問題の説明と根拠]

### Significant
- [統合名]: [問題の説明と根拠]

### Minor
- [統合名]: [問題の説明と根拠]

## 是正提案
| 統合 | 提案 | 優先度 | 影響範囲 |
|-----|------|--------|---------|
| ... | ... | High / Medium / Low | ... |

## 保留事項
- [追加調査が必要な項目]

判断表

やりたいこと	やること
既存コードの結合構造を分析したい	ステップ 1 から順に進める
特定モジュール群だけ分析したい	ステップ 1 で対象範囲を限定する
不均衡の是正策を提案してほしい	ステップ 3 の結果を基にステップ 4 で具体案を作る
design-and-plan で検出した課題を深掘りしたい	該当モジュールを対象にステップ 1 から分析する

注意点

• すべての統合を均等に扱わない: バランスルールに従い、Critical から優先的に対処する。
• 変動性の見積もりは暫定でよい: サブドメイン分類が不明確な場合は Medium で仮置きし、後で見直す。
• 是正策は提案まで: 実際の変更方針は planning や設計の次段に渡す。この skill は診断に専念する。
• 暗黙的な結合を見逃さない: コードの依存関係だけでなく、共有 DB、設定、グローバル状態も統合として扱う。

関連リソース

• plugins/happy-coding/skills/design-and-plan/SKILL.md — 設計の入口
• plugins/happy-coding/skills/design-and-plan/_foundation/DDD_GLOSSARY.md — 用語集
• plugins/happy-coding/skills/design-and-plan/SKILL.md — 是正策の構造判断
• plugins/happy-coding/skills/interview-with-docs/SKILL.md — 是正策を用語・前提・ADR と照合するとき
• docs/local_references/balanced-coupling/README.md — Balanced Coupling モデルの参照ガイド