reviewing-readability

thkt's avatarfrom thkt

Code readability review based on "The Art of Readable Code" and Miller's Law (7±2). Triggers: 可読性, 理解しやすい, わかりやすい, 明確, 命名, 変数名, 関数名, ネスト, 深いネスト, 関数設計, コメント, 複雑, 難しい, 難読, Miller's Law, ミラーの法則, 認知負荷, AI-generated, 過剰設計.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates code readability audits based on the principles of 'The Art of Readable Code' and Miller's Law. It helps developers minimize cognitive load by identifying vague naming, deep nesting, and over-engineered logic, ensuring that source code is not just functional, but easy for humans to understand and maintain.

Use Cases

  • Refactoring Legacy Code: Automatically identify and flatten deeply nested logic (exceeding 3 levels) using guard clauses or function extraction to improve code flow.
  • Naming Convention Optimization: Scan for vague identifiers like 'data' or 'process' and suggest intent-revealing names that improve self-documentation.
  • Cognitive Load Management: Apply Miller's Law (7±2) to evaluate function complexity and parameter counts, ensuring logic remains within the limits of human short-term memory.
  • AI-Generated Code Cleanup: Review and simplify verbose or over-engineered code produced by AI assistants to meet professional readability and architectural standards.
  • Comment Quality Control: Detect and remove redundant or self-evident comments while highlighting areas where documentation is actually needed for complex logic.
namereviewing-readability
description>
allowed-tools[Read, Grep, Glob, Task]
agentreadability-reviewer
contextfork
user-invocablefalse

Readability Review

Detection

ID Pattern Fix
RD1 processData() (vague) validateUserEmail()
RD1 Misleading identifiers Names reveal intent
RD2 Nesting > 3 levels Guard clauses, extract functions
RD2 Function > 30 lines Decompose
RD3 Comment: // increment i Delete (self-evident)
RD3 Comment: // TODO: fix later Create issue or fix now
RD4 Interface for single impl Remove until 2nd impl
RD4 Class for stateless logic Pure function
RD5 > 5 function parameters Config object or decompose

Thresholds

Metric Recommended Maximum
Function lines ≤30 50
Nesting depth ≤3 4
Function arguments ≤3 5

References

Topic File
Control Flow references/control-flow.md
Comments references/comments-clarity.md
AI Antipatterns references/ai-antipatterns.md
Naming references/naming.md