clean-code-reviewer

Clean Code Review

Based on the principles of "Clean Code", focus on 7 high-yield inspection dimensions.

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

Core principle: Preserve functionality

All suggestions are only forimplementationoptimization—never suggest changing the functionality, output, or behavior of the code.

Check Dimensions

1. Naming issues [Meaningful names]

Inspection signs:

• data1, temp, result, info, obj and other meaningless names
• Multiple names for the same concept (get/fetch/retrieve mixed use)

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

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

2. Function issues [Small functions + SRP]

Inspection signs:

• Function exceeds 100 lines
• More than 3 parameters
• Function does multiple things

// ❌ 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. Duplication issues [DRY]

Inspection signs:

• Similar if-else structures
• Similar data transformation/error handling logic
• Copy-paste traces

4. Overengineering [YAGNI]

Inspection signs:

• Never true if (config.legacyMode) branch
• Interfaces with only one implementation
• Useless try-catch or if-else

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

5. Magic numbers [Avoid hardcoding]

Inspection signs:

• Bare numbers with no explanation
• Hardcoded strings

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

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

6. Structural clarity [Readability first]

Inspection signs:

• Nested ternary operators
• Overly compact one-liners
• Overly deep conditional nesting (> 3 levels)

// ❌ 嵌套三元
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. Project conventions [Consistency]

Inspection signs:

• Disordered import order (external libraries vs internal modules)
• Inconsistent function declaration style
• Inconsistent naming conventions (camelCase vs snake_case mixed use)

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

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

[!TIP] Project conventions should refer to CLAUDE.md AGENTS.md or the coding standards agreed upon by the project.

Severity Levels

Level	Standard
High	Affects maintainability/readability, should be fixed immediately
Medium	Room for improvement, recommended to fix
Low	Code smell, optional optimization

Output Format

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

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

References

Detailed examples: See references/detailed-examples.md

• Complete cases for each dimension (naming, functions, DRY, YAGNI, magic numbers)

Language patterns: See references/language-patterns.md

• Common TypeScript/JavaScript issues
• Common Python issues
• Common Go issues

Multi-Agent Parallel

Split to multiple agents for parallelism according to the following dimensions:

1. By inspection dimension - one agent for each of the 7 dimensions
2. By module/directory - one agent for each different module
3. By language - one agent each for TypeScript, Python, and Go
4. By file type - components, hooks, utility functions, type definitions

Example:/clean-code-reviewer --scope=components or --dimension=naming

During aggregation, deduplication and unified severity rating are required.