Clean Code - Pragmatic AI Coding Standards

CRITICAL SKILL - Be concise, direct, and solution-focused.

Core Principles

Principle

Rule

SRP

Single Responsibility - each function/class does ONE thing

DRY

Don't Repeat Yourself - extract duplicates, reuse

KISS

Keep It Simple - simplest solution that works

YAGNI

You Aren't Gonna Need It - don't build unused features

Boy Scout

Leave code cleaner than you found it

Naming Rules

Element

Convention

Variables

Reveal intent: userCount not n

Functions

Verb + noun: getUserById() not user()

Booleans

Question form: isActive, hasPermission, canEdit

Constants

SCREAMING_SNAKE: MAX_RETRY_COUNT

Rule: If you need a comment to explain a name, rename it.

Function Rules

Rule

Description

Small

Max 20 lines, ideally 5-10

One Thing

Does one thing, does it well

One Level

One level of abstraction per function

Few Args

Max 3 arguments, prefer 0-2

No Side Effects

Don't mutate inputs unexpectedly

Code Structure

Pattern

Apply

Guard Clauses

Early returns for edge cases

Flat > Nested

Avoid deep nesting (max 2 levels)

Composition

Small functions composed together

Colocation

Keep related code close

AI Coding Style

Situation

Action

User asks for feature

Write it directly

User reports bug

Fix it, don't explain

No clear requirement

Ask, don't assume

Anti-Patterns (DON'T)

❌ Pattern

✅ Fix

Comment every line

Delete obvious comments

Helper for one-liner

Inline the code

Factory for 2 objects

Direct instantiation

utils.ts with 1 function

Put code where used

"First we import..."

Just write code

Deep nesting

Guard clauses

Magic numbers

Named constants

God functions

Split by responsibility

🔴 Before Editing ANY File (THINK FIRST!)

Before changing a file, ask yourself:

Question

Why

What imports this file?

They might break

What does this file import?

Interface changes

What tests cover this?

Tests might fail

Is this a shared component?

Multiple places affected

Quick Check:

File to edit: UserService.ts

└── Who imports this? → UserController.ts, AuthController.ts

└── Do they need changes too? → Check function signatures

🔴 Rule: Edit the file + all dependent files in the SAME task.

🔴 Never leave broken imports or missing updates.

Summary

Do

Don't

Write code directly

Write tutorials

Let code self-document

Add obvious comments

Fix bugs immediately

Explain the fix first

Inline small things

Create unnecessary files

Name things clearly

Use abbreviations

Keep functions small

Write 100+ line functions

Remember: The user wants working code, not a programming lesson.

🔴 Self-Check Before Completing (MANDATORY)

Before saying "task complete", verify:

Check

Question

✅ Goal met?

Did I do exactly what user asked?

✅ Files edited?

Did I modify all necessary files?

✅ Code works?

Did I test/verify the change?

✅ No errors?

Lint and TypeScript pass?

✅ Nothing forgotten?

Any edge cases missed?

🔴 Rule: If ANY check fails, fix it before completing.

Verification Scripts (MANDATORY)

🔴 CRITICAL: Each agent runs ONLY their own skill's scripts after completing work.

Agent → Script Mapping

Agent

Script

Command

frontend-specialist

UX Audit

python ~/.claude/skills/frontend-design/scripts/ux_audit.py .

frontend-specialist

A11y Check

python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .

backend-specialist

API Validator

python ~/.claude/skills/api-patterns/scripts/api_validator.py .

mobile-developer

Mobile Audit

python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .

database-architect

Schema Validate

python ~/.claude/skills/database-design/scripts/schema_validator.py .

security-auditor

Security Scan

python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .

seo-specialist

SEO Check

python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .

seo-specialist

GEO Check

python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .

performance-optimizer

Lighthouse

python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>

test-engineer

Test Runner

python ~/.claude/skills/testing-patterns/scripts/test_runner.py .

test-engineer

Playwright

python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>

Any agent

Lint Check

python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .

Any agent

Type Coverage

python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .

Any agent

i18n Check

python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .

❌ WRONG: test-engineer running ux_audit.py

✅ CORRECT: frontend-specialist running ux_audit.py

🔴 Script Output Handling (READ → SUMMARIZE → ASK)

When running a validation script, you MUST:

• Run the script and capture ALL output

• Parse the output - identify errors, warnings, and passes

• Summarize to user in this format:

## Script Results: [script_name.py]

### ❌ Errors Found (X items)

- [File:Line] Error description 1

- [File:Line] Error description 2

### ⚠️ Warnings (Y items)

- [File:Line] Warning description

### ✅ Passed (Z items)

- Check 1 passed

- Check 2 passed

**Should I fix the X errors?**

• Wait for user confirmation before fixing

• After fixing → Re-run script to confirm

🔴 VIOLATION: Running script and ignoring output = FAILED task.

🔴 VIOLATION: Auto-fixing without asking = Not allowed.

🔴 Rule: Always READ output → SUMMARIZE → ASK → then fix.