Clean Code Review Guide

The problem

• Reviews often stop at code that compiles, while vague names, long functions, deep nesting, magic numbers, comments that restate the code, and broken multi-file changes keep accumulating.
• This skill turns Clean Code principles into a checkable checklist, so review and self-testing have a consistent standard instead of relying only on instinct.

How it works

• Principles: It checks whether functions and classes follow SRP, DRY, KISS, YAGNI, and the Boy Scout Rule, asking whether each unit does one thing, avoids duplication, and resists over-design.
• Naming: It evaluates variables, functions, booleans, constants, classes, and enums for intent, replacing weak names like tmp, data, and flag.
• Functions: It looks at length, argument count, abstraction level, and side effects, favoring guard clauses, early returns, and options objects to reduce nesting and caller complexity.
• Structure: It flags anti-patterns such as God functions, one-function utils.ts files, premature abstraction, copy-paste logic, stringly-typed code, and callback hell, then suggests extraction, composition, and discriminated unions.
• Pre-edit safety: Before changing a file, it checks what imports it, what it imports, which tests cover it, and whether it is a shared component, then updates dependents, tests, and types in the same task.
• Completion checks: It verifies the goal, edited files, compilation, clean lint or type checks, and missing edge cases.

Boundaries and cautions

• It fits code review, refactoring, multi-file changes, and quality constraints in AI-assisted development.
• It is a rules checklist, not a substitute for architecture, domain modeling, or performance profiling.
• Hard rules such as 20-line functions and 3-argument limits should be read with team conventions in mind; if business logic is inherently complex, split and rename first instead of mechanically forcing small pieces.
• The references to Anti-Patterns, Code Smells, and Refactoring Catalog can guide deeper study.