mcpField
C
code-modularization-evaluator

code-modularization-evaluator

github.com/dotneet開発3460 回インストール40 週間前に更新
リポジトリ

code-modularization-evaluator について

Code Modularization Evaluator は、Balanced Coupling Model に基づいてコードの結合を評価するスキルです。統合強度、距離、変動性、コネセンスから問題のある依存を特定し、リファクタリングの手順を検討できます。

主な機能

  1. 01結合の強度・距離・変動性の評価
  2. 02静的・動的コネセンスの分類
  3. 03モジュール化に関する警告兆候の特定
  4. 04対象を絞ったリファクタリング案
  5. 05コンポーネントマップによる評価整理

活用シーン

  1. 01モジュールやサービス間の依存関係をレビュー
  2. 02循環依存や重複ロジックの調査
  3. 03分散モノリスのリファクタリング計画
  4. 04ソフトウェア設計でモジュール境界を評価

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dotneet/claude-code-marketplace --skill code-modularization-evaluator

インストール後、Claude Code で/code-modularization-evaluatorを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
connascence-types.md
coupling-metrics.md
refactoring-patterns.md

詳細

コードのモジュール化評価

Vlad Khononov 著『Balancing Coupling in Software Design』のバランスの取れた結合モデルを使用して、コードのモジュール化を評価します。このスキルは、問題のある結合パターンを特定し、実行可能なリファクタリングの指針を示します。

基本原則

**結合そのものが悪いのではなく、設計の不適切な結合が悪いのです。**目標は結合をゼロにすることではなく、バランスの取れた結合です。

基本となる数式：

MODULARITY = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

システムがモジュール性を実現するのは、次の場合です：

  • 統合強度の高いコンポーネントが近くにある（同じモジュール／サービス内）
  • 統合強度の低いコンポーネントが離れていてもよい（異なるサービス間）
  • 変動性の低いコンポーネントは、結合の不一致を許容できる

結合の3つの側面

結合は常に、次の3つの側面から評価してください：

1. 統合強度（どのような知識を共有していますか？）

最も強い（最悪）ものから最も弱い（最良）ものの順：

レベル種類説明例
1侵襲的非公開インターフェースを使用する別サービスのデータベースに直接アクセスする、リフレクションで非公開フィールドを参照する
2機能的ビジネスロジック／ルールを共有する同じ検証が2か所に重複している、順序に依存する操作
3モデルドメインモデルを共有する2つのサービスが同一のエンティティ定義を使用している
4契約明示的なインターフェースのみを使用する適切に設計されたAPI、DTO、プロトコル
2. 距離（知識はどれほど遠くまで伝わりますか？）

最も近いものから最も遠いものの順：

  1. 同じクラス内のメソッド
  2. 同じファイル内のクラス
  3. 同じ名前空間／パッケージ内のクラス
  4. 異なる名前空間のモジュール
  5. 独立したサービス／マイクロサービス
  6. 異なるチームが所有するサービス
  7. 異なるシステム／組織
3. 変動性（どのくらいの頻度で変更されますか？）

ドメイン駆動設計のサブドメイン分類を使用します：

  • コアサブドメイン：変動性が高い（競争上の優位性があり、頻繁に変更される）
  • 支援サブドメイン：変動性が低い（必要だが、差別化要因ではない）
  • 汎用サブドメイン：変動性が低い（解決済みの問題で、安定している）

判断フレームワーク

コードを評価する際は、次のマトリックスを適用してください：

統合強度距離結果
高大❌ 複雑性（分散モノリス）
低小❌ 複雑性（不要な抽象化）
高小✅ モジュール性（関連するものをまとめる）
低大✅ モジュール性（独立したコンポーネントを分離する）

例外：変動性が低い場合、結合の不一致は許容できます。

コネセンス分析

コネセンスを使用して、具体的な結合の種類を特定します。詳しい例については、references/connascence-types.mdを参照してください。

静的コネセンス（コンパイル時に発生し、修正が容易）

弱いものから強いものの順：

  1. 名前（CoN）：コンポーネントが名前について合意している
  2. 型（CoT）：コンポーネントが型について合意している
  3. 意味（CoM）：コンポーネントが値の意味について合意している（マジックナンバー）
  4. 位置（CoP）：コンポーネントが値の順序について合意している
  5. アルゴリズム（CoA）：コンポーネントがアルゴリズムのロジックを共有している
動的コネセンス（実行時に発生し、検出が困難）

弱いものから強いものの順： 6. 実行（CoE）：メソッド呼び出しの順序が重要である 7. タイミング（CoTm）：実行のタイミングが重要である 8. 値（CoV）：複数の値を同時に変更する必要がある 9. 同一性（CoI）：同じインスタンスを参照する必要がある

コネセンスのルール
  1. コネセンス全体を最小限にする
  2. モジュール境界を越えるコネセンスを最小限にする
  3. モジュール境界内のコネセンスを最大限にする
  4. 強い形式のコネセンスを弱い形式に変換する
  5. 距離が大きくなるほど、コネセンスは弱くする

評価チェックリスト

コードを分析する際は、次の点を確認してください：

危険信号（直ちに対応が必要）
  • 他のサービスのデータベースへの直接アクセス（侵入的な結合）
  • リフレクションによるプライベートフィールドへのアクセス
  • サービス間で重複するビジネスロジック
  • 同期デプロイが必要なマイクロサービス
  • クラスの CBO（オブジェクト間結合度）が 14 を超えている
  • 頻繁に変更されるモジュールの不安定度指数が 0.3～0.7
  • モジュール間の循環依存
警告サイン（さらに調査が必要）
  • コンポーネント間で共有されるマジックナンバー／値（CoM）
  • API における位置依存パラメーター（CoP）
  • 複数の場所で重複するアルゴリズムロジック（CoA）
  • 特定の順序で呼び出す必要があるメソッド（CoE）
  • 長いメソッドチェーン：a.b().c().d()（デメテルの法則への違反）
  • 「Manager」「Helper」「Utility」という名前で、多くの処理を担うクラス
健全なパターン
  • サービス間の契約ベースの統合
  • 内部モデルを適切に抽象化する DTO
  • モジュール内の高い凝集度
  • クラスごとの単一責任
  • 外部依存関係に対する依存性注入

リファクタリング戦略

統合強度の問題別

侵入的結合 → 契約結合：

  1. 実装詳細への直接的な依存関係をすべて特定する
  2. 明示的なインターフェース／契約を定義する
  3. アダプターレイヤーを作成する
  4. すべてのアクセスをアダプター経由にする

機能結合 → モデル結合：

  1. 共有するビジネスロジックを専用モジュールに抽出する
  2. 明確な所有権を定義する
  3. 明示的な依存関係を通じて利用する

モデル結合 → 契約結合：

  1. 統合専用の DTO を作成する
  2. 境界で内部モデルと DTO の間をマッピングする
  3. モデルとは独立して契約をバージョン管理する
Connascence の種類別
FromToTechnique
CoM（意味）CoN（名前）マジック値を名前付き定数／列挙型に置き換える
CoP（位置）CoN（名前）名前付きパラメーター、ビルダーパターン、またはパラメーターオブジェクトを使用する
CoA（アルゴリズム）CoN（名前）アルゴリズムを単一の場所に抽出し、名前で参照する
CoT（型）CoN（名前）ダックタイピングまたはインターフェースを使用する
CoE（実行）明示的ステートマシン、ビルダーパターン、またはコンストラクター注入を使用する
CoI（識別）明示的明示的な配線を伴う依存性注入を使用する
距離の問題別

高い強度＋大きな距離（分散モノリス）：

  • オプション A：距離を縮める—サービス／モジュールを統合する
  • オプション B：強度を下げる—契約や非同期メッセージングを導入する

低い強度＋小さな距離（過剰な抽象化）：

  • 不要な抽象化レイヤーを削除する
  • 過度に汎用的なコードをインライン化する
  • 密接に関連するクラスを統合する

分析ワークフロー

コードのモジュール化を評価するよう依頼された場合：

  1. コンポーネント構造を把握する

    • モジュール、サービス、クラスを特定する
    • 依存関係グラフを描く

  2. 統合強度を評価する

    • 各依存関係を分類する：侵入的／機能／モデル／契約
    • 境界を越える強度の高い依存関係に印を付ける

  3. 距離を測定する

    • コンポーネントの配置場所を記録する（同じファイル → 別のシステム）
    • チーム／所有権の境界を特定する

  4. 変動性を評価する

    • 各コンポーネントのサブドメインの種類を分類する
    • 過去に頻繁に変更された領域を記録する

  5. 式を適用する

    • 確認する：強度と距離は適切に釣り合っているか？
    • 変動性によって不釣り合いが正当化されるか？

  6. Connascence を特定する

    • 特定の Connascence の種類がないか調べる
    • 優先順位を付ける：強度が高い＋局所性が低い＋次数が高い

  7. 対応策を推奨する

    • 影響度と工数に基づいて優先順位を付ける
    • 具体的なリファクタリング手法を提示する

出力形式

評価は次の形式で構成してください：

## Modularization Assessment

### Summary
[Brief overview of coupling health]

### Component Map
[Describe module/service structure]

### Coupling Analysis
| Component Pair | Strength | Distance | Volatility | Balance |
|---------------|----------|----------|------------|---------|
| A → B         | Model    | High     | High       | ❌      |

### Connascence Issues
1. [Specific connascence type]: [Location] - [Impact]

### Recommendations
1. **Priority 1**: [Action] - [Rationale]
2. **Priority 2**: [Action] - [Rationale]

### Refactoring Plan
[Step-by-step approach for highest-priority item]

参考資料

  • Connascence の詳細な例については、references/connascence-types.md を参照してください
  • 結合度メトリクスについては、references/coupling-metrics.md を参照してください
  • リファクタリングパターンについては、references/refactoring-patterns.md を参照してください

制限事項

  • 実行コンテキストがなければ、ランタイムの動作を評価できません
  • 変動性の評価には、ドメイン知識が必要です
  • チーム／組織間の距離の評価には、プロジェクトのコンテキストが必要です
  • 静的解析だけでは、過去の変更頻度を把握できません

コメント

Markdown 対応