# Clean Code > Refactor existing code with behavior-preserving Clean Code practices. Use for local naming, readability, duplication, or structure problems; use architecture-lens for module boundary decisions. - Skill: `robsonrung/clean-code` (Agent Skill) - Install (CLI): `npx skillmds@latest add robsonrung/clean-code` - Raw SKILL.md: https://api.skillmd.com/api/skills/robsonrung/clean-code/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: robsonrung (https://skillmd.com/u/robsonrung) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robsonrung/clean-code --- # Clean Code Improve existing code so it is easier to read, safer to change, and simpler to test while preserving behavior by default. ## Operating Rules - Stay behavior-preserving unless the user explicitly asks for a behavior change: keep public APIs, side effects, error behavior and messages, performance characteristics, observable timing assumptions, edge cases, and data shapes stable unless changing them is part of the request. - Prefer the smallest useful change over a broad rewrite. - Improve names before adding comments or abstractions. - Keep domain language visible. Do not hide business rules behind generic helpers. - Remove duplication only when duplicated code represents the same concept and has the same reason to change. - Avoid new patterns, dependencies, formatting churn, and module moves unless they clearly reduce real complexity. - If tests are missing or weak and the refactor is risky, improve existing tests, or add or suggest focused characterization tests as the behavior-preserving net, before changing structure deeply. For legacy code with no net to stand on, build that net first via `safe-incremental-coding`, then return here. ## Workflow 1. Understand the code. - Identify the code's purpose, public interfaces, inputs, outputs, side effects, invariants, framework constraints, and existing tests. - If the user asked for review only, report findings without editing. 2. Classify the work. - Use `local cleanup` for naming, constants, simple extraction, and control-flow clarity. - Use `refactor` for behavior-preserving structural changes. - Use `bug fix plus cleanup` only when the user allowed a behavior change or the requested bug is clear. - Treat `redesign` as out of scope unless the user explicitly asked for it. - If the safe path requires redesign, dependency changes, or behavior changes beyond the request, stop and report the option to the user instead of proceeding. 3. Choose improvements. - Rename unclear identifiers. - Extract meaningful constants for magic values. - Extract small helpers when they name a real step in the domain. - Flatten nested control flow with guard clauses. - Separate parsing, validation, business rules, persistence, formatting, orchestration, and side effects when they are tangled. - Improve error handling consistency without weakening existing errors. 4. Edit safely. - Keep changes scoped to the requested code path. - Make one logical improvement at a time when possible. - Re-verify the change is behavior-preserving per the rule above. - Do not replace clear code with clever code. 5. Validate. - Run the most relevant existing tests or checks when available. - If tests cannot be run, say why. - Re-check that names express intent, functions are focused, abstraction levels are consistent, comments remain accurate, and side effects are visible. ## Smell Checklist Diagnose by name. Before you change anything, say which smell you see — naming the smell is what makes the fix obvious and keeps the change behavior-preserving. Each smell below is a term of art; use the term, don't paraphrase it. - **Naming smells**: unclear names, magic values. - **Function smells**: long functions, deep nesting, complex booleans, flag arguments, inconsistent abstraction levels. - **Responsibility smells**: mixed responsibilities, large classes, hidden mutations. - **Data smells**: primitive obsession, data clumps, long parameter lists. - **Duplication smells**: duplicated logic (only when it is the same concept with the same reason to change). - **Comment smells**: noisy comments that repeat or excuse the code. - **Safety smells**: inconsistent error handling, brittle or missing tests. State the smell, then apply the matching improvement. "This has **primitive obsession** and a **data clump** in the parameters" is the kind of sentence that should precede each edit. ## Naming Guide - Prefer intent-revealing names such as `elapsedTimeInDays`, `customerRepository`, `isEligibleForDiscount`, `calculateInvoiceTotal`, and `parsePaymentRequest`. - Avoid vague names such as `data`, `info`, `manager`, `processor`, and `helper` unless the domain really uses that term. - Name booleans so they read naturally: `isActive`, `hasPermission`, `canRetry`, `shouldNotifyCustomer`. - Name functions with verbs when practical: `calculateTotal`, `validateRequest`, `loadCustomer`, `sendReceipt`, `formatCurrency`. ## Comments Diagnose every comment as an **earned comment** or noise. A comment is earned only when it carries what the code cannot — a business rule, external constraint, security concern, performance tradeoff, historical context, or non-obvious decision. Say it while editing: "this is an **earned comment** — it records the auth constraint the parameter name can't." Everything else is noise: comments that repeat the code, restate the obvious, excuse code that should be renamed or extracted, or read like AI slop (apologetic, placeholder, or narrate-the-diff lines a senior would never leave). - Keep **earned comments**: business rules, external constraints, security concerns, performance tradeoffs, historical context, non-obvious decisions. - Cut the unearned: code-restating, obvious, outdated, or AI-slop comments. ## Output Contract When returning results, include: - `summary`: what was improved. - `key_improvements`: the most important readability, maintainability, safety, or testability changes. - `behavior_changes`: state `none` when behavior was preserved; otherwise explain exactly what changed and why. - `validation`: tests or checks run, with results. - `risks`: missing tests, unclear requirements, framework constraints, or areas needing extra review. For review-only tasks, lead with findings ordered by severity and include file and line references where possible. ## Gotcha Do not quote or reconstruct source text from the book this skill distills.