Clean Code Reviewer

Clean Code Review

Grounded in the principles of Clean Code (Robert C. Martin), focused on 7 high-leverage check dimensions.

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.

Core Principle: Behavior Preservation

Every suggestion targets only how the code is implemented — never suggest changing the code's functionality, output, or behavior.

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. Naming Problems (Meaningful Names)

Detection signals:

• Meaningless names like data1, temp, result, info, obj
• Multiple names for the same concept (mixing get/fetch/retrieve)
• Booleans missing an is/has/can/should prefix

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

2. Function Problems (Small Functions + SRP)

Detection signals:

• Function exceeds 100 lines
• More than 3 parameters (use a parameter object instead)
• Function does multiple things (violates Single Responsibility)
• Function name implies read-only but it has side effects

3. Duplication (DRY)

Detection signals:

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

4. Over-Engineering (YAGNI)

Detection signals:

• if (config.legacyMode) branches that are never true (dead code)
• Interfaces with only one implementation
• Over-defensive / useless try-catch or if-else

5. Magic Numbers (Avoid Hardcoding)

Detection signals:

• Bare numbers with no explanation (retryCount > 3, setTimeout(fn, 86400000))
• Hardcoded strings, status codes, time constants

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

6. Structural Clarity (Readability First)

Detection signals:

• Nested ternary operators
• Overly compact one-liners
• Deep conditional nesting (> 3 levels) — prefer guard clauses with early returns

7. Project Conventions (Consistency)

Detection signals:

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

[!TIP] Source project conventions from the project root CLAUDE.md / AGENTS.md, plus linter configs (.eslintrc, .prettierrc, ruff/flake8 config).

Severity Levels

Use 高 / 中 / 低 as the literal severity labels in the report — they are part of the output contract.

Output

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
<the highest-leverage maintainability risk, one paragraph>

## Findings

### P1: <issue title>
- **原则**: <命名 / 单一职责 / DRY / YAGNI / 魔法数字 / 结构清晰度 / 项目规范>
- **位置**: `<file>:<line>`
- **级别**: 高 / 中 / 低
- **问题**: <what makes the code harder to read, change, or test>
- **建议**: <behavior-preserving refactor direction>
- **Why now**: <risk if left as-is>

## Good Patterns To Keep
- <implementation choice worth preserving>

## Test Gaps
- <tests needed to protect behavior during the refactor>

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 (naming, functions, DRY, YAGNI, magic numbers); read when you need richer cases or are unsure a finding qualifies.
• references/language-patterns.md — language-specific smells for TypeScript/JavaScript, Python, and 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. By check dimension — one agent per dimension (7 total)
2. By module/directory — one agent per module
3. By language — one agent each for TypeScript, Python, Go
4. By file type — components, hooks, utility functions, type definitions

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 (consumer API, data flow, testability) → component-diagnosis / react-component-diagnosis.