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.

🧠 Knowledge Modules (Fractal Skills)

1. Agent → Script Mapping

2. 🔴 Script Output Handling (READ → SUMMARIZE → ASK)

3. ❌ Errors Found (X items)

4. ⚠️ Warnings (Y items)

5. ✅ Passed (Z items)