code-communities

コードのコミュニティ検出

コードベース内のアーキテクチャ上のクラスターとモジュール境界を 特定します。

使用しない場合

• 1 つのモジュールのインポートを確認する場合（cartograph:dependency-graph を使用）
• すでに決定済みのアーキテクチャを図にする場合（ cartograph:architecture-diagram を使用）

前提条件

このスキルでは、グラフデータを使用するために gauntlet プラグインが必要です。 インストール状況を確認します。

GRAPH_QUERY=$(find ~/.claude/plugins -name "graph_query.py" -path "*/gauntlet/*" 2>/dev/null | head -1)

gauntlet がインストールされていない場合：ディレクトリ構造の分析に切り替えます。 ファイルをディレクトリごとにグループ化し、インポート文を使ってモジュール境界を特定します。 ディレクトリ間の関係を示す Mermaid 図を生成します。

インストール済みだが graph.db がない場合：ユーザーに /gauntlet-graph build の実行を案内します。

手順

1. コミュニティ検出を実行する（gauntlet が必要）：

   python3 "$GRAPH_QUERY" --action communities
   

   代替手段（gauntlet がない場合）：ディレクトリ構造と ディレクトリをまたぐインポートを分析します。

   # Directory-level grouping
   find . -name "*.py" -not -path "*/node_modules/*" | \
       sed 's|/[^/]*$||' | sort | uniq -c | sort -rn
   
   # Cross-directory imports (rg preferred, grep fallback)
   if command -v rg &>/dev/null; then
     rg "^from |^import " --type py -l . | \
       xargs -I{} rg "^from \w+ import|^import \w+" {} --no-filename
   else
     grep -rh "^from \|^import " --include="*.py" .
   fi | sort | uniq -c | sort -rn | head -20
   

   トップレベルディレクトリごとにグループ化し、ディレクトリをまたぐ インポート数を数えて結合度を推定します。

2. クラスターを表示する：

   Community         | Nodes | Cohesion | Description
   auth              |    12 |    0.85  | Authentication module
   db                |     8 |    0.92  | Database access layer
   api/handlers      |    15 |    0.71  | API request handlers
   utils             |     6 |    0.45  | Shared utilities
   

3. 結合度に関する警告を表示する：コミュニティ間に 10 件を超える境界横断エッジがある場合は、強調表示します。

   WARNING: High coupling between 'auth' and 'api/handlers'
   (23 cross-community edges, severity: high)
   

4. Mermaid 図を生成する：

   flowchart TB
     subgraph auth[Auth Module - cohesion 0.85]
       verify_token
       check_permissions
     end
     subgraph db[DB Layer - cohesion 0.92]
       execute_query
       connection_pool
     end
     auth -->|"23 edges"| api
     db -->|"5 edges"| api
   

5. 改善案を提示する：

   • 凝集度が低い（<0.5）場合：「このモジュールを、より目的を絞った コンポーネントに分割することを検討してください」
   • 結合度が高い（>20 エッジ）場合：「直接的な依存関係を減らすために、 インターフェースの導入を検討してください」

アルゴリズム

エッジの種類ごとに重みを設定した Leiden アルゴリズムを使用します（igraph が利用可能な場合）。 それ以外の場合は、ファイルベースのグループ化に切り替えます。

エッジの種類	重み
CALLS	1.0
INHERITS	0.8
IMPLEMENTS	0.7
IMPORTS_FROM	0.5
TESTED_BY	0.4
CONTAINS	0.3

完了条件

• 検出された各クラスターについて、Community、Nodes、Cohesion、 Description の列を含むコミュニティテーブルが表示されている
• コミュニティのペア間に 10 件を超える境界横断エッジがある場合、 重要度ラベル付きの結合度警告が表示されている
• 各コミュニティに 1 つの subgraph を割り当て、 サブグラフのラベルに凝集度スコアを表示する Mermaid の flowchart TB が生成されている
• 凝集度が < 0.5、またはコミュニティ間の結合度が 20 エッジを超える コミュニティに対して、改善案が提示されている
• gauntlet がインストールされていない場合、ディレクトリ構造への フォールバックが実行され、グラフデータがないことがユーザーに伝えられている