florianbruniaux/claude-code-ultimate-guide/explain

Simple (1-2 min read)     → Quick summary, key points only
Standard (3-5 min read)   → Purpose, how it works, key decisions
Deep (10+ min read)       → Full breakdown, alternatives, trade-offs

# For file explanations
head -50 "$FILE"  # See imports and structure
 
# For function explanations
grep -A 30 "function $NAME\|def $NAME\|fn $NAME" "$FILE"
 
# For module explanations
ls -la "$DIR"
cat "$DIR/index.ts" 2>/dev/null || cat "$DIR/__init__.py" 2>/dev/null

// How to use this correctly

**validateUser()** checks if the user object has required fields
(email, password) and returns a boolean. Uses regex for email format.

**validateUser(user: User): ValidationResult**
 
**Purpose**: Validates user input before database operations.
 
**Flow**:
1.Check required fields exist (email, password)
2.Validate email format with regex
3.Check password meets requirements (8+ chars, special char)
4.Return { valid: boolean, errors: string[] }
 
**Used by**: signup(), updateProfile()

[All of standard, plus:]
 
**Design Decisions**:
-Returns ValidationResult instead of throwing to allow batch validation
-Regex chosen over library for zero dependencies
-Password rules configurable via config.ts
 
**Trade-offs**:
-Pro: Fast, no dependencies
-Con: Regex email validation isn't RFC-compliant
 
**Alternatives Considered**:
-Zod schema: More powerful but adds 50KB
-Class-validator: Better for decorators but OOP-heavy

/explain src/auth/middleware.ts

/explain the handleWebhook function in payments.ts

/explain how our event sourcing works

/explain --deep the authentication flow
/explain --simple what useCallback does

/explain --learn the repository pattern used here