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