Clean Code

Clean Code - Pragmatic AI Coding Standards

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

Core Principles

PrincipleRuleSRPSingle Responsibility - each function/class does ONE thingDRYDon't Repeat Yourself - extract duplicates, reuseKISSKeep It Simple - simplest solution that worksYAGNIYou Aren't Gonna Need It - don't build unused featuresBoy ScoutLeave code cleaner than you found it

Naming Rules

ElementConventionVariablesReveal intent: userCount not nFunctionsVerb + noun: getUserById() not user()BooleansQuestion form: isActive, hasPermission, canEditConstantsSCREAMING_SNAKE: MAX_RETRY_COUNT Rule: If you need a comment to explain a name, rename it.

Function Rules

RuleDescriptionSmallMax 20 lines, ideally 5-10One ThingDoes one thing, does it wellOne LevelOne level of abstraction per functionFew ArgsMax 3 arguments, prefer 0-2No Side EffectsDon't mutate inputs unexpectedly

Code Structure

PatternApplyGuard ClausesEarly returns for edge casesFlat > NestedAvoid deep nesting (max 2 levels)CompositionSmall functions composed togetherColocationKeep related code close

AI Coding Style

SituationActionUser asks for featureWrite it directlyUser reports bugFix it, don't explainNo clear requirementAsk, don't assume

Anti-Patterns (DON'T)

❌ Pattern✅ FixComment every lineDelete obvious commentsHelper for one-linerInline the codeFactory for 2 objectsDirect instantiationutils.ts with 1 functionPut code where used"First we import..."Just write codeDeep nestingGuard clausesMagic numbersNamed constantsGod functionsSplit by responsibility

🔴 Before Editing ANY File (THINK FIRST!)

Before changing a file, ask yourself: QuestionWhyWhat imports this file?They might breakWhat does this file import?Interface changesWhat tests cover this?Tests might failIs 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

DoDon'tWrite code directlyWrite tutorialsLet code self-documentAdd obvious commentsFix bugs immediatelyExplain the fix firstInline small thingsCreate unnecessary filesName things clearlyUse abbreviationsKeep functions smallWrite 100+ line functions Remember: The user wants working code, not a programming lesson.

🔴 Self-Check Before Completing (MANDATORY)

Before saying "task complete", verify: CheckQuestion✅ 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

AgentScriptCommandfrontend-specialistUX Auditpython .agent/skills/frontend-design/scripts/ux_audit.py .frontend-specialistA11y Checkpython .agent/skills/frontend-design/scripts/accessibility_checker.py .backend-specialistAPI Validatorpython .agent/skills/api-patterns/scripts/api_validator.py .mobile-developerMobile Auditpython .agent/skills/mobile-design/scripts/mobile_audit.py .database-architectSchema Validatepython .agent/skills/database-design/scripts/schema_validator.py .security-auditorSecurity Scanpython .agent/skills/vulnerability-scanner/scripts/security_scan.py .seo-specialistSEO Checkpython .agent/skills/seo-fundamentals/scripts/seo_checker.py .seo-specialistGEO Checkpython .agent/skills/geo-fundamentals/scripts/geo_checker.py .performance-optimizerLighthousepython .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>test-engineerTest Runnerpython .agent/skills/testing-patterns/scripts/test_runner.py .test-engineerPlaywrightpython .agent/skills/webapp-testing/scripts/playwright_runner.py <url>Any agentLint Checkpython .agent/skills/lint-and-validate/scripts/lint_runner.py .Any agentType Coveragepython .agent/skills/lint-and-validate/scripts/type_coverage.py .Any agenti18n Checkpython .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:
• 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.