Clean Code Review

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

Review Workflow

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

Severity reflects maintainability impact, so the report leads with what to fix first. Prefer the few highest-leverage findings over an exhaustive list of 低 smells — a signal-dense report the human acts on beats a long one they ignore.

When the codebase is primarily Python or Go, consult references/language-patterns.md for language-specific smells before finalizing.

核心原则：功能保留

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

Check Dimensions

These are the detection signals and thresholds — the load-bearing decision criteria. Full ❌/✅ worked examples for dimensions 1–5 live in references/detailed-examples.md; read it when you need richer cases or are unsure a finding qualifies.

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

检查标志：

• data1, temp, result, info, obj 等无意义命名
• 同一概念多种命名（get/fetch/retrieve 混用）
• 布尔值缺少 is/has/can/should 前缀

const data1 = fetchUser();   // ❌  →  const userProfile = fetchUser();  // ✅

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

检查标志：

• 函数超过 100 行
• 参数超过 3 个（改用参数对象）
• 函数做多件事（违反单一职责）
• 函数名暗示只读却有副作用

3. 重复问题【DRY】

检查标志：

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

4. 过度设计【YAGNI】

检查标志：

• 从未为 true 的 if (config.legacyMode) 分支（死代码）
• 只有一个实现的接口
• 过度防御 / 无用的 try-catch 或 if-else

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

检查标志：

• 裸露数字无解释（retryCount > 3、setTimeout(fn, 86400000)）
• 硬编码字符串、状态码、时间常量

if (retryCount > 3) {}   // ❌  →  const MAX_RETRY_COUNT = 3; if (retryCount > MAX_RETRY_COUNT) {}  // ✅

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

检查标志：

• 嵌套三元运算符
• 过度紧凑的单行代码
• 过深的条件嵌套（> 3 层）——优先用 guard clauses 早返回

7. 项目规范【一致性】

检查标志：

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

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

Severity Levels

级别	标准
高	影响可维护性/可读性，应立即修复
中	有改进空间，建议修复
低	代码气味，可选优化

Output Format

Emit a Summary first, then P-numbered findings sorted by severity, then patterns worth keeping and any tests needed to refactor safely. Skeleton (read references/output-template.md before finalizing — it is the full, canonical shape):

# Clean Code Review: <scope>

## Summary
<最高杠杆的可维护性风险，一段话>

## Findings

### P1: <问题简述>
- **原则**: <命名 / 单一职责 / DRY / YAGNI / 魔法数字 / 结构清晰度 / 项目规范>
- **位置**: `文件:行号`
- **级别**: 高 / 中 / 低
- **问题**: <为什么让代码更难读、改、测>
- **建议**: <保留行为的重构方向>
- **Why now**: <不改的风险>

## Good Patterns To Keep
- <值得保留的实现选择>

## Test Gaps
- <重构期间为保护行为所需的测试>

References

• references/output-template.md — the full canonical report shape; read before finalizing output.
• references/detailed-examples.md — full ❌/✅ worked cases for the 5 core dimensions (命名、函数、DRY、YAGNI、魔法数字); read when you need richer cases or are unsure a finding qualifies.
• references/language-patterns.md — TypeScript/JavaScript、Python、Go 各自的语言特定坏味道; consult when the codebase is primarily one of these languages.

Multi-Agent Parallel

When parallelizing across subagents, split the work along one axis, then dedupe and reconcile severity ratings when merging:

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

Use a different skill when

This skill reports file/function-level Clean Code findings and does not modify code. Route elsewhere when:

• Architecture / module boundaries / abstraction quality (system-level, APoSD) → hai-architecture.
• Eliminating any / TypeScript type safety → ts-type-safety-reviewer.
• Actually applying the refactors (not just reporting) → code-simplifier.
• React component design (使用者 API、数据流、可测试性) → component-diagnosis / react-component-diagnosis.