Clean Code

Clean Code rules are tools, not dogma. If strictly applying a rule makes the code harder to understand, less simple, or more complex overall — DO NOT apply it.

Before applying any rule, ask: "Does this change make the code easier to understand for the next developer?" If the answer is NO or UNCERTAIN → skip the change, explain why.

Examples where NOT to apply Clean Code blindly:

• Extracting a 3-line helper function that will only ever be called once → adds indirection without clarity
• Renaming a well-understood abbreviation (url, id, i) to a verbose name → noise, not clarity
• Splitting a simple 25-line function that reads naturally as a single block → fragmentation hurts comprehension
• Applying polymorphism to a switch with 2 cases that will never grow → over-engineering
• Extracting a boolean condition into a named function when the condition is already obvious

The goal is a codebase that any developer can read fluently. Rules serve that goal — not the other way around.

Audit existing code:

/clean-code src/features/auth
/clean-code src/services/user.service.ts

Auto mode (no confirmation):

/clean-code -a src/features/auth

Report only (no fixes applied):

/clean-code -r src/features/auth

Guide mode (during code writing):

/clean-code --guide

→ Loads principles into context to guide the current writing session.

REVIEW mode (default)

Analyze existing code → identify violations → propose/apply fixes.

Workflow: step-01-analyze.md → step-02-fix.md

GUIDE mode (--guide)

Load Clean Code principles into context to guide a code writing session. No multi-step workflow — act as an active reference while the agent writes.

In guide mode:

1. Read references/clean-code-principles.md
2. Confirm: "Clean Code principles loaded. I'll apply naming, SOLID, DRY, small functions, and error handling rules — but only when they improve readability."
3. While writing: proactively flag violations before committing code

If --guide: → Load references/clean-code-principles.md + confirm guide mode. Done.

Otherwise: → Load steps/step-01-analyze.md

Trigger this skill when:

• An agent just wrote new code → /clean-code --guide before writing or review after
• Code reviewing a PR → /clean-code src/features/xxx
• Refactoring an existing module → /clean-code -a src/module
• Doubt about naming, function structure, or SOLID compliance

Principles covered:

• Intent-revealing naming (no magic numbers, consistent verb choices)
• Small functions, single responsibility, CQS, no hidden side effects
• Comments: when to write, when to delete
• DRY — duplicate elimination
• SOLID: SRP, OCP, LSP, ISP, DIP
• Law of Demeter — no train wrecks
• Error handling: exceptions vs return codes, never null
• Code smells: rigidity, fragility, needless complexity, Feature Envy, etc.