clean-code

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 .agent/skills/frontend-design/scripts/ux_audit.py .
frontend-specialist	A11y Check	python .agent/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialist	API Validator	python .agent/skills/api-patterns/scripts/api_validator.py .
mobile-developer	Mobile Audit	python .agent/skills/mobile-design/scripts/mobile_audit.py .
database-architect	Schema Validate	python .agent/skills/database-design/scripts/schema_validator.py .
security-auditor	Security Scan	python .agent/skills/vulnerability-scanner/scripts/security_scan.py .
seo-specialist	SEO Check	python .agent/skills/seo-fundamentals/scripts/seo_checker.py .
seo-specialist	GEO Check	python .agent/skills/geo-fundamentals/scripts/geo_checker.py .
performance-optimizer	Lighthouse	python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>
test-engineer	Test Runner	python .agent/skills/testing-patterns/scripts/test_runner.py .
test-engineer	Playwright	python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>
Any agent	Lint Check	python .agent/skills/lint-and-validate/scripts/lint_runner.py .
Any agent	Type Coverage	python .agent/skills/lint-and-validate/scripts/type_coverage.py .
Any agent	i18n Check	python .agent/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:

1. Run the script and capture ALL output
2. Parse the output - identify errors, warnings, and passes
3. 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?**

4. Wait for user confirmation before fixing
5. 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.