Clean Code Standards Skill

A Claude Code skill that enforces pragmatic clean code principles — single responsibility, meaningful naming, minimal complexity, and consistent patterns — to keep your codebase readable, maintainable, and refactoring-friendly.

When to Use This Skill

Choose this skill when:

• Writing new functions, classes, or modules that others will maintain
• Refactoring existing code that has grown complex or hard to understand
• Reviewing pull requests for readability and maintainability
• Establishing coding standards for a new project or team
• Reducing technical debt by improving code structure systematically

Consider alternatives when:

• Writing throwaway scripts or one-time data migrations
• Optimizing for raw performance where readability trade-offs are acceptable
• Working in a codebase with established style guides already enforced by linters

Quick Start

Copy
# Add to your Claude Code project
claude mcp add clean-code

# Review a file for clean code violations
claude "review src/services/userService.ts for clean code principles"

# Refactor a complex function
claude "refactor this function following clean code standards"

Copy
# .claude/skills/clean-code.yml
name: clean-code
description: Enforce pragmatic clean code principles
triggers:
  - "clean code review"
  - "refactor for readability"
  - "code quality check"
config:
  strictness: standard
  max_function_lines: 30
  max_parameters: 3

Core Concepts

Principles

Principle	Rule	Example
SRP	Each function does ONE thing	calculateTotal() not calculateTotalAndSendEmail()
DRY	Extract repeated logic into shared functions	Shared validation instead of copy-pasted checks
KISS	Choose the simplest working solution	Array filter over hand-rolled loop with flags
YAGNI	Don't build features you don't need yet	No abstract factory for a single implementation
Boy Scout Rule	Leave code cleaner than you found it	Fix a nearby naming issue when editing a function

Naming Conventions

Copy
// BAD: Unclear abbreviations and generic names
function proc(d: any) {
  const t = d.map((i: any) => i.v * i.q);
  return t.reduce((a: number, b: number) => a + b, 0);
}

// GOOD: Self-documenting names
function calculateOrderTotal(lineItems: LineItem[]): number {
  const subtotals = lineItems.map(item => item.price * item.quantity);
  return subtotals.reduce((sum, subtotal) => sum + subtotal, 0);
}

// BAD: Boolean with unclear meaning
let flag = true;
if (flag) { sendNotification(); }

// GOOD: Boolean reads as a question
let shouldNotifyUser = true;
if (shouldNotifyUser) { sendNotification(); }

// BAD: Function name doesn't describe what it returns
function check(user: User) { return user.age >= 18; }

// GOOD: Predicate function reads naturally
function isEligibleForAccount(user: User) { return user.age >= 18; }

Function Structure

Copy
// BAD: Function does too many things
async function handleRegistration(formData: FormData) {
  // validate... 20 lines
  // create user... 15 lines
  // send email... 10 lines
  // log activity... 8 lines
  // return response... 5 lines
}

// GOOD: Each function has one responsibility
async function handleRegistration(formData: FormData) {
  const validData = validateRegistrationForm(formData);
  const user = await createUserAccount(validData);
  await sendWelcomeEmail(user);
  await logRegistrationActivity(user);
  return { success: true, userId: user.id };
}

Configuration

Parameter	Type	Default	Description
strictness	string	"standard"	Enforcement level: relaxed, standard, strict
max_function_lines	number	30	Maximum lines per function before flagging
max_parameters	number	3	Maximum function parameters before suggesting an options object
max_nesting_depth	number	3	Maximum nesting levels (if/for/while)
naming_convention	string	"camelCase"	Variable naming: camelCase, snake_case, PascalCase
require_early_returns	boolean	true	Prefer guard clauses over nested if-else
max_file_lines	number	300	Maximum lines per file before suggesting a split

Best Practices

1. Use guard clauses to reduce nesting — flip negative conditions into early returns at the top of functions; this flattens the code and makes the happy path easier to follow.

2. Name variables and functions to eliminate the need for comments — if you need a comment to explain what code does, consider renaming variables or extracting a well-named function instead.

3. Limit function parameters to three or fewer — when a function needs more inputs, group related parameters into an options object; this improves readability and makes the function easier to extend.

4. Keep functions under 30 lines — this is a guideline, not a hard rule, but consistently long functions signal that the function is doing too much and should be broken apart.

5. Prefer composition over inheritance — build behavior by composing small, focused functions rather than creating deep inheritance hierarchies; composition is more flexible and easier to test.

Common Issues

Team disagrees on what "clean" means — Clean code is subjective. Align on specific, measurable rules (max function length, naming conventions, nesting depth) rather than abstract principles. Configure the skill with your team's agreed-upon thresholds.

Over-abstracting to satisfy DRY — Extracting a shared function for two slightly similar code blocks can create a fragile abstraction that's harder to maintain than the duplication. Only extract when three or more usages exist and the shared logic is genuinely identical.

Refactoring breaks existing tests — Clean code refactoring should not change behavior. Run your test suite after each refactoring step, and if tests break, you've changed behavior, not just structure. Use version control to compare before and after.