clean-code

```

1. NO HALLUCINATED PACKAGES - Verify before import
2. NO LAZY PLACEHOLDERS - Code must be runnable
3. NO SECURITY SHORTCUTS - Production-ready defaults
4. NO OVER-ENGINEERING - Simplest solution first

```

LLMs hallucinate packages that sound real but don't exist.

1. Verify before import - npm search or pip show for unfamiliar packages
2. Prefer battle-tested - lodash, date-fns, zod over obscure alternatives
3. Check npm audit / pip-audit before adding new dependencies
4. Pin versions in production - no ^ or ~ for critical deps

2025 AI Package Risks:

• Never import AI "wrapper" libraries without verification
• LLM SDKs: Use official only (openai, anthropic, google-generativeai)
• Vector DBs: Stick to established (pinecone, weaviate, chromadb)

Frontend Security:

| Forbidden | Required |

|-----------|----------|

| dangerouslySetInnerHTML | DOMPurify sanitization |

| Inline event handlers | Event delegation |

| eval(), new Function() | Static code only |

| Storing tokens in localStorage | httpOnly cookies |

Backend Security:

| Forbidden | Required |

|-----------|----------|

| CORS: * | Explicit origin whitelist |

| Raw SQL strings | Parameterized queries |

| chmod 777 | Principle of least privilege |

| Hardcoded secrets | Environment variables + validation |

API Security (2025):

• Rate limiting on ALL public endpoints
• Input validation at the gate (Zod/Pydantic)
• Output sanitization for AI-generated content
• PASETO > JWT for new projects

Forbidden Patterns:

```javascript

// ❌ BANNED

// TODO: Implement this

// ... logic goes here

function placeholder() { }

throw new Error('Not implemented');

```

Required:

• Every function must be runnable
• If too complex, break into smaller complete functions
• "Hurry" is not an excuse - write minimal viable implementation

The 50/300 Rule:

• Functions > 50 lines → Break down
• Files > 300 lines → Split into modules

SOLID Principles:

| Principle | Quick Check |

|-----------|-------------|

| Single Responsibility | Does this do ONE thing? |

| Open/Closed | Can I extend without modifying? |

| Liskov Substitution | Can subtypes replace parent? |

| Interface Segregation | Are interfaces minimal? |

| Dependency Inversion | Do I depend on abstractions? |

Native First:

```javascript

// ❌ Don't install is-odd

npm install is-odd

// ✅ Use native

const isOdd = n => n % 2 !== 0;

```

Anti-Patterns:

• AbstractFactoryBuilderManager for simple functions
• 10 layers of abstraction for CRUD
• "Future-proofing" for requirements that don't exist

YAGNI: You Aren't Gonna Need It. Build for today's requirements.

Freshness Check:

```bash

npm outdated # Check for updates

npm audit # Check for vulnerabilities

```

The CVE Brake:

• "Latest" is not always "Safest"
• If latest has Critical CVE → Rollback to last secure version
• Security > New Features

2025 Recommended:

| Category | Recommended |

|----------|-------------|

| Validation | zod, valibot |

| HTTP | ky, ofetch |

| State | zustand, jotai |

| ORM | drizzle, prisma |

| Auth | lucia, better-auth |

When Building AI Features:

1. Validate AI outputs - Never trust raw LLM responses
2. Rate limit AI calls - Prevent cost explosions
3. Sanitize before display - AI can generate malicious content
4. Log AI interactions - For debugging and compliance

When AI is Writing Code:

1. Verify imports exist - AI hallucinates packages
2. Check types are correct - AI guesses at APIs
3. Test edge cases - AI misses boundary conditions
4. Review security - AI takes shortcuts

Before committing ANY code:

• [ ] No hallucinated imports (verified packages exist)
• [ ] No security shortcuts (CORS, eval, hardcoded secrets)
• [ ] No lazy placeholders (// TODO, empty functions)
• [ ] Functions < 50 lines, files < 300 lines
• [ ] Dependencies audited (npm audit clean)
• [ ] Types are strict (no any)

---

| When Using... | Clean Code Adds... |

|---------------|-------------------|

| @frontend-design | Security defaults, no eval, CSP awareness |

| @backend-design | Input validation, no raw SQL, Zero Trust |

| @tdd-mastery | No placeholders (tests enforce completeness) |

| @planning-mastery | Modularity guides task breakdown |

| @brainstorming | SOLID/YAGNI guide architecture decisions |

| @debug-mastery | Logging standards, no silent failures |