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