code-visualizer

Code Visualizer Skill

目的

コードフロー図を自動的に生成し、維持します。このスキルは Python モジュールの構造を分析し、インポート関係を検出して、mermaid 図を生成します。また、コードが変更されても図が更新されていない場合に、その古さを検出します。

哲学との整合性

このスキルは amplihack の中核となる哲学を体現しています。

徹底したシンプルさ

• 単一責任：コード構造の可視化のみを行います。それ以外は行いません
• 最小限の依存関係：分析には Python AST のみを使用し、図の構文は mermaid-diagram-generator に委譲します
• 過剰な設計を避ける：タイムスタンプに基づく古さの判定はシンプルで、ケースの 90% には「十分」です

BS ゼロの実装

• 実際の分析：Python AST を実際に解析してインポートを抽出します。モックデータは使用しません
• 制限を正直に伝える：古さの検出はタイムスタンプに基づいており、セマンティックなものではありません（「制限事項」セクションを参照）
• 動作するコード：ここに示すアルゴリズムはすべて機能するものであり、擬似コードではありません

モジュール設計（Bricks & Studs）

• このスキルは 1 つのブリックです：コード分析と古さの検出を行います
• 他のブリックに委譲します：構文には mermaid-diagram-generator を、複雑な図には visualization-architect を使用します
• 明確なスタッド（公開契約）：モジュールの分析、図の生成、最新状態の確認を行います

スキル委譲アーキテクチャ

code-visualizer (this skill)
├── Responsibilities:
│   ├── Python module analysis (AST parsing)
│   ├── Import relationship extraction
│   ├── Staleness detection (timestamp-based)
│   └── Orchestration of diagram generation
│
└── Delegates to:
    ├── mermaid-diagram-generator skill
    │   ├── Mermaid syntax generation
    │   ├── Diagram formatting and styling
    │   └── Markdown embedding
    │
    └── visualization-architect agent
        ├── Complex multi-level architecture
        ├── ASCII art alternatives
        └── Cross-module dependency graphs

呼び出しパターン：

# code-visualizer analyzes code structure
modules = analyze_python_modules("src/")
relationships = extract_import_relationships(modules)

# Then delegates to mermaid-diagram-generator for syntax
Skill(skill="mermaid-diagram-generator")
# Provide: Module relationships, diagram type (flowchart/class), styling preferences
# Receive: Valid mermaid syntax ready for embedding

# For complex architectures, delegates to visualization-architect
Task(subagent_type="visualization-architect", prompt="Create multi-level diagram for...")

このスキルを使用する場面

• 新しいモジュールの作成：新しいモジュールのアーキテクチャ図を自動生成します
• PR レビュー：提案された変更によるアーキテクチャへの影響を示します
• 古さの検出：既存の図が現在のコードを反映しているか確認します
• 依存関係の分析：インポート関係を可視化します
• リファクタリング：変更を加える前にモジュールの依存関係を把握します

クイックスタート

モジュールの図を生成する

User: Generate a code flow diagram for the authentication module

図が最新か確認する

User: Are my architecture diagrams up to date?

PR の影響を表示する

User: What architecture changes does this PR introduce?

主な機能

1. モジュール分析

Python ファイルを分析して、次の情報を抽出します。

• インポート文（内部および外部）
• クラス定義と継承関係
• 関数のエクスポート（__all__）
• モジュールの依存関係

2. 図の生成

次の内容を示す mermaid 図を作成します。

• モジュール間の関係（フローチャート）
• クラス階層（クラス図）
• コンポーネント間のデータフロー
• 依存関係グラフ

3. 古さの検出

次の項目を比較します。

• ファイルの変更タイムスタンプ
• 変更に関する Git の履歴
• 図の内容と実際のコード構造
• 図に含まれていないモジュール

分析プロセス

ステップ 1：モジュールを検出する

# Scan target directory for Python modules
modules = glob("**/*.py")
packages = identify_packages(modules)

ステップ 2：関係を抽出する

各モジュールについて、次の処理を行います。

1. インポート文を解析する
2. ローカルインポートと外部インポートを識別する
3. 依存関係グラフを構築する
4. 循環依存関係を検出する

ステップ 3：図を生成する

flowchart TD
    subgraph core["Core Modules"]
        auth[auth.py]
        users[users.py]
        api[api.py]
    end

    subgraph utils["Utilities"]
        helpers[helpers.py]
        validators[validators.py]
    end

    api --> auth
    api --> users
    auth --> helpers
    users --> validators

ステップ 4：最新状態を確認する

図のタイムスタンプをソースファイルと比較します。

• 図がソースより古い = 古い
• 図に含まれていないモジュールがある = 不完全
• 図に余分なモジュールがある = 旧式

図の種類

モジュール依存関係グラフ

