@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/backend-expert-guide.md

@@ -0,0 +1,415 @@
+# Backend Expert Review Guide
+
+> 20-year experience distilled: Reliability first, data consistency, security by default.
+
+## Table of Contents
+
+- [Core Philosophy](#core-philosophy)
+- [New Project Review](#new-project-review)
+- [Version Iteration Review](#version-iteration-review)
+- [New Feature Review](#new-feature-review)
+- [Common Problems & Solutions](#common-problems--solutions)
+- [Tools & Automation](#tools--automation)
+
+---
+
+## Core Philosophy
+
+1. **Reliability first** — 99.99% uptime is the baseline
+2. **Data consistency** — ACID transactions, eventual consistency patterns
+3. **Security by default** — OWASP Top 10 prevention mandatory
+4. **Horizontal scalability** — Stateless services, proper caching
+5. **Observability** — If you can't measure it, you can't fix it
+
+---
+
+## New Project Review
+
+### Architecture Checklist
+
+| Aspect | What to Verify | Red Flags |
+|--------|----------------|-----------|
+| **Service Design** | Proper layering, separation of concerns | God services, circular deps |
+| **Data Modeling** | Normalized schema, proper indexes | No foreign keys, missing constraints |
+| **API Design** | RESTful/GraphQL, versioned, documented | Inconsistent naming, no versioning |
+| **Error Handling** | Structured errors, proper HTTP codes | Generic 500, leaked stack traces |
+| **Security** | Auth, input validation, secrets management | Hardcoded secrets, no auth |
+
+### Technical Decisions Review
+
+```markdown
+## New Project Technical Review
+
+### Architecture Validation
+- [ ] Service boundaries well-defined
+- [ ] Data layer abstracted (Repository pattern)
+- [ ] API versioning strategy defined
+- [ ] Authentication/Authorization mechanism chosen
+- [ ] Rate limiting planned
+
+### Database Foundation
+- [ ] Schema normalized appropriately
+- [ ] Indexes on query columns
+- [ ] Migration tool configured (Alembic/Flyway)
+- [ ] Connection pooling configured
+- [ ] Backup strategy defined
+
+### Security Baseline
+- [ ] Secrets management (Vault/env)
+- [ ] Input validation on all endpoints
+- [ ] SQL injection prevention (ORM/parameterized)
+- [ ] CORS configuration appropriate
+- [ ] Security headers (helmet.js equivalent)
+
+### Observability
+- [ ] Structured logging configured
+- [ ] Metrics collection (Prometheus)
+- [ ] Distributed tracing (Jaeger/Zipkin)
+- [ ] Health check endpoints
+- [ ] Alerting rules defined
+```
+
+### Common New Project Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| No API versioning | Breaking clients | `/v1/` prefix from start |
+| Skipping migrations | Manual DB changes | Versioned migrations required |
+| Monolith without boundaries | Unmaintainable | Module boundaries even in monolith |
+| No rate limiting | DoS vulnerability | Rate limits on all public APIs |
+| Synchronous everything | Bottlenecks | Async patterns for I/O |
+
+---
+
+## Version Iteration Review
+
+### Compatibility Checklist
+
+| Check | Method | Risk if Skipped |
+|-------|--------|-----------------|
+| **API backward compat** | Contract testing (Pact) | Breaking client apps |
+| **Database migrations** | Rollback tested | Data loss, downtime |
+| **Config changes** | Feature flags | Hard rollback needed |
+| **Dependency updates** | Lock file diff | Unexpected behavior |
+
+### Zero-Downtime Deployment
+
+```markdown
+## Deployment Safety Checklist
+
+### Database Changes
+- [ ] Migration is backward compatible
+- [ ] No column renames (add new, migrate, drop old)
+- [ ] No NOT NULL without default
+- [ ] Index creation is CONCURRENT
+- [ ] Rollback script tested
+
+### API Changes
+- [ ] New endpoints added, old deprecated
+- [ ] Deprecation headers on old endpoints
+- [ ] Client migration window defined
+- [ ] Documentation updated
+
+### Release Process
+- [ ] Canary deployment configured
+- [ ] Health checks passing
+- [ ] Rollback procedure documented
+- [ ] Monitoring dashboards ready
+- [ ] On-call notified
+```
+
+### Migration Patterns
+
+```python
+# 🔴 BAD: Destructive migration
+def upgrade():
+    op.drop_column('users', 'legacy_field')  # Data loss!
+
+# ✅ GOOD: Safe column removal (3-phase)
+# Phase 1: Stop writing to column (code change)
+# Phase 2: Make column nullable
+def upgrade():
+    op.alter_column('users', 'legacy_field', nullable=True)
+# Phase 3: Drop column after verification
+
+# 🔴 BAD: Rename column (breaks running code)
+def upgrade():
+    op.alter_column('users', 'name', new_column_name='full_name')
+
+# ✅ GOOD: Add new, migrate, drop old
+def upgrade():
+    op.add_column('users', sa.Column('full_name', sa.String))
+    # In code: write to both, read from new
+    # Later: migrate data, drop old
+```
+
+---
+
+## New Feature Review
+
+### Feature Isolation Checklist
+
+| Aspect | Verification | Red Flag |
+|--------|--------------|----------|
+| **API contract** | OpenAPI spec matches | Undocumented changes |
+| **Data model** | Migrations reviewed | Breaking schema changes |
+| **Security** | Auth on new endpoints | Open endpoints |
+| **Performance** | Load tested | Unbounded queries |
+| **Rollback** | Feature flag exists | No kill switch |
+
+### Concurrency Review
+
+```python
+# 🔴 BAD: Race condition in balance update
+def transfer(from_id, to_id, amount):
+    from_acc = get_account(from_id)
+    to_acc = get_account(to_id)
+    
+    from_acc.balance -= amount  # Race!
+    to_acc.balance += amount
+    
+    save(from_acc)
+    save(to_acc)
+
+# ✅ GOOD: Transactional with locking
+def transfer(from_id, to_id, amount):
+    with db.transaction():
+        from_acc = get_account_for_update(from_id)  # SELECT FOR UPDATE
+        to_acc = get_account_for_update(to_id)
+        
+        if from_acc.balance < amount:
+            raise InsufficientFunds()
+        
+        from_acc.balance -= amount
+        to_acc.balance += amount
+        
+        save(from_acc)
+        save(to_acc)
+```
+
+### Distributed Transaction Patterns
+
+```python
+# 🔴 BAD: Multiple service calls without compensation
+async def create_order(data):
+    order = await order_service.create(data)      # 1. Created
+    await payment_service.charge(order.total)     # 2. Charged
+    await inventory_service.reduce(order.items)   # 3. Fails! Order + payment orphaned
+
+# ✅ GOOD: Saga pattern with compensation
+async def create_order(data):
+    saga = OrderSaga()
+    try:
+        order = await saga.step(
+            action=lambda: order_service.create(data),
+            compensate=lambda o: order_service.cancel(o.id)
+        )
+        await saga.step(
+            action=lambda: payment_service.charge(order.total),
+            compensate=lambda: payment_service.refund(order.id)
+        )
+        await saga.step(
+            action=lambda: inventory_service.reduce(order.items),
+            compensate=lambda: inventory_service.restore(order.items)
+        )
+        await saga.commit()
+    except Exception:
+        await saga.rollback()  # Compensate all completed steps
+        raise
+```
+
+---
+
+## Common Problems & Solutions
+
+### Problem Matrix
+
+| Problem | Symptom | Root Cause | Solution |
+|---------|---------|------------|----------|
+| **Unclear requirements** | Schema churn | No data modeling | JAD meetings, frozen ER |
+| **Wrong database** | Performance issues | No benchmarks | POC with realistic data |
+| **N+1 queries** | Slow responses | ORM misuse | Query analysis, eager loading |
+| **API inconsistency** | Integration failures | No contract | OpenAPI spec as source of truth |
+| **Security gaps** | Vulnerabilities | Afterthought | OWASP in CI, security reviews |
+| **Observability gaps** | Blind spots | No instrumentation | Logging/metrics/traces from start |
+
+### Performance Optimization Patterns
+
+```python
+# 🔴 BAD: N+1 query
+users = User.query.all()
+for user in users:
+    print(user.orders)  # Each access = 1 query
+
+# ✅ GOOD: Eager loading
+users = User.query.options(joinedload(User.orders)).all()
+for user in users:
+    print(user.orders)  # Already loaded
+
+# 🔴 BAD: Unbounded query
+@app.get("/items")
+def list_items():
+    return Item.query.all()  # Could be millions
+
+# ✅ GOOD: Paginated with limits
+@app.get("/items")
+def list_items(page: int = 1, limit: int = 20):
+    if limit > 100:
+        limit = 100  # Hard cap
+    return Item.query.offset((page-1)*limit).limit(limit).all()
+
+# 🔴 BAD: Sync I/O in async context
+@app.get("/data")
+async def get_data():
+    result = requests.get(url)  # Blocks event loop!
+    return result.json()
+
+# ✅ GOOD: Async I/O
+@app.get("/data")
+async def get_data():
+    async with httpx.AsyncClient() as client:
+        result = await client.get(url)
+    return result.json()
+```
+
+### Error Handling Patterns
+
+```python
+# 🔴 BAD: Generic error, leaked details
+@app.get("/users/{id}")
+def get_user(id: int):
+    try:
+        return db.get_user(id)
+    except Exception as e:
+        return {"error": str(e)}  # Leaks internal details
+
+# ✅ GOOD: Structured, safe error response
+class UserNotFoundError(HTTPException):
+    def __init__(self, user_id: int):
+        super().__init__(
+            status_code=404,
+            detail={"code": "USER_NOT_FOUND", "message": f"User {user_id} not found"}
+        )
+
+@app.get("/users/{id}")
+def get_user(id: int):
+    user = db.get_user(id)
+    if not user:
+        raise UserNotFoundError(id)
+    return user
+```
+
+---
+
+## Tools & Automation
+
+### Recommended Tool Stack
+
+| Category | Tool | Purpose |
+|----------|------|---------|
+| **Type Safety** | TypeScript / Python typing | Prevent runtime errors |
+| **Static Analysis** | SonarQube / Bandit | Code quality + security |
+| **API Spec** | OpenAPI / Swagger | Contract documentation |
+| **Testing** | Pytest / Jest + Supertest | Coverage pyramid |
+| **Load Testing** | k6 / JMeter | Performance verification |
+| **Security** | OWASP ZAP | Vulnerability scanning |
+| **Monitoring** | Prometheus + Grafana | Metrics and alerts |
+| **Tracing** | Jaeger / Zipkin | Distributed tracing |
+
+### CI/CD Pipeline Requirements
+
+```yaml
+# Minimum backend CI checks
+stages:
+  - lint:
+      - eslint/pylint
+      - type checking
+  - security:
+      - dependency audit
+      - SAST scan (SonarQube)
+      - secrets detection
+  - test:
+      - unit tests (>80% coverage)
+      - integration tests
+      - contract tests
+  - build:
+      - docker build
+      - image scan
+  - deploy:
+      - canary deployment
+      - smoke tests
+      - rollback on failure
+```
+
+### Database Review Automation
+
+```bash
+#!/bin/bash
+# Pre-merge database checks
+
+# Check migration files
+echo "=== Migration Safety Check ==="
+for file in migrations/*.sql; do
+  # Check for dangerous operations
+  if grep -iE "DROP|TRUNCATE|DELETE FROM .* WHERE" "$file"; then
+    echo "⚠️ Dangerous operation in $file - requires approval"
+  fi
+  
+  # Check for missing indexes
+  if grep -iE "ADD COLUMN" "$file" | grep -ivE "INDEX|UNIQUE"; then
+    echo "⚠️ New column without index consideration in $file"
+  fi
+done
+
+# Check for N+1 patterns in code
+echo "=== N+1 Query Detection ==="
+grep -rn "for.*:$" --include="*.py" -A 3 | grep -E "\.query\.|\.get\(|\.find\("
+```
+
+---
+
+## Review Report Template
+
+```markdown
+# Backend Code Review Report
+
+## Summary
+- **Reviewer**: [Name]
+- **Date**: [Date]
+- **Context**: [New Project / Iteration / Feature]
+- **Verdict**: [APPROVED / CHANGES REQUESTED]
+
+## Findings
+
+### 🔴 P0 - Blockers
+| Issue | File:Line | Impact | Suggested Fix |
+|-------|-----------|--------|---------------|
+
+### 🟠 P1 - Critical
+| Issue | File:Line | Impact | Suggested Fix |
+|-------|-----------|--------|---------------|
+
+### 🟡 P2 - Major
+| Issue | File:Line | Impact | Suggested Fix |
+|-------|-----------|--------|---------------|
+
+## Checklist Completion
+- [ ] API contract verified
+- [ ] Database migrations safe
+- [ ] Security reviewed
+- [ ] Performance acceptable
+- [ ] Error handling complete
+- [ ] Observability configured
+
+## Similar Bug Hunt
+**Pattern searched**: [Description]
+**Files checked**: [Count]
+**Issues found**: [Count]
+
+## Performance Impact
+- [ ] Load tested
+- [ ] Query plans reviewed
+- [ ] No N+1 patterns
+- [ ] Caching appropriate
+```
+