Architecture Review

定期扫描代码库架构质量，识别循环依赖、死代码、过大模块和高圈复杂度，生成报告指导重构优先级。

借鉴来源：improve-codebase-architecture + CodeGraphContext 死代码检测

定期对代码库做架构质量扫描，识别腐烂信号（泥球、反循环依赖、死代码、圈复杂度超标）。

核心理念：架构问题不会一夜发生，但会日积月累。定期扫描比一次性重构便宜10倍。

---

触发条件

满足以下任一场景时激活：

• 用户要求"审计一下这个项目"、"看看代码有没有问题"
• 进入一个陌生的代码库
• 代码库超过 6 个月没做架构审查
• 用户要求重构但没明确范围
• 大版本发布前的质量检查

---

扫描维度

1. 模块结构（高优先级）

检查项：

• 模块之间是否有明确的层次关系（Domain → Application → Infrastructure）
• 是否存在循环依赖（A→B→C→A）
• 是否有超大的 God Module（>3000 行）

工具：

bash

# 检查循环依赖
npm run list:deps 2>/dev/null || npx madge --circular src/

# 统计模块行数
Get-ChildItem -Recurse src/**/*.ts | Get-Content | Measure-Object -Line

2. 死代码检测（高优先级）

检查项：

• 未被调用的函数/方法
• 未被使用的变量/常量
• 已被注释掉的代码（长期积累）
• 旧的 API 端点（无人调用但仍在暴露）

工具：

bash

# TypeScript/JavaScript
npx ts-prune 2>/dev/null || npx madge --not --extensions ts,tsx

# Python
vulture . --min-confidence 80

# Go
staticcheck ./... 2>/dev/null | grep "is never used"

# 通用（基于 tree-sitter 调用图）
# codegraph-index skill 已构建调用图，孤立的叶子节点 = 潜在死代码

3. 圈复杂度检测（中优先级）

检查项：

• 函数/方法圈复杂度 > 10（难以测试，容易出 bug）
• 圈复杂度 > 20 的函数必须拆分

工具：

bash

# TypeScript/JavaScript
npx complexity-report --dest ./complexity-report.html 2>/dev/null

# Python
radon cc -a -s src/

# 通用（Python 脚本）
python3 -c "
import os, ast
def cyclomatic(func_def):
    score = 1
    for node in ast.walk(func_def):
        if isinstance(node, (ast.If, ast.While, ast.For, ast.ExceptHandler)):
            score += 1
        elif isinstance(node, ast.BoolOp):
            score += len(node.values) - 1
    return score
# 输出复杂度超标的函数
"

4. 接口设计（边界清晰性）

检查项：

• 模块间接口是否有清晰的契约（类型定义/文档）
• 是否存在隐式依赖（全局状态、Singleton 滥用）

工具：

bash

# 检查全局状态滥用
grep -r "global\." src/ --include="*.ts" | head -20
grep -r "window\." src/ --include="*.ts" | head -20

5. 技术债务可视化（长期追踪）

检查项：

• 过期的依赖包（有安全漏洞或已废弃）
• 过时的 API 用法（如 Vue 2 Options API 项目中发现大量 Composition API）

工具：

bash

# 依赖检查
npm outdated 2>/dev/null
npx npm-check-updates 2>/dev/null

---

输出格式

markdown

## 架构审查报告

### 模块结构
| 问题 | 位置 | 严重度 |
|------|------|--------|
| 循环依赖 A→B→C→A | src/a/, src/b/ | 🔴 高 |
| God Module | src/core.js (3500行) | 🟡 中 |

### 死代码
| 函数/变量 | 位置 | 建议 |
|-----------|------|------|
| unusedFunc | lib/utils.ts:42 | 删除 |
| oldAPI | api/routes.js:15 | 移除端点 |

### 圈复杂度超标
| 函数 | 位置 | 复杂度 | 建议 |
|------|------|--------|------|
| processPayment | services/pay.ts:88 | 18 | 拆分为3个函数 |

### 技术债务
| 类型 | 描述 | 建议 |
|------|------|------|
| 过期依赖 | lodash@3.2.0 | 升级到 4.x |
| 废弃 API | /api/v1/legacy | 移除或迁移 |

### 优先级排序
1. [立即处理] 循环依赖（影响所有新功能开发）
2. [本周处理] God Module 重构
3. [本月处理] 死代码清理
4. [下季度] 依赖升级

---

与其他 Skill 的配合

• codegraph-index：先做索引，再查调用图和符号关系
• refactoring：发现架构问题后，用 refactoring skill 执行重构
• skill-compounding：如果某类架构问题反复出现，提取为检查清单 Skill

---

下一跳（Skill 链式调用）

architecture-review 是架构质量审查技能，审查完成后按以下路径调用：

• 发现循环依赖、God Module 等架构问题 → 调用 refactoring 做重构
• 同时需要安全/性能/代码质量等专项审查 → 调用 agent-teams
• 只有轻微问题 → 直接输出报告，进入下一阶段

---

触发命令

"审计一下这个项目"、"看看代码有没有问题"、"做一次架构审查"、"检查死代码"