用途：ファイル間のインポート関係を示します

flowchart LR
    main[main.py] --> auth[auth/]
    main --> api[api/]
    auth --> models[models.py]
    api --> auth

クラス階層

用途：継承とコンポジションを示します

classDiagram
    class BaseService {
        +process()
    }
    class AuthService {
        +login()
        +logout()
    }
    BaseService <|-- AuthService

データフロー

用途：システム内でデータがどのように流れるかを示します

flowchart TD
    Request[HTTP Request] --> Validate{Validate}
    Validate -->|Valid| Process[Process]
    Validate -->|Invalid| Error[Return Error]
    Process --> Response[HTTP Response]

古さの検出

仕組み

1. 図を検索する：README.md、ARCHITECTURE.md 内の mermaid 図を探します
2. モジュールを抽出する：図を解析し、参照されているモジュールを抽出します
3. 比較する：現在のすべてのモジュールが含まれているか確認します
4. 報告する：最新状態のレポートを生成します

最新状態レポートの形式

## Diagram Freshness Report

### Status: STALE

**Diagrams Checked**: 3
**Fresh**: 1
**Stale**: 2

### Details

| File         | Last Updated | Code Changed | Status |
| ------------ | ------------ | ------------ | ------ |
| README.md    | 2025-01-01   | 2025-01-15   | STALE  |
| docs/ARCH.md | 2025-01-10   | 2025-01-10   | FRESH  |

### Missing from Diagrams

- `new_module.py` (added 2025-01-12)
- `api/v2.py` (added 2025-01-14)

### Recommended Actions

1. Update README.md architecture diagram
2. Add new_module.py to dependency graph

PR によるアーキテクチャへの影響

表示される内容

特定の PR または一連の変更について、次の内容を示します。

1. 新たに追加されたモジュール／ファイル
2. 変更されたインポート関係
3. 削除された依存関係
4. 変更されたクラス階層

影響図

flowchart TD
    subgraph added["New"]
        style added fill:#90EE90
        new_api[api/v2.py]
    end

    subgraph modified["Modified"]
        style modified fill:#FFE4B5
        auth[auth.py]
    end

    subgraph existing["Unchanged"]
        users[users.py]
        models[models.py]
    end

    new_api --> auth
    auth --> models
    users --> models

他のスキルとの連携

Mermaid Diagram Generator

このスキルは、次の目的で mermaid-diagram-generator を使用します。

• 構文の生成
• 図のフォーマット
• Markdown への埋め込み

可視化アーキテクトエージェント

以下の処理を visualization-architect に委任します。

• 複雑なアーキテクチャの可視化
• ASCII アートによる代替案
• マルチレベルの図

使用例

例 1：新しいモジュールの図

User: I just created a new payment module. Generate an architecture diagram.

Claude:
1. Analyzes payment/ directory
2. Extracts imports and dependencies
3. Generates mermaid flowchart
4. Suggests where to embed (README.md)

例 2：古さの確認

User: Are my diagrams up to date?

Claude:
1. Finds all mermaid diagrams in docs
2. Compares with current codebase
3. Reports stale diagrams
4. Lists missing modules
5. Suggests updates

例 3：PR の影響

User: Show architecture impact of this PR

Claude:
1. Gets changed files from PR
2. Identifies new/modified/deleted modules
3. Generates impact diagram
4. Highlights dependency changes

検出アルゴリズム

インポート分析

# Extract imports from Python file
import ast

def extract_imports(file_path):
    """Extract import statements from Python file."""
    tree = ast.parse(Path(file_path).read_text())
    imports = []
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                imports.append(alias.name)
        elif isinstance(node, ast.ImportFrom):
            if node.module:
                imports.append(node.module)
    return imports

古さの確認

def check_staleness(diagram_file, source_dir):
    """Check if diagram is stale compared to source."""
    diagram_mtime = Path(diagram_file).stat().st_mtime

    for source in Path(source_dir).rglob("*.py"):
        if source.stat().st_mtime > diagram_mtime:
            return True, source  # Stale

    return False, None  # Fresh

ベストプラクティス

図を更新するタイミング

1. 新しいモジュール：依存関係グラフに追加します
2. インポートの変更：関連性を更新します
3. ファイルの削除：図から削除します
4. アーキテクチャの変更：完全に再生成します

図の配置場所

図の種類	推奨される配置場所
モジュールの概要	README.md
詳細なアーキテクチャ	docs/ARCHITECTURE.md
パッケージ構造	package/README.md
API フロー	api/README.md

命名規則

## Architecture





```mermaid
flowchart TD
    ...
```

成功基準

優れた可視化は、次の条件を満たします。

• 現在のすべてのモジュールが示されている
• 実際のインポート関係が反映されている
• 適切な図の種類が使われている
• 見つけやすい場所に配置されている
• 最新性を示すメタデータが含まれている
• 明瞭で、情報が詰め込まれすぎていない

制限事項

重要：このスキルを利用する前に、次の制限事項を理解してください。

古さの検出に関する制限事項

1. セマンティックではなく、タイムスタンプに基づく検出：実際のコード変更ではなく、ファイルの更新日時を比較します

   • ファイルに変更が加えられていても、意味のある変更でなければ「古い」と判定されます
   • コードのフォーマット変更により、誤検出が発生します
   • mtime を更新する Git 操作により、誤検出が発生します

2. ロジックの変更は検出できません：インポートを変更しない関数の追加は検出されません

   • モジュール内の内部リファクタリングは検出されません
   • 関数シグネチャの変更は反映されません
   • インポートの変更を伴わずに追加された新しいクラスメソッドは表示されません

3. インポート中心のビューです：インポート関係のみを追跡します

   • 実行時の依存関係（依存性注入）は検出されません
   • 設定に基づく接続は検出されません
   • ダックタイピングの関係は取得されません

対象範囲に関する制限事項

1. Python のみ：現在、分析できるのは Python ファイルのみです

   • TypeScript、JavaScript、Rust、Go はサポートされていません
   • 複数言語のプロジェクトは部分的にしかカバーされません

2. 静的分析のみ：実行時の情報はありません

   • 動的インポート（__import__、importlib）は検出されません
   • 条件付きインポートが見落とされる場合があります
   • プラグインアーキテクチャは完全には表現されません

3. 単一プロジェクトが対象：リポジトリをまたぐ依存関係は分析できません

   • 外部パッケージの内部構造は表示されません
   • モノレポ内の関係には手動設定が必要です

精度の目安

シナリオ	精度	備考
新しいモジュールの検出	95%+	Python モジュールでは信頼性が高いです
インポート関係のマッピング	90%+	動的インポートは見落とされます
古さの検出	70-80%	誤検出がよく発生します
循環依存関係の検出	85%+	複雑な循環を見落とす場合があります
クラス階層の抽出	85%+	ミックスインは扱いが難しい場合があります

このスキルを使用しない場合

• セキュリティ上重要な依存関係の監査：適切なセキュリティスキャンツールを使用してください
• 実行時の依存関係分析：プロファイラーまたは動的分析ツールを使用してください
• 複数言語のプロジェクト：手動分析のほうが正確な場合があります
• 動的なコードベース：プラグインアーキテクチャ、メタプログラミング

依存関係

このスキルには次のものが必要です。

1. mermaid-diagram-generator スキル：図の構文を生成するために利用可能である必要があります
2. Python 3.8+：使用する AST 解析機能に必要です
3. Git（任意）：Git の履歴を使用した、より高度な古さの検出に必要です

mermaid-diagram-generator が利用できない場合、このスキルは関係データをそのまま提供しますが、埋め込み図を生成できません。

PR レビューとの統合

PRでの図の表示方法

PRをレビューする際、このスキルはPRの説明に追加できる影響図を生成します。

PRの説明テンプレート：

## Architecture Impact



### Changed Dependencies

```mermaid
flowchart LR
    subgraph changed["Modified Modules"]
        style changed fill:#FFE4B5
        auth[auth/service.py]
        api[api/routes.py]
    end

    subgraph added["New Modules"]
        style added fill:#90EE90
        oauth[auth/oauth.py]
    end

    subgraph unchanged["Existing"]
        models[models/user.py]
        db[db/connection.py]
    end

    oauth --> auth
    auth --> models
    api --> auth
    api --> db
```

### Impact Summary

- **New modules**: 1 (oauth.py)
- **Modified modules**: 2 (auth/service.py, api/routes.py)
- **New dependencies**: oauth.py -> auth/service.py
- **Diagrams to update**: README.md (STALE)

CI統合の例

.github/workflows/pr-review.ymlに追加します。

- name: Check Diagram Staleness
  run: |
    # Claude Code analyzes and reports
    # Outputs: STALE diagrams that need updating
    # Generates: Suggested diagram updates

レビュアーのワークフロー

1. PRが作成される -> code-visualizerが影響図を生成します
2. レビュアーが確認する -> アーキテクチャの変更を視覚的に比較できます
3. 古さのチェック -> 既存の図に更新が必要な場合に警告します
4. 対応項目 -> 手動での更新が必要な図を一覧表示します

覚えておきましょう

このスキルは、開発者が忘れがちな作業を自動化します。

• 図をコードと同期させる
• アーキテクチャの変更を文書化する
• 依存関係への影響を把握する

目指すのは、常に最新の状態に保たれる図です。

ただし、制限事項を忘れないでください：古さの検出は概算です。正確さが重要な場合は、手動で確認してください。