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.