code-communities

代码社区检测

识别代码库中的架构集群和模块边界。

不适用场景

• 分析单个模块的导入关系（使用 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 条边）：“考虑引入接口以减少直接依赖”

算法

如果 igraph 可用，则使用 Leiden 算法，并为不同边类型设置特定权重。否则改用 基于文件的分组方式。

边类型	权重
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 条的社区对显示耦合警告，并标注严重程度
• 生成 Mermaid flowchart TB，每个社区对应一个 subgraph， 并在子图标签中显示内聚度得分
• 为内聚度 < 0.5 或跨社区耦合超过 20 条边的社区提供改进建议
• 如果未安装 gauntlet，则运行目录结构备用方案，并告知用户缺少图数据