Clean Code Review

基于《代码整洁之道》原则，聚焦 7 个高收益检查维度。

Review Workflow

Review Progress:
- [ ] 1. Scan codebase: identify files to review
- [ ] 2. Check each dimension (naming, functions, DRY, YAGNI, magic numbers, clarity, conventions)
- [ ] 3. Rate severity (高/中/低) for each issue
- [ ] 4. Generate report sorted by severity

核心原则：功能保留

所有建议仅针对实现方式优化——绝不建议改变代码的功能、输出或行为。

Check Dimensions

1. 命名问题【有意义的命名】

检查标志：

• data1, temp, result, info, obj 等无意义命名
• 同一概念多种命名（get/fetch/retrieve 混用）

// ❌ 
const d = new Date();
const data1 = fetchUser();

// ✅ 
const currentDate = new Date();
const userProfile = fetchUser();

2. 函数问题【函数短小 + SRP】

检查标志：

• 函数超过 100 行
• 参数超过 3 个
• 函数做多件事

// ❌ 7 个参数
function processOrder(user, items, address, payment, discount, coupon, notes)

// ✅ 使用参数对象
interface OrderParams { user: User; items: Item[]; shipping: Address; payment: Payment }
function processOrder(params: OrderParams)

3. 重复问题【DRY】

检查标志：

• 相似的 if-else 结构
• 相似的数据转换/错误处理逻辑
• Copy-paste 痕迹

4. 过度设计【YAGNI】

检查标志：

• 从未为 true 的 if (config.legacyMode) 分支
• 只有一个实现的接口
• 无用的 try-catch 或 if-else

// ❌ YAGNI 违反：从未使用的兼容代码
if (config.legacyMode) {
  // 100 行兼容代码
}

5. 魔法数字【避免硬编码】

检查标志：

• 裸露数字无解释
• 硬编码字符串

// ❌ 
if (retryCount > 3) // 3 是什么？
setTimeout(fn, 86400000) // 这是多久？

// ✅ 
const MAX_RETRY_COUNT = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

6. 结构清晰度【可读性优先】

检查标志：

• 嵌套三元运算符
• 过度紧凑的单行代码
• 过深的条件嵌套（> 3 层）

// ❌ 嵌套三元
const status = a ? (b ? 'x' : 'y') : (c ? 'z' : 'w');

// ✅ 使用 switch 或 if/else
function getStatus(a, b, c) {
  if (a) return b ? 'x' : 'y';
  return c ? 'z' : 'w';
}

7. 项目规范【一致性】

检查标志：

• import 顺序混乱（外部库 vs 内部模块）
• 函数声明风格不一致
• 命名规范不统一（camelCase vs snake_case 混用）

// ❌ 风格不一致
import { api } from './api'
import axios from 'axios'  // 外部库应在前
const handle_click = () => { ... }  // 命名风格混用

// ✅ 统一风格
import axios from 'axios'
import { api } from './api'
function handleClick(): void { ... }

[!TIP] 项目规范应参照 CLAUDE.md AGENTS.md 或项目约定的编码标准。

Severity Levels

Output Format

### [问题类型]: [简述]

- **原则**: [Clean Code 原则]
- **位置**: `文件:行号`
- **级别**: 高/中/低
- **问题**: [具体描述]
- **建议**: [修复方向]

References

Detailed examples: See references/detailed-examples.md

• 各维度的完整案例（命名、函数、DRY、YAGNI、魔法数字）

Language patterns: See references/language-patterns.md

• TypeScript/JavaScript 常见问题
• Python 常见问题
• Go 常见问题

Multi-Agent Parallel

按以下维度拆分给多 agent 并行：

1. 按检查维度 – 7 维度各一个 agent
2. 按模块/目录 – 不同模块各一个 agent
3. 按语言 – TypeScript、Python、Go 各一个 agent
4. 按文件类型 – 组件、hooks、工具函数、类型定义

示例：/clean-code-reviewer --scope=components 或 --dimension=naming

汇总时需去重和统一严重程度评定。