refactor-advisor

Code Refactoring Advisor

Trigger Conditions

Activate this skill when the user requests refactoring code, optimizing code structure, improving code quality, or eliminating technical debt.

Workflow

Step 1: Scan the codebase

• Use grep/rg to scan the target directory and identify potential code smells
• Collect metrics such as file line counts, function lengths, and parameter counts
• Find duplicate code blocks (similarity > 80%)

Step 2: Classify code smells

Classify the discovered issues by severity:

Level	Meaning	Description
🔴 Critical	Must be fixed immediately	Affects maintainability and stability
🟡 Medium	Recommended to fix as soon as possible	Reduces code readability
🟢 Minor	Can be optimized when appropriate	Does not affect functionality but has room for improvement

Step 3: Prioritize

Sort comprehensively by the following dimensions:

1. Impact scope — The more times it is referenced/called, the higher the priority
2. Change frequency — Files frequently changed in git log take priority
3. Fix cost — Handle low-cost, high-benefit items first

Step 4: Output the refactoring plan

Common code smell detection

Code smell	Characteristics	Refactoring technique	Level
Long method	Function exceeds 50 lines	Extract Method	🔴
Large class	Class exceeds 300 lines	Extract Class	🔴
Duplicate code	Similar code blocks appear 3+ times	Extract common method	🔴
Long parameter list	Function has more than 4 parameters	Introduce Parameter Object	🟡
Deep nesting	if/for nested 3+ levels	Guard Clause	🟡
Magic number	Hard-coded numbers	Extract as constant	🟢
Long method chain	a.b.c.d.e	Extract intermediate variable	🟢
Global mutable state	Global variables modified in multiple places	Encapsulate as module / introduce dependency injection	🔴
Excessive coupling	Modules depend on each other	Dependency inversion, introduce interfaces	🟡

Output format

Full report template

# 代码重构报告

## 概要
- 扫描文件数：XXX
- 发现问题数：XX（🔴 X / 🟡 X / 🟢 X）
- 预估工作量：X 天

## 问题列表

### 问题 1：[问题标题]
- **📍 位置**：`src/services/user.ts:45-120`
- **🔍 问题**：该函数长达 75 行，包含 3 层嵌套，职责不单一
- **🛠️ 重构方案**：
  - 提取 `validateUserData()` 方法
  - 提取 `saveToDatabase()` 方法
  - 使用卫语句替代嵌套 if
- **⚠️ 风险评估**：
  - 该函数被 12 处调用，需全面回归测试
  - 建议先添加单元测试再重构
- **Before**：
  ```typescript
  function processUser(data) { /* 75行... */ }

• After：

  function processUser(data) {
    const validated = validateUserData(data);
    return saveToDatabase(validated);
  }
  

Refactoring roadmap

Phase	Content	Priority	Estimate
P1	Fix 🔴 Critical issues	High	2 days
P2	Handle 🟡 Medium issues	Medium	3 days
P3	Optimize 🟢 Minor issues	Low	1 day

## 注意事项
- 重构前确保有足够的测试覆盖
- 每次重构尽量小步提交，便于回滚
- 重构不应改变外部行为（行为保持）
- 大规模重构建议分阶段进行，每阶段独立可验证
- 关注重构过程中的性能回退风险