clean-code

name	clean-code
description	Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
allowed-tools	Read, Write, Edit
version	2
priority	CRITICAL

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.

---

Elite Verification (MANDATORY)

[!CRITICAL] All changes must be verified using the system's core integrity scripts.

Script	Command
System Integrity	npx tsx .agent/scripts/check-integrity.ts
Battle Test	npx tsx .agent/scripts/battle-test.ts
Bootstrap Status	npx tsx .agent/scripts/bootstrap.ts --status
Type Check	npx tsc --noEmit

🔴 Rule: If any check fails, do not proceed with a GitHub push.