# 20. Code Visualization and Quality Metrics Strategy

Date: 2026-02-14

## Status

Accepted

## Context

プロジェクトの規模拡大に伴い、以下の課題が発生している：
1.  **構造の把握困難**: モジュール間の依存関係が複雑化し、新規参画者が全体像を掴みにくい。
2.  **品質の定量化**: コードの複雑さが「感覚」で語られており、客観的なリファクタリング基準がない。
3.  **アーキテクチャの健全性**: 「安定依存の原則（SDP）」が守られているか（不安定なモジュールが安定したモジュールに依存しているか）を確認する手段がない。

## Decision

以下の3つのツール/スクリプトを導入し、CI/CDおよびローカル開発フロー（Makefile）に統合する。

1.  **Radon**: 
    * 関数・クラスレベルの「循環的複雑度 (Cyclomatic Complexity)」と「保守性指数 (Maintainability Index)」を計測する。
    * `make audit` で実行可能にする。

2.  **Pydeps**: 
    * モジュール間のインポート依存関係を可視化するグラフ（SVG）を生成する。
    * `make visualize` で実行可能にする。

3.  **Custom Stability Analyzer**:
    * Robert C. Martinのパッケージ原則に基づく「不安定度 ($I = Ce / (Ca + Ce)$)」を算出するスクリプトを `tools/` に配置する。
    * Graphvizを用いて、安定度に基づいた色分け（青＝安定、赤＝不安定）を行ったアーキテクチャ図を生成する。

## Consequences

### Positive
* **客観的な指標**: リファクタリングの優先順位を数値（複雑度ランクC以上など）に基づいて決定できる。
* **オンボーディングの高速化**: 生成された図を見ることで、コードを読む前に構造を理解できる。
* **設計違反の検知**: 不安定度が低い（Coreなどの）モジュールが、不安定度が高い（CLIなどの）モジュールに依存している「逆流」を視覚的に発見できる。

### Negative
* **実行環境の要件**: `graphviz` (システムパッケージ) のインストールが必須となる。

