┌──────────────┐
│  RED         │  Escribe test que FALLE
│  ❌ Test    │  (no hay implementación)
└──────┬───────┘
       │
       ↓
┌──────────────┐
│  GREEN       │  Implementa código MÍNIMO
│  ✅ Test    │  para que pase el test
└──────┬───────┘
       │
       ↓
┌──────────────┐
│  REFACTOR    │  Mejora el código
│  🔧 Código  │  (tests garantizan que funciona)
└──────┬───────┘
       │
       ↓ (repetir)

Tú: Necesito una función que valide emails.
 
Debe:
- Retornar true para emails válidos
- Retornar false para emails inválidos
- Lanzar error si el input no es string

Tú: Escribe primero el test para esta función

// tests/validateEmail.test.ts
 
import { validateEmail } from '../src/validateEmail';
 
describe('validateEmail', () => {
  describe('casos válidos', () => {
    test('retorna true para email válido simple', () => {
      expect(validateEmail('user@example.com')).toBe(true);
    });
 
    test('retorna true para email con subdominios', () => {
      expect(validateEmail('user@mail.example.com')).toBe(true);
    });
 
    test('retorna true para email con números', () => {
      expect(validateEmail('user123@example.com')).toBe(true);
    });
 
    test('retorna true para email con guiones', () => {
      expect(validateEmail('first-last@example.com')).toBe(true);
    });
 
    test('retorna true para email con plus', () => {
      expect(validateEmail('user+tag@example.com')).toBe(true);
    });
  });
 
  describe('casos inválidos', () => {
    test('retorna false para email sin @', () => {
      expect(validateEmail('userexample.com')).toBe(false);
    });
 
    test('retorna false para email sin dominio', () => {
      expect(validateEmail('user@')).toBe(false);
    });
 
    test('retorna false para email sin usuario', () => {
      expect(validateEmail('@example.com')).toBe(false);
    });
 
    test('retorna false para email con espacios', () => {
      expect(validateEmail('user @example.com')).toBe(false);
    });
 
    test('retorna false para string vacío', () => {
      expect(validateEmail('')).toBe(false);
    });
  });
 
  describe('casos de error', () => {
    test('lanza error si input no es string', () => {
      expect(() => validateEmail(null as any)).toThrow('Input must be a string');
      expect(() => validateEmail(undefined as any)).toThrow('Input must be a string');
      expect(() => validateEmail(123 as any)).toThrow('Input must be a string');
      expect(() => validateEmail({} as any)).toThrow('Input must be a string');
    });
  });
});

Tú: Ejecuta el test
 
Claude: Ejecutando tests...
 
❌ FAIL tests/validateEmail.test.ts
  validateEmail
    ✗ retorna true para email válido simple
      Cannot find module '../src/validateEmail'
 
Tests: 0 passed, 13 failed

Tú: Ahora implementa validateEmail para pasar estos tests

// src/validateEmail.ts
 
export function validateEmail(email: unknown): boolean {
  // Validar que es string
  if (typeof email !== 'string') {
    throw new Error('Input must be a string');
  }
 
  // Validar formato básico
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

Tú: Ejecuta los tests de nuevo
 
Claude: Ejecutando tests...
 
✅ PASS tests/validateEmail.test.ts
  validateEmail
    casos válidos
      ✓ retorna true para email válido simple (2 ms)
      ✓ retorna true para email con subdominios (1 ms)
      ✓ retorna true para email con números (1 ms)
      ✓ retorna true para email con guiones (1 ms)
      ✓ retorna true para email con plus (1 ms)
    casos inválidos
      ✓ retorna false para email sin @ (1 ms)
      ✓ retorna false para email sin dominio (1 ms)
      ✓ retorna false para email sin usuario (1 ms)
      ✓ retorna false para email con espacios (1 ms)
      ✓ retorna false para string vacío (1 ms)
    casos de error
      ✓ lanza error si input no es string (2 ms)
 
Tests: 13 passed, 0 failed

Tú: El código funciona, pero ¿puedes refactorizarlo para mejor legibilidad?
Mantén los tests pasando.

// src/validateEmail.ts
 
/**
 * Valida si un string tiene formato de email válido
 * @param email - String a validar
 * @returns true si es email válido, false si no
 * @throws Error si el input no es string
 */
export function validateEmail(email: unknown): boolean {
  validateInput(email);
  return hasValidEmailFormat(email);
}
 
function validateInput(email: unknown): asserts email is string {
  if (typeof email !== 'string') {
    throw new Error('Input must be a string');
  }
}
 
function hasValidEmailFormat(email: string): boolean {
  const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return EMAIL_PATTERN.test(email);
}

Tú: Ejecuta tests
 
Claude:
✅ PASS tests/validateEmail.test.ts
Tests: 13 passed, 0 failed
 
Refactor exitoso: el código está más limpio y los tests siguen pasando.

Tú: Vamos a crear un endpoint POST /api/users con TDD.
 
Requisitos:
- Recibe { email, password, name } en body
- Valida que email sea válido
- Valida que password tenga mínimo 8 caracteres
- Hashea el password con bcrypt
- Guarda usuario en base de datos
- Retorna { id, email, name } (sin password)
- Retorna 400 si validación falla
- Retorna 409 si email ya existe
 
Usa Express + TypeScript.
Empieza escribiendo los tests primero.

// tests/users.test.ts
 
import request from 'supertest';
import { app } from '../src/app';
import { db } from '../src/db';
 
describe('POST /api/users', () => {
  beforeEach(async () => {
    // Limpiar base de datos antes de cada test
    await db.users.deleteMany({});
  });
 
  afterAll(async () => {
    await db.disconnect();
  });
 
  describe('casos exitosos', () => {
    test('crea usuario con datos válidos', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          password: 'securePassword123',
          name: 'Test User'
        });
 
      expect(response.status).toBe(201);
      expect(response.body).toEqual({
        id: expect.any(String),
        email: 'test@example.com',
        name: 'Test User'
      });
      expect(response.body.password).toBeUndefined();
    });
 
    test('hashea el password antes de guardar', async () => {
      await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          password: 'myPassword123',
          name: 'Test User'
        });
 
      const user = await db.users.findOne({ email: 'test@example.com' });
      expect(user.password).not.toBe('myPassword123');
      expect(user.password).toMatch(/^\$2[aby]\$.{56}$/); // bcrypt hash pattern
    });
  });
 
  describe('validación de email', () => {
    test('retorna 400 si email está vacío', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: '',
          password: 'securePassword123',
          name: 'Test User'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toBe('Invalid email');
    });
 
    test('retorna 400 si email es inválido', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'not-an-email',
          password: 'securePassword123',
          name: 'Test User'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toBe('Invalid email');
    });
  });
 
  describe('validación de password', () => {
    test('retorna 400 si password tiene menos de 8 caracteres', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          password: 'short',
          name: 'Test User'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toBe('Password must be at least 8 characters');
    });
 
    test('retorna 400 si password está vacío', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          password: '',
          name: 'Test User'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toBe('Password must be at least 8 characters');
    });
  });
 
  describe('validación de name', () => {
    test('retorna 400 si name está vacío', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          password: 'securePassword123',
          name: ''
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toBe('Name is required');
    });
  });
 
  describe('duplicados', () => {
    test('retorna 409 si email ya existe', async () => {
      // Crear primer usuario
      await request(app)
        .post('/api/users')
        .send({
          email: 'duplicate@example.com',
          password: 'password123',
          name: 'First User'
        });
 
      // Intentar crear otro con mismo email
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'duplicate@example.com',
          password: 'differentPassword123',
          name: 'Second User'
        });
 
      expect(response.status).toBe(409);
      expect(response.body.error).toBe('Email already exists');
    });
  });
 
  describe('campos faltantes', () => {
    test('retorna 400 si falta email', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          password: 'password123',
          name: 'Test User'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toContain('email');
    });
 
    test('retorna 400 si falta password', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          name: 'Test User'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toContain('password');
    });
 
    test('retorna 400 si falta name', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'test@example.com',
          password: 'password123'
        });
 
      expect(response.status).toBe(400);
      expect(response.body.error).toContain('name');
    });
  });
});

Tú: Ejecuta los tests
 
Claude:
❌ FAIL tests/users.test.ts
  Cannot find module '../src/app'
 
Tests: 0 passed, 14 failed
 
Perfecto, los tests fallan porque no hay implementación.

Tú: Ahora implementa el código para pasar estos tests

// src/routes/users.ts
 
import { Router, Request, Response } from 'express';
import bcrypt from 'bcrypt';
import { db } from '../db';
import { validateEmail } from '../utils/validateEmail';
 
const router = Router();
 
interface CreateUserRequest {
  email: string;
  password: string;
  name: string;
}
 
router.post('/api/users', async (req: Request, res: Response) => {
  try {
    const { email, password, name } = req.body as CreateUserRequest;
 
    // Validar campos requeridos
    if (!email || !password || !name) {
      return res.status(400).json({
        error: 'email, password, and name are required'
      });
    }
 
    // Validar email
    if (!validateEmail(email)) {
      return res.status(400).json({ error: 'Invalid email' });
    }
 
    // Validar password
    if (password.length < 8) {
      return res.status(400).json({
        error: 'Password must be at least 8 characters'
      });
    }
 
    // Validar name
    if (name.trim().length === 0) {
      return res.status(400).json({ error: 'Name is required' });
    }
 
    // Verificar si email ya existe
    const existingUser = await db.users.findOne({ email });
    if (existingUser) {
      return res.status(409).json({ error: 'Email already exists' });
    }
 
    // Hash password
    const hashedPassword = await bcrypt.hash(password, 10);
 
    // Crear usuario
    const user = await db.users.create({
      email,
      password: hashedPassword,
      name
    });
 
    // Retornar sin password
    res.status(201).json({
      id: user.id,
      email: user.email,
      name: user.name
    });
  } catch (error) {
    console.error('Error creating user:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
 
export default router;

// src/app.ts
 
import express from 'express';
import usersRouter from './routes/users';
 
export const app = express();
 
app.use(express.json());
app.use(usersRouter);

Tú: Ejecuta los tests
 
Claude:
✅ PASS tests/users.test.ts
  POST /api/users
    casos exitosos
      ✓ crea usuario con datos válidos (45 ms)
      ✓ hashea el password antes de guardar (38 ms)
    validación de email
      ✓ retorna 400 si email está vacío (12 ms)
      ✓ retorna 400 si email es inválido (11 ms)
    validación de password
      ✓ retorna 400 si password tiene menos de 8 caracteres (10 ms)
      ✓ retorna 400 si password está vacío (9 ms)
    validación de name
      ✓ retorna 400 si name está vacío (10 ms)
    duplicados
      ✓ retorna 409 si email ya existe (52 ms)
    campos faltantes
      ✓ retorna 400 si falta email (8 ms)
      ✓ retorna 400 si falta password (9 ms)
      ✓ retorna 400 si falta name (8 ms)
 
Tests: 14 passed, 0 failed
Time: 2.154 s

Tú: El código funciona pero está un poco largo.
Refactorízalo extrayendo la validación a funciones separadas.
Asegúrate de que los tests sigan pasando.

// src/routes/users.ts (refactorizado)
 
import { Router, Request, Response } from 'express';
import bcrypt from 'bcrypt';
import { db } from '../db';
import { validateEmail } from '../utils/validateEmail';
 
const router = Router();
 
interface CreateUserRequest {
  email: string;
  password: string;
  name: string;
}
 
interface ValidationError {
  error: string;
}
 
router.post('/api/users', async (req: Request, res: Response) => {
  try {
    const { email, password, name } = req.body as CreateUserRequest;
 
    // Validar input
    const validationError = validateUserInput({ email, password, name });
    if (validationError) {
      return res.status(400).json(validationError);
    }
 
    // Verificar duplicado
    if (await emailExists(email)) {
      return res.status(409).json({ error: 'Email already exists' });
    }
 
    // Crear usuario
    const user = await createUser({ email, password, name });
 
    // Retornar respuesta
    res.status(201).json(sanitizeUser(user));
  } catch (error) {
    console.error('Error creating user:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
 
function validateUserInput(
  input: CreateUserRequest
): ValidationError | null {
  const { email, password, name } = input;
 
  if (!email || !password || !name) {
    return { error: 'email, password, and name are required' };
  }
 
  if (!validateEmail(email)) {
    return { error: 'Invalid email' };
  }
 
  if (password.length < 8) {
    return { error: 'Password must be at least 8 characters' };
  }
 
  if (name.trim().length === 0) {
    return { error: 'Name is required' };
  }
 
  return null;
}
 
async function emailExists(email: string): Promise<boolean> {
  const user = await db.users.findOne({ email });
  return user !== null;
}
 
async function createUser(data: CreateUserRequest) {
  const hashedPassword = await bcrypt.hash(data.password, 10);
 
  return db.users.create({
    email: data.email,
    password: hashedPassword,
    name: data.name
  });
}
 
function sanitizeUser(user: any) {
  return {
    id: user.id,
    email: user.email,
    name: user.name
  };
}
 
export default router;

Tú: Ejecuta tests
 
Claude:
✅ PASS tests/users.test.ts
Tests: 14 passed, 0 failed
 
¡Refactor exitoso! El código está más organizado y los tests garantizan
que la funcionalidad no cambió.

Tú: Escribe tests para una función calculateDiscount(price, code)
 
Claude genera automáticamente tests para:
  ✓ Happy path
  ✓ Casos edge (precio 0, negativo, decimal)
  ✓ Códigos inválidos
  ✓ Validación de tipos
  ✓ Casos límite

Tú: Refactoriza esta función para mejor rendimiento
 
Claude:
- Optimiza el código
- Ejecuta tests automáticamente
- Si algo se rompe, lo detecta inmediatamente
- Ajusta hasta que todos los tests pasen

test('calcula descuento del 20% con código SAVE20', () => {
  expect(calculateDiscount(100, 'SAVE20')).toBe(80);
});
 
// Este test documenta cómo usar la función

Tú: Vamos a implementar autenticación JWT con TDD.
 
Paso 1: Escribe tests para generateToken(userId)
Paso 2: Implementa generateToken
Paso 3: Tests pasan ✅
 
Paso 4: Escribe tests para verifyToken(token)
Paso 5: Implementa verifyToken
Paso 6: Tests pasan ✅
 
Paso 7: Escribe tests para refreshToken(token)
Paso 8: Implementa refreshToken
Paso 9: Tests pasan ✅
 
Resultado: Sistema de auth completo con tests

Tú: Hay un bug: calculateTotal falla con arrays vacíos
 
Paso 1: Escribe un test que reproduzca el bug
test('maneja array vacío', () => {
  expect(calculateTotal([])).toBe(0);
});
 
Paso 2: Ejecuta test (falla ❌)
 
Paso 3: Arregla el código
 
Paso 4: Test pasa ✅
 
Paso 5: El bug nunca volverá (test lo previene)

Tú: Este código funciona pero es difícil de leer. Refactorízalo.
 
Claude:
1. Primero, genero tests para el código actual
2. Ejecuto tests → todos pasan ✅
3. Ahora refactorizo el código
4. Ejecuto tests después de cada cambio
5. Si algo se rompe, lo detecto inmediatamente
6. Resultado: código limpio + tests garantizan funcionalidad

❌ Malo:
"Crea una función de validación"
 
✅ Bueno:
"Crea validatePassword que:
- Retorna true si >= 8 caracteres
- Retorna true si tiene al menos 1 número
- Retorna true si tiene al menos 1 mayúscula
- Retorna false si no cumple lo anterior
- Lanza error si input no es string"

Tú: Implementa función calculateShipping
 
Claude: [Empieza a implementar]
 
❌ Detén: "Espera, escribe los tests primero"
 
✅ Desde el inicio: "Escribe tests primero para calculateShipping"

1. Claude escribe test
2. Tú: "Ejecuta el test" → Debe fallar ❌
3. Si pasa sin implementación = test está mal

No hagas:
- Escribir 10 tests
- Implementar todo de golpe
 
Haz:
- Escribir 1-3 tests relacionados
- Implementar para pasarlos
- Refactorizar
- Repetir

✅ Bueno:
test('retorna true para email válido', () => {
  expect(validateEmail('user@example.com')).toBe(true);
});
 
❌ Malo:
test('test1', () => {
  const data = { /* 50 líneas de setup */ };
  const result = complexFunction(data);
  expect(result.nested.deeply.value[0].prop).toBe(/* algo */);
});

❌ Malo:
Tú: "Implementa esta función"
[Después] "Ahora escribe tests"
 
✅ Bueno:
Tú: "Escribe tests primero"
[Tests fallan]
"Ahora implementa"

❌ Malo:
test('función existe', () => {
  expect(myFunction).toBeDefined();
});
 
✅ Bueno:
test('retorna resultado correcto', () => {
  expect(myFunction(input)).toBe(expectedOutput);
});

❌ Malo:
Tests pasan → "Listo, siguiente feature"
 
✅ Bueno:
Tests pasan → "¿Puedo mejorar este código?"
Refactorizar → Tests siguen pasando → Listo

// LoginForm.test.tsx
 
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { LoginForm } from './LoginForm';
 
describe('LoginForm', () => {
  test('renderiza email y password inputs', () => {
    render(<LoginForm onSubmit={jest.fn()} />);
 
    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
  });
 
  test('renderiza botón de submit', () => {
    render(<LoginForm onSubmit={jest.fn()} />);
 
    expect(screen.getByRole('button', { name: /log in/i })).toBeInTheDocument();
  });
 
  test('llama onSubmit con email y password', async () => {
    const handleSubmit = jest.fn();
    render(<LoginForm onSubmit={handleSubmit} />);
 
    fireEvent.change(screen.getByLabelText(/email/i), {
      target: { value: 'test@example.com' }
    });
    fireEvent.change(screen.getByLabelText(/password/i), {
      target: { value: 'password123' }
    });
 
    fireEvent.click(screen.getByRole('button', { name: /log in/i }));
 
    await waitFor(() => {
      expect(handleSubmit).toHaveBeenCalledWith({
        email: 'test@example.com',
        password: 'password123'
      });
    });
  });
 
  test('muestra error si email está vacío', async () => {
    render(<LoginForm onSubmit={jest.fn()} />);
 
    fireEvent.click(screen.getByRole('button', { name: /log in/i }));
 
    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
  });
 
  test('muestra error si password está vacío', async () => {
    render(<LoginForm onSubmit={jest.fn()} />);
 
    fireEvent.change(screen.getByLabelText(/email/i), {
      target: { value: 'test@example.com' }
    });
 
    fireEvent.click(screen.getByRole('button', { name: /log in/i }));
 
    expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
  });
 
  test('deshabilita botón mientras está submitting', async () => {
    const slowSubmit = () => new Promise(resolve => setTimeout(resolve, 100));
    render(<LoginForm onSubmit={slowSubmit} />);
 
    fireEvent.change(screen.getByLabelText(/email/i), {
      target: { value: 'test@example.com' }
    });
    fireEvent.change(screen.getByLabelText(/password/i), {
      target: { value: 'password123' }
    });
 
    const button = screen.getByRole('button', { name: /log in/i });
    fireEvent.click(button);
 
    expect(button).toBeDisabled();
    expect(button).toHaveTextContent(/logging in/i);
  });
 
  test('muestra error del servidor', async () => {
    const handleSubmit = jest.fn().mockRejectedValue(
      new Error('Invalid credentials')
    );
    render(<LoginForm onSubmit={handleSubmit} />);
 
    fireEvent.change(screen.getByLabelText(/email/i), {
      target: { value: 'test@example.com' }
    });
    fireEvent.change(screen.getByLabelText(/password/i), {
      target: { value: 'wrong' }
    });
 
    fireEvent.click(screen.getByRole('button', { name: /log in/i }));
 
    expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument();
  });
});

// LoginForm.tsx
 
import { useState, FormEvent } from 'react';
 
interface LoginFormProps {
  onSubmit: (credentials: { email: string; password: string }) => Promise<void>;
}
 
export function LoginForm({ onSubmit }: LoginFormProps) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [errors, setErrors] = useState<{ email?: string; password?: string; server?: string }>({});
  const [isSubmitting, setIsSubmitting] = useState(false);
 
  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault();
 
    // Limpiar errores previos
    setErrors({});
 
    // Validar
    const newErrors: typeof errors = {};
    if (!email) newErrors.email = 'Email is required';
    if (!password) newErrors.password = 'Password is required';
 
    if (Object.keys(newErrors).length > 0) {
      setErrors(newErrors);
      return;
    }
 
    // Submit
    setIsSubmitting(true);
    try {
      await onSubmit({ email, password });
    } catch (error) {
      setErrors({ server: error.message });
    } finally {
      setIsSubmitting(false);
    }
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
        {errors.email && <span role="alert">{errors.email}</span>}
      </div>
 
      <div>
        <label htmlFor="password">Password</label>
        <input
          id="password"
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
        />
        {errors.password && <span role="alert">{errors.password}</span>}
      </div>
 
      {errors.server && <div role="alert">{errors.server}</div>}
 
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Logging in...' : 'Log in'}
      </button>
    </form>
  );
}

✅ PASS LoginForm.test.tsx
  LoginForm
    ✓ renderiza email y password inputs
    ✓ renderiza botón de submit
    ✓ llama onSubmit con email y password
    ✓ muestra error si email está vacío
    ✓ muestra error si password está vacío
    ✓ deshabilita botón mientras está submitting
    ✓ muestra error del servidor
 
Tests: 7 passed, 0 failed

❌ Proceso tradicional:
1. Ves el error → 😰
2. Lees el stack trace → 🤔
3. Googlas el error → 🔍
4. Lees Stack Overflow → 📚
5. Pruebas solución 1 → No funciona
6. Pruebas solución 2 → No funciona
7. Pruebas solución 3 → Funciona!
   (2 horas después) → 😓
 
✅ Con Claude Code:
1. Copias el error completo
2. Se lo pasas a Claude
3. Claude analiza, identifica causa, propone solución
4. Aplicas la solución
5. Verificas
   (5 minutos después) → ✅

Usuario: Tengo este error:
 
Error: Cannot read property 'map' of undefined
    at UserList.render (UserList.tsx:23:18)
    at finishClassComponent (react-dom.development.js:17485:31)
    at updateClassComponent (react-dom.development.js:17435:24)
    at beginWork (react-dom.development.js:19073:16)
    at HTMLUnknownElement.callCallback (react-dom.development.js:3945:14)
 
Código donde ocurre (UserList.tsx):
 
21: function UserList({ users }) {
22:   return (
23:     <ul>
24:       {users.map(user => (
25:         <li key={user.id}>{user.name}</li>
26:       ))}
27:     </ul>
28:   );
29: }
 
Contexto:
- Ocurre al cargar la página de usuarios
- Funcionaba ayer, dejó de funcionar hoy
- Actualicé la API que devuelve los usuarios

Usuario: Este error aparece en producción:
 
TypeError: Cannot read properties of null (reading 'token')
    at verifyAuth (middleware/auth.js:15:29)
    at Layer.handle [as handle_request] (express/lib/router/layer.js:95:5)
    at next (express/lib/router/route.js:144:13)
    at Route.dispatch (express/lib/router/route.js:114:3)
 
Código (middleware/auth.js):
 
12: function verifyAuth(req, res, next) {
13:   const authHeader = req.headers.authorization;
14:
15:   const token = authHeader.split(' ')[1];
16:
17:   jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
18:     if (err) return res.status(401).json({ error: 'Invalid token' });
19:     req.userId = decoded.userId;
20:     next();
21:   });
22: }
 
Contexto:
- Algunos usuarios reportan este error al hacer requests autenticados
- No todos los usuarios lo experimentan

Claude: Identifiqué el problema:
 
🔍 CAUSA RAÍZ:
El error ocurre en la línea 15 cuando `authHeader` es null o undefined.
 
Esto sucede cuando:
1. El request no incluye header `Authorization`
2. Algunos clientes no están enviando el header
 
🐛 PROBLEMA ESPECÍFICO:
authHeader.split(' ')[1]
         ↑
         Si authHeader es null, esto lanza TypeError
 
👥 POR QUÉ ALGUNOS USUARIOS SÍ Y OTROS NO:
- Usuarios con sesión expirada → No envían header → Error
- Usuarios con sesión válida → Envían header → Funciona
 
✅ SOLUCIÓN:
 
function verifyAuth(req, res, next) {
  const authHeader = req.headers.authorization;
 
  // VALIDAR: Header existe
  if (!authHeader) {
    return res.status(401).json({
      error: 'Authorization header missing'
    });
  }
 
  // VALIDAR: Header tiene formato correcto
  const parts = authHeader.split(' ');
  if (parts.length !== 2 || parts[0] !== 'Bearer') {
    return res.status(401).json({
      error: 'Invalid authorization format. Use: Bearer <token>'
    });
  }
 
  const token = parts[1];
 
  jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
    if (err) return res.status(401).json({ error: 'Invalid token' });
    req.userId = decoded.userId;
    next();
  });
}
 
🎯 CAMBIOS:
1. Validar que authHeader existe antes de usar .split()
2. Validar formato "Bearer <token>"
3. Mensajes de error más descriptivos
 
🧪 TESTING:
Prueba con estos casos:
1. Sin header Authorization → 401 "Authorization header missing"
2. Header malformado "token123" → 401 "Invalid authorization format"
3. Header correcto "Bearer token123" → Funciona

Usuario: Aplica la solución
 
Claude: [Actualiza el archivo]
 
Ahora ejecuta estos tests para verificar:
 
curl http://localhost:3000/api/users
→ Debería retornar 401 "Authorization header missing"
 
curl -H "Authorization: malformed" http://localhost:3000/api/users
→ Debería retornar 401 "Invalid authorization format"
 
curl -H "Authorization: Bearer valid_token" http://localhost:3000/api/users
→ Debería funcionar correctamente

Usuario: Mi build de TypeScript está fallando:
 
error TS2339: Property 'username' does not exist on type 'User'.
 
34   const greeting = `Hello, ${user.username}`;
                                    ~~~~~~~~
 
  src/types/User.ts:3:5
    3     name: string;
          ~~~~
    'name' is declared here.
 
Build failed.
 
Código (src/components/Greeting.tsx):
 
32: function Greeting({ user }: { user: User }) {
33:   return (
34:     <div>Hello, {user.username}</div>
35:   );
36: }
 
Interfaz (src/types/User.ts):
 
1: export interface User {
2:   id: string;
3:   name: string;
4:   email: string;
5: }
 
Contexto:
- Funcionaba antes
- Alguien del equipo cambió la interfaz User ayer

Claude: Problema identificado:
 
🔍 CAUSA:
La interfaz User tiene la propiedad `name`, pero el código usa `username`.
 
📝 HISTORIA:
Alguien renombró `username` → `name` en la interfaz,
pero no actualizó todos los usos en el código.
 
🔎 BUSCANDO TODOS LOS USOS:
[Claude busca automáticamente...]
 
Encontré 5 archivos que usan user.username:
1. src/components/Greeting.tsx:34
2. src/components/Profile.tsx:18
3. src/components/UserCard.tsx:42
4. src/utils/formatUser.ts:12
5. src/services/userService.ts:67
 
✅ SOLUCIONES POSIBLES:
 
OPCIÓN 1: Cambiar código para usar `name`
Pros: Se alinea con la nueva interfaz
Contras: Muchos archivos que actualizar
 
OPCIÓN 2: Añadir `username` como alias en la interfaz
Pros: No rompe código existente
Contras: Duplicación, eventual deuda técnica
 
OPCIÓN 3: Cambiar interfaz de vuelta a `username`
Pros: Nada que cambiar en el código
Contras: Inconsistente si otros tipos usan `name`
 
💡 RECOMENDACIÓN: Opción 1 (actualizar código)
 
Razón: Es mejor alinearse con la convención del equipo.
Si otros tipos de usuario usan `name`, mantén consistencia.
 
¿Quieres que actualice los 5 archivos automáticamente?

Usuario: Sí, actualiza los 5 archivos
 
Claude: Actualizando archivos...
 
✓ src/components/Greeting.tsx
  - user.username → user.name
 
✓ src/components/Profile.tsx
  - user.username → user.name
 
✓ src/components/UserCard.tsx
  - user.username → user.name
 
✓ src/utils/formatUser.ts
  - user.username → user.name
 
✓ src/services/userService.ts
  - user.username → user.name
 
Ejecutando build...
✅ Build exitoso
 
Tests...
✅ 47 tests passed

Usuario: Tengo un bug extraño en mi función de cálculo:
 
La función calculateTotal a veces retorna valores incorrectos.
 
Ejemplos:
- calculateTotal([10, 20, 30]) → 60 ✅ Correcto
- calculateTotal([5, 5, 5]) → 15 ✅ Correcto
- calculateTotal([1.1, 2.2, 3.3]) → 6.6000000000000005 ❌ Incorrecto
- calculateTotal([9.99, 9.99]) → 19.98 ✅ Correcto
- calculateTotal([0.1, 0.2]) → 0.30000000000000004 ❌ Incorrecto
 
Código:
 
function calculateTotal(prices: number[]): number {
  return prices.reduce((sum, price) => sum + price, 0);
}

Claude: Identifiqué el problema:
 
🔍 CAUSA:
Problema clásico de precisión de punto flotante en JavaScript.
 
📚 EXPLICACIÓN:
JavaScript usa IEEE 754 para números flotantes.
Algunos decimales no pueden representarse exactamente en binario:
 
0.1 en binario = 0.0001100110011001100... (infinito)
0.2 en binario = 0.001100110011001100... (infinito)
 
Al sumar, los errores de redondeo se acumulan:
0.1 + 0.2 = 0.30000000000000004
 
🐛 POR QUÉ ALGUNOS FUNCIONAN:
- Enteros (10, 20, 30) → Sin decimales, sin problema
- 9.99 → Casualidad, se representa exactamente
- 0.1, 0.2 → No se pueden representar exactamente
 
✅ SOLUCIONES:
 
OPCIÓN 1: Redondear resultado (simple)
function calculateTotal(prices: number[]): number {
  const total = prices.reduce((sum, price) => sum + price, 0);
  return Math.round(total * 100) / 100; // 2 decimales
}
 
OPCIÓN 2: Trabajar con centavos (recomendado para dinero)
function calculateTotal(prices: number[]): number {
  // Convertir a centavos (enteros)
  const totalCents = prices.reduce(
    (sum, price) => sum + Math.round(price * 100),
    0
  );
  // Convertir de vuelta a dólares
  return totalCents / 100;
}
 
OPCIÓN 3: Usar biblioteca de precisión decimal
import Decimal from 'decimal.js';
 
function calculateTotal(prices: number[]): number {
  return prices
    .reduce(
      (sum, price) => sum.plus(price),
      new Decimal(0)
    )
    .toNumber();
}
 
💡 RECOMENDACIÓN para tu caso:
Opción 2 (centavos) si es dinero real
Opción 1 (redondeo) si solo necesitas 2 decimales
 
🧪 TESTS SUGERIDOS:
test('maneja decimales correctamente', () => {
  expect(calculateTotal([0.1, 0.2])).toBe(0.3);
  expect(calculateTotal([1.1, 2.2, 3.3])).toBe(6.6);
  expect(calculateTotal([9.99, 0.01])).toBe(10.00);
});

Usuario: Después de actualizar dependencias, mi app no arranca:
 
Error: Cannot find module 'react-dom/client'
Require stack:
- /app/src/index.tsx
- /app/node_modules/react-scripts/scripts/start.js
 
npm ls react
myapp@1.0.0
├── react@17.0.2
└─┬ react-scripts@5.0.1
  └── react@18.2.0
 
Contexto:
- Actualicé React de 17 a 18
- Olvidé actualizar react-dom

Claude: Problema de versiones incompatibles detectado:
 
🔍 CAUSA:
React 18 movió el punto de entrada a 'react-dom/client',
pero tienes react-dom 17 que no tiene ese módulo.
 
📦 VERSIONES ACTUALES:
- react: 18.2.0 ✅
- react-dom: 17.0.2 ❌ (desactualizada)
- react-scripts: 5.0.1 (requiere React 18)
 
⚠️ CONFLICTO:
React Scripts 5 espera React 18, pero react-dom está en 17.
 
✅ SOLUCIÓN:
 
Paso 1: Actualiza react-dom
npm install react-dom@18.2.0
 
Paso 2: Actualiza el código de entrada (src/index.tsx)
 
ANTES (React 17):
import ReactDOM from 'react-dom';
import App from './App';
 
ReactDOM.render(
  <App />,
  document.getElementById('root')
);
 
DESPUÉS (React 18):
import { createRoot } from 'react-dom/client';
import App from './App';
 
const container = document.getElementById('root');
const root = createRoot(container!);
root.render(<App />);
 
Paso 3: Verifica package.json
Asegura que ambas versiones coincidan:
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}
 
🔄 COMANDOS A EJECUTAR:
npm install react-dom@18.2.0
# Luego actualizo src/index.tsx
npm start
 
📚 BREAKING CHANGES en React 18:
1. createRoot en lugar de ReactDOM.render
2. Automatic batching activado
3. Concurrent features disponibles
 
¿Quieres que aplique estos cambios?

Usuario: Mi página se vuelve muy lenta después de unos minutos:
 
Síntomas:
- Empieza rápido
- Después de 5 minutos, lag notable
- Después de 10 minutos, casi inutilizable
- Refrescar la página lo arregla temporalmente
 
Código sospechoso (Dashboard.tsx):
 
function Dashboard() {
  const [data, setData] = useState([]);
 
  useEffect(() => {
    const interval = setInterval(() => {
      fetchLatestData().then(newData => {
        setData(prev => [...prev, newData]);
      });
    }, 5000); // cada 5 segundos
 
    return () => clearInterval(interval);
  }, []);
 
  return (
    <div>
      {data.map(item => <DataCard key={item.id} data={item} />)}
    </div>
  );
}

Claude: Memory leak detectado:
 
🔍 CAUSA:
El array `data` crece indefinidamente.
Cada 5 segundos añades un elemento, nunca eliminas.
 
📊 CÁLCULO:
- 1 fetch cada 5 segundos
- 12 fetches por minuto
- 120 fetches en 10 minutos
- Si cada item ocupa 1KB → 120KB acumulados
- Más el DOM rendering de 120 elementos
 
📈 PROGRESIÓN:
Minuto 0: 0 items → Rápido
Minuto 5: 60 items → Empieza lag
Minuto 10: 120 items → Lento
Minuto 20: 240 items → Inutilizable
 
🐛 PROBLEMAS:
1. Array crece sin límite
2. React re-renderiza toda la lista cada vez
3. Acumulación de memoria
 
✅ SOLUCIONES:
 
OPCIÓN 1: Mantener solo últimos N elementos
function Dashboard() {
  const [data, setData] = useState([]);
  const MAX_ITEMS = 20; // Solo últimos 20
 
  useEffect(() => {
    const interval = setInterval(() => {
      fetchLatestData().then(newData => {
        setData(prev => {
          const updated = [...prev, newData];
          // Mantener solo últimos MAX_ITEMS
          return updated.slice(-MAX_ITEMS);
        });
      });
    }, 5000);
 
    return () => clearInterval(interval);
  }, []);
 
  return (
    <div>
      {data.map(item => <DataCard key={item.id} data={item} />)}
    </div>
  );
}
 
OPCIÓN 2: Reemplazar en lugar de acumular
function Dashboard() {
  const [data, setData] = useState(null);
 
  useEffect(() => {
    const interval = setInterval(() => {
      fetchLatestData().then(newData => {
        setData(newData); // Reemplazar, no acumular
      });
    }, 5000);
 
    return () => clearInterval(interval);
  }, []);
 
  return data ? <DataCard data={data} /> : null;
}
 
OPCIÓN 3: Paginación virtual (para muchos elementos)
import { FixedSizeList } from 'react-window';
 
function Dashboard() {
  const [data, setData] = useState([]);
 
  // ... (lógica de fetch con límite)
 
  return (
    <FixedSizeList
      height={600}
      itemCount={data.length}
      itemSize={80}
      width="100%"
    >
      {({ index, style }) => (
        <div style={style}>
          <DataCard data={data[index]} />
        </div>
      )}
    </FixedSizeList>
  );
}
 
💡 RECOMENDACIÓN:
- Si solo necesitas el dato más reciente → Opción 2
- Si necesitas historial limitado → Opción 1
- Si necesitas mostrar cientos de items → Opción 3
 
🧪 CÓMO VERIFICAR:
1. Abre Chrome DevTools → Performance
2. Graba durante 1 minuto
3. Verifica que memoria se estabilice
4. Verifica que no haya layout thrashing
 
¿Qué opción prefieres?

❌ Malo:
"Tengo un error con map"
 
✅ Bueno:
"Error: Cannot read property 'map' of undefined
En: UserList.tsx:23
Al: Cargar la página
Después de: Actualizar la API
Stack trace: [completo]
Código: [relevante]"

✅ Muy útil:
"Funcionaba ayer. Hoy actualicé:
- Express 4.17 → 4.18
- Node 16 → 18
- Añadí middleware de CORS"

✅ Ahorra tiempo:
"Ya intenté:
- Reinstalar node_modules → No funcionó
- Cambiar versión de React → No funcionó
- Revisar permisos → Todo OK"

✅ Información valiosa:
"Sistema: macOS 13.2
Node: 18.14.0
npm: 9.5.0
Entorno: Desarrollo local
Base de datos: PostgreSQL 14"

# Guardar output completo en archivo
npm start 2>&1 | tee debug.log
 
# Luego compartir con Claude
# Pega el contenido de debug.log

# Ver árbol de dependencias
npm ls <paquete>
 
# Ver versiones instaladas
npm list --depth=0
 
# Verificar incompatibilidades
npm ls | grep UNMET

# Ejecutar test específico con output detallado
npm test -- --verbose UserList.test.ts
 
# Con coverage
npm test -- --coverage --verbose
 
# Modo watch para debugging iterativo
npm test -- --watch

Claude detecta:
 
Error: listen EADDRINUSE: address already in use :::3000
 
✅ SOLUCIONES:
 
# Opción 1: Matar proceso en puerto 3000
lsof -ti:3000 | xargs kill -9
 
# Opción 2: Usar otro puerto
PORT=3001 npm start
 
# Opción 3: Encontrar qué está usando el puerto
lsof -i:3000

Claude detecta:
 
Error: Cannot find module 'express'
 
✅ CAUSAS COMUNES:
1. No instalaste el módulo → npm install express
2. Ruta incorrecta → Verifica el import
3. node_modules corrupto → rm -rf node_modules && npm install
4. Package en devDependencies pero necesitas en dependencies

Claude detecta:
 
Access to fetch at 'http://api.example.com' from origin 'http://localhost:3000'
has been blocked by CORS policy
 
✅ SOLUCIÓN (Backend):
 
const cors = require('cors');
 
app.use(cors({
  origin: 'http://localhost:3000', // O '*' para desarrollo
  credentials: true
}));

┌─────────────────────────────────────┐
│ 1. ERROR APARECE                    │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│ 2. CAPTURAR INFORMACIÓN             │
│  - Stack trace completo             │
│  - Código relevante                 │
│  - Contexto y cambios recientes     │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│ 3. COMPARTIR CON CLAUDE             │
│  "Tengo este error: [info completa]"│
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│ 4. CLAUDE ANALIZA                   │
│  - Identifica causa raíz            │
│  - Explica por qué ocurre           │
│  - Propone soluciones               │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│ 5. APLICAR SOLUCIÓN                 │
│  Claude implementa o tú lo haces    │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│ 6. VERIFICAR                        │
│  - Error desapareció? ✅            │
│  - Tests pasan? ✅                  │
│  - No hay regresiones? ✅           │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│ 7. DOCUMENTAR (opcional)            │
│  Añadir comentario explicativo      │
│  o test que prevenga regresión      │
└─────────────────────────────────────┘

❌ Onboarding tradicional:
- Día 1-2: Leer README desactualizado
- Día 3-5: Explorar carpetas manualmente
- Semana 2: Entender ~30% del código
- Semana 3: Hacer primera contribución pequeña
- Mes 1: Sentirse medianamente productivo
 
✅ Onboarding con Claude Code:
- Hora 1: Entender estructura completa
- Hora 2: Mapear flujos principales
- Hora 3: Identificar patrones y convenciones
- Día 1: Primera contribución
- Semana 1: Productivo en el proyecto

Tú: Analiza la estructura de este proyecto y explícala.

📁 ESTRUCTURA DEL PROYECTO
 
proyecto/
├── frontend/                → Aplicación React
│   ├── src/
│   │   ├── components/      → Componentes reutilizables
│   │   ├── pages/           → Páginas/rutas
│   │   ├── hooks/           → Custom React hooks
│   │   ├── services/        → Llamadas a API
│   │   ├── utils/           → Funciones utilitarias
│   │   ├── contexts/        → React Context (estado global)
│   │   └── types/           → Definiciones TypeScript
│   ├── public/              → Assets estáticos
│   └── package.json         → Dependencias frontend
│
├── backend/                 → API Node.js
│   ├── src/
│   │   ├── routes/          → Endpoints REST
│   │   ├── controllers/     → Lógica de negocio
│   │   ├── models/          → Esquemas de base de datos
│   │   ├── middleware/      → Middleware Express
│   │   ├── services/        → Servicios externos
│   │   └── utils/           → Utilidades
│   ├── tests/               → Tests del backend
│   └── package.json         → Dependencias backend
│
├── shared/                  → Código compartido
│   └── types/               → Tipos TypeScript compartidos
│
├── docs/                    → Documentación
│   ├── api/                 → Documentación de API
│   └── architecture/        → Diagramas y decisiones
│
└── scripts/                 → Scripts de automatización
    ├── deploy.sh
    └── seed-db.js
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
🏗️ ARQUITECTURA
 
Tipo: Monorepo
Frontend: React 18 + TypeScript
Backend: Node.js + Express + TypeScript
Base de datos: PostgreSQL
ORM: Prisma
Patrón: MVC (Model-View-Controller)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
📊 ESTADÍSTICAS
 
Frontend:
  - 42 componentes
  - 12 páginas
  - 18 custom hooks
  - 8 servicios API
 
Backend:
  - 15 endpoints
  - 8 modelos
  - 6 middlewares
  - 12 controladores
 
Total líneas de código: ~15,000
Cobertura de tests: 73%

Tú: ¿Cuáles son las dependencias principales y para qué sirven?

📦 DEPENDENCIAS CLAVE
 
FRONTEND
--------
 
react (18.2.0)
  → Biblioteca UI principal
  → Componentes funcionales + hooks
 
react-router-dom (6.14.0)
  → Enrutamiento SPA
  → Usado en: src/App.tsx para definir rutas
 
@tanstack/react-query (4.32.0)
  → Manejo de estado servidor
  → Cacheo y sincronización de datos
  → Usado en: todos los servicios de API
 
zustand (4.4.0)
  → Estado global ligero
  → Alternativa a Redux
  → Usado en: src/stores/ para auth y UI state
 
axios (1.4.0)
  → Cliente HTTP
  → Usado en: src/services/ para llamadas a API
 
zod (3.22.0)
  → Validación de esquemas
  → Runtime type checking
  → Usado en: formularios y validación de API responses
 
BACKEND
-------
 
express (4.18.2)
  → Framework web
  → Manejo de rutas y middleware
 
prisma (5.1.0)
  → ORM (Object-Relational Mapping)
  → Esquema en: prisma/schema.prisma
  → Migraciones en: prisma/migrations/
 
jsonwebtoken (9.0.1)
  → Autenticación JWT
  → Usado en: src/middleware/auth.ts
 
bcrypt (5.1.0)
  → Hash de passwords
  → Usado en: src/controllers/authController.ts
 
joi (17.9.2)
  → Validación de request body
  → Usado en: src/middleware/validation.ts
 
winston (3.10.0)
  → Logging estructurado
  → Configurado en: src/utils/logger.ts
 
DESARROLLO
----------
 
typescript (5.1.6)
  → Type safety en todo el proyecto
 
vitest (0.34.0)
  → Framework de testing
  → Más rápido que Jest
 
eslint + prettier
  → Linting y formateo
  → Configurado en: .eslintrc.js y .prettierrc

Tú: ¿Cómo funciona la autenticación en este proyecto?

🔐 FLUJO DE AUTENTICACIÓN
 
TECNOLOGÍA: JWT (JSON Web Tokens)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
1. REGISTRO (Sign Up)
 
   Frontend                     Backend                    Base de datos
   ────────                     ───────                    ─────────────
 
   [Formulario]
   - email
   - password
   - name
        │
        ↓ POST /api/auth/register
        │
        │                    [authController.ts:23]
        │                    1. Validar input (Joi)
        │                    2. Verificar email único
        │                    3. Hash password (bcrypt)
        │                         │
        │                         ↓ prisma.user.create()
        │                         │                       [users table]
        │                         │                       - Guarda usuario
        │                         ↓
        │                    4. Generar JWT
        │                    5. Retornar { token, user }
        ↓
   [Guarda token]
   localStorage.setItem('token', ...)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
2. LOGIN
 
   Frontend                     Backend                    Base de datos
   ────────                     ───────                    ─────────────
 
   [Formulario]
   - email
   - password
        │
        ↓ POST /api/auth/login
        │
        │                    [authController.ts:67]
        │                    1. Buscar usuario por email
        │                         │
        │                         ↓ prisma.user.findUnique()
        │                         │                       [users table]
        │                         ↓                       - Lee usuario
        │                    2. Comparar passwords
        │                       bcrypt.compare(input, hash)
        │                    3. Si válido: generar JWT
        │                    4. Retornar { token, user }
        ↓
   [Guarda token]
   localStorage.setItem('token', ...)
   [Actualiza estado]
   setUser(userData)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
3. REQUESTS AUTENTICADOS
 
   Frontend                     Backend
   ────────                     ───────
 
   [Request a API]
   headers: {
     Authorization: `Bearer ${token}`
   }
        │
        ↓ GET/POST/PUT/DELETE /api/*
        │
        │                    [middleware/auth.ts:12]
        │                    1. Extraer token del header
        │                    2. Verificar JWT
        │                       jwt.verify(token, SECRET)
        │                    3. Si válido: añadir userId a req
        │                       req.userId = decoded.userId
        │                    4. next() → continuar a controller
        │
        │                    [controller respectivo]
        │                    - Tiene acceso a req.userId
        │                    - Puede hacer queries filtradas
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
4. LOGOUT
 
   Frontend
   ────────
 
   [Logout button]
        │
        ↓
   localStorage.removeItem('token')
   setUser(null)
   navigate('/login')
 
   Nota: JWT es stateless, el backend no mantiene sesiones.
         El token expira automáticamente (configurado: 7 días)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
ARCHIVOS CLAVE:
 
Backend:
  - src/routes/auth.ts               → Rutas de auth
  - src/controllers/authController.ts → Lógica de login/register
  - src/middleware/auth.ts           → Middleware de verificación
  - src/utils/jwt.ts                 → Helpers para JWT
 
Frontend:
  - src/services/authService.ts      → API calls de auth
  - src/contexts/AuthContext.tsx     → Estado global de auth
  - src/hooks/useAuth.ts             → Hook para acceder a auth
  - src/components/ProtectedRoute.tsx → HOC para rutas privadas
 
CONFIGURACIÓN:
  - JWT_SECRET: Variable de entorno (backend/.env)
  - Expiración: 7 días (configurable en utils/jwt.ts:8)
  - Refresh tokens: NO implementado (considerar si necesario)

Tú: Explica el flujo de datos completo desde que el usuario hace clic
en "Crear producto" hasta que se guarda en la base de datos.

📊 FLUJO COMPLETO: CREAR PRODUCTO
 
┌─────────────────────────────────────────────────────────────┐
│ 1. FRONTEND: Usuario interactúa                            │
└─────────────────────────────────────────────────────────────┘
 
[ProductForm.tsx:45]
Usuario llena formulario:
  - name: "Laptop Dell"
  - price: 999.99
  - category: "electronics"
  - description: "..."
 
Click en "Crear" → handleSubmit()
 
┌─────────────────────────────────────────────────────────────┐
│ 2. VALIDACIÓN FRONTEND                                      │
└─────────────────────────────────────────────────────────────┘
 
[ProductForm.tsx:67]
const schema = z.object({
  name: z.string().min(3),
  price: z.number().positive(),
  category: z.string(),
  description: z.string().optional()
});
 
const result = schema.safeParse(formData);
if (!result.success) {
  // Mostrar errores
  return;
}
 
┌─────────────────────────────────────────────────────────────┐
│ 3. LLAMADA A API                                            │
└─────────────────────────────────────────────────────────────┘
 
[services/productService.ts:23]
export async function createProduct(data: CreateProductDto) {
  const response = await axios.post('/api/products', data, {
    headers: {
      'Authorization': `Bearer ${getToken()}`
    }
  });
  return response.data;
}
 
POST /api/products
Headers:
  - Authorization: Bearer eyJhbGc...
  - Content-Type: application/json
Body:
  {
    "name": "Laptop Dell",
    "price": 999.99,
    "category": "electronics",
    "description": "..."
  }
 
┌─────────────────────────────────────────────────────────────┐
│ 4. BACKEND: Middleware de autenticación                    │
└─────────────────────────────────────────────────────────────┘
 
[middleware/auth.ts:12]
1. Extraer token del header
2. Verificar con jwt.verify()
3. Si válido: req.userId = decoded.userId
4. next() → continuar
 
Si falla → 401 Unauthorized
 
┌─────────────────────────────────────────────────────────────┐
│ 5. BACKEND: Validación de request                          │
└─────────────────────────────────────────────────────────────┘
 
[middleware/validation.ts:34]
const productSchema = Joi.object({
  name: Joi.string().min(3).required(),
  price: Joi.number().positive().required(),
  category: Joi.string().valid('electronics', 'clothing', ...).required(),
  description: Joi.string().optional()
});
 
validate(productSchema)(req, res, next);
 
Si falla → 400 Bad Request
 
┌─────────────────────────────────────────────────────────────┐
│ 6. BACKEND: Controller                                      │
└─────────────────────────────────────────────────────────────┘
 
[controllers/productController.ts:45]
export async function createProduct(req, res) {
  try {
    const { name, price, category, description } = req.body;
    const userId = req.userId; // Del middleware auth
 
    // Llamar al servicio
    const product = await productService.create({
      name,
      price,
      category,
      description,
      userId // Asociar producto con usuario creador
    });
 
    res.status(201).json(product);
  } catch (error) {
    logger.error('Error creating product:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
}
 
┌─────────────────────────────────────────────────────────────┐
│ 7. BACKEND: Service Layer                                  │
└─────────────────────────────────────────────────────────────┘
 
[services/productService.ts:23]
export async function create(data: CreateProductData) {
  // Lógica de negocio adicional
 
  // Ej: Generar slug automático
  const slug = generateSlug(data.name);
 
  // Ej: Validar que categoría existe
  await validateCategory(data.category);
 
  // Guardar en DB
  const product = await prisma.product.create({
    data: {
      ...data,
      slug,
      createdAt: new Date()
    }
  });
 
  // Operaciones post-creación
  await logActivity('product_created', product.id);
  await cacheInvalidate('products:list');
 
  return product;
}
 
┌─────────────────────────────────────────────────────────────┐
│ 8. BASE DE DATOS: Prisma ORM                               │
└─────────────────────────────────────────────────────────────┘
 
Prisma genera SQL:
INSERT INTO products (
  id, name, price, category, description, slug, user_id, created_at
) VALUES (
  'uuid...', 'Laptop Dell', 999.99, 'electronics', '...',
  'laptop-dell', 'user_id...', '2024-01-15 10:30:00'
)
RETURNING *;
 
PostgreSQL ejecuta query y retorna el registro creado.
 
┌─────────────────────────────────────────────────────────────┐
│ 9. RESPUESTA BACKEND → FRONTEND                            │
└─────────────────────────────────────────────────────────────┘
 
HTTP 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Laptop Dell",
  "price": 999.99,
  "category": "electronics",
  "description": "...",
  "slug": "laptop-dell",
  "userId": "user_id...",
  "createdAt": "2024-01-15T10:30:00.000Z"
}
 
┌─────────────────────────────────────────────────────────────┐
│ 10. FRONTEND: Actualización de estado                      │
└─────────────────────────────────────────────────────────────┘
 
[ProductForm.tsx:89]
// React Query actualiza cache automáticamente
queryClient.invalidateQueries(['products']);
 
// Mostrar notificación de éxito
toast.success('Producto creado exitosamente');
 
// Navegar a lista de productos
navigate('/products');
 
// React Query refetch en ProductList
// → Lista actualizada incluye nuevo producto
 
┌─────────────────────────────────────────────────────────────┐
│ 11. FRONTEND: Re-render                                    │
└─────────────────────────────────────────────────────────────┘
 
[ProductList.tsx:34]
- useQuery refetch automático
- Lista se actualiza con el nuevo producto
- Usuario ve "Laptop Dell" en la lista
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
TIEMPO TOTAL: ~200-500ms
 
Desglose:
  - Validación frontend: ~5ms
  - Request HTTP: ~50ms
  - Middleware auth: ~10ms
  - Validación backend: ~5ms
  - Controller: ~5ms
  - Service logic: ~20ms
  - Query a DB: ~30ms
  - Response HTTP: ~50ms
  - Update UI: ~20ms
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
MANEJO DE ERRORES en cada capa:
 
Frontend:
  - Validación Zod falla → Mostrar errores en formulario
  - API retorna error → Mostrar toast de error
 
Backend:
  - Auth falla → 401 Unauthorized
  - Validación falla → 400 Bad Request con detalles
  - DB error → 500 Internal Server Error (error logged)
 
Base de datos:
  - Constraint violation → Prisma lanza error
  - Connection error → Service retry o error

Tú: ¿Qué patrones de diseño se usan en este proyecto?

🎨 PATRONES DE DISEÑO IDENTIFICADOS
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
1. MVC (Model-View-Controller)
 
   Backend estructurado en capas:
 
   MODEL (models/)
     ↓
   CONTROLLER (controllers/)
     ↓
   VIEW (JSON responses)
 
   Ejemplo:
   - Model: prisma/schema.prisma
   - Controller: src/controllers/userController.ts
   - View: JSON response
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
2. Repository Pattern
 
   [services/productService.ts]
 
   Abstracción de acceso a datos:
 
   class ProductRepository {
     async findAll() { ... }
     async findById(id) { ... }
     async create(data) { ... }
     async update(id, data) { ... }
     async delete(id) { ... }
   }
 
   Beneficio: Cambiar DB sin afectar controllers
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
3. Middleware Pattern
 
   [Express middleware]
 
   Request → Auth → Validation → Rate Limit → Controller → Response
 
   Cada middleware tiene una responsabilidad única.
 
   Ejemplo:
   app.post('/api/products',
     authMiddleware,      // Verificar auth
     validateMiddleware,  // Validar input
     rateLimitMiddleware, // Prevenir spam
     productController.create
   );
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
4. Factory Pattern
 
   [utils/logger.ts:23]
 
   function createLogger(service: string) {
     return winston.createLogger({
       defaultMeta: { service },
       transports: [...]
     });
   }
 
   Uso:
   const logger = createLogger('auth-service');
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
5. Singleton Pattern
 
   [utils/database.ts:12]
 
   let prismaInstance: PrismaClient | null = null;
 
   export function getPrisma() {
     if (!prismaInstance) {
       prismaInstance = new PrismaClient();
     }
     return prismaInstance;
   }
 
   Beneficio: Una sola conexión a DB
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
6. Dependency Injection
 
   [controllers/userController.ts:8]
 
   class UserController {
     constructor(
       private userService: UserService,
       private emailService: EmailService
     ) {}
 
     async create(req, res) {
       const user = await this.userService.create(...);
       await this.emailService.sendWelcome(user);
     }
   }
 
   Beneficio: Fácil de testear (mock services)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
7. Custom Hooks (React)
 
   [hooks/useAuth.ts]
   [hooks/useProducts.ts]
   [hooks/useDebounce.ts]
 
   Reutilización de lógica entre componentes.
 
   Ejemplo:
   function useAuth() {
     const { data, isLoading } = useQuery('user', fetchUser);
     const logout = () => { ... };
     return { user: data, isLoading, logout };
   }
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
8. Compound Components (React)
 
   [components/Modal/]
 
   <Modal>
     <Modal.Header>Title</Modal.Header>
     <Modal.Body>Content</Modal.Body>
     <Modal.Footer>Actions</Modal.Footer>
   </Modal>
 
   Componentes que trabajan juntos.
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
9. Error Handling Pattern
 
   [middleware/errorHandler.ts]
 
   Manejo centralizado de errores:
 
   app.use((err, req, res, next) => {
     logger.error(err);
 
     if (err instanceof ValidationError) {
       return res.status(400).json(...);
     }
 
     if (err instanceof UnauthorizedError) {
       return res.status(401).json(...);
     }
 
     // Default
     res.status(500).json(...);
   });
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
10. Observer Pattern (React Query)
 
    [hooks/useProducts.ts]
 
    Componentes "observan" datos:
 
    const { data } = useQuery('products', fetchProducts);
 
    Cuando datos cambian:
    → React Query notifica
    → Componentes re-renderizan automáticamente

Tú: ¿Qué convenciones de código debo seguir en este proyecto?

📝 CONVENCIONES DE CÓDIGO
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
NOMENCLATURA
------------
 
Variables y funciones:
  ✅ camelCase
  const userId = 123;
  function getUserById() { }
 
Clases y componentes:
  ✅ PascalCase
  class UserService { }
  function UserProfile() { }
 
Constantes:
  ✅ UPPER_SNAKE_CASE
  const API_BASE_URL = 'https://...';
  const MAX_RETRIES = 3;
 
Archivos:
  ✅ kebab-case para utils
  user-service.ts
  validation-helpers.ts
 
  ✅ PascalCase para componentes React
  UserProfile.tsx
  ProductCard.tsx
 
Tipos e Interfaces:
  ✅ Interfaces: I + PascalCase
  interface IUser { }
  interface IProduct { }
 
  ✅ Types: T + PascalCase
  type TUserRole = 'admin' | 'user';
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
ESTRUCTURA DE ARCHIVOS
-----------------------
 
Componentes React:
  ✅ Un componente por archivo
  ✅ Archivo mismo nombre que componente
 
  components/
    UserProfile/
      UserProfile.tsx        → Componente
      UserProfile.test.tsx   → Tests
      UserProfile.styles.ts  → Estilos (si styled-components)
      index.ts               → Re-export
 
Servicios:
  ✅ Sufijo "Service"
  userService.ts
  emailService.ts
 
Controllers:
  ✅ Sufijo "Controller"
  userController.ts
  productController.ts
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
IMPORTS
-------
 
Orden de imports:
  1. Externos
  2. Internos
  3. Tipos
  4. Estilos
 
  // Externos
  import React from 'react';
  import { useQuery } from '@tanstack/react-query';
 
  // Internos
  import { Button } from '@/components/Button';
  import { useAuth } from '@/hooks/useAuth';
 
  // Tipos
  import type { User } from '@/types/user';
 
  // Estilos
  import styles from './UserProfile.module.css';
 
Path aliases configurados:
  @ → src/
  @components → src/components/
  @hooks → src/hooks/
  @utils → src/utils/
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
TYPESCRIPT
----------
 
✅ HACER:
  - Tipos explícitos en parámetros de función
  - Interfaces para objetos complejos
  - Type guards cuando sea necesario
 
  function getUser(id: string): Promise<IUser> { }
 
  interface ICreateUserDto {
    email: string;
    password: string;
    name: string;
  }
 
❌ EVITAR:
  - any (prohibido por eslint)
  - type assertions innecesarios
  - tipos implícitos en exports
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
FUNCIONES
---------
 
✅ Arrow functions para la mayoría:
  const handleClick = () => { };
  const calculateTotal = (items: Item[]) => { };
 
✅ Function declaration para exportadas:
  export function getUserById(id: string) { }
 
✅ Async/await preferido sobre Promises:
  ❌ return fetch().then().catch()
  ✅ const data = await fetch()
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
COMENTARIOS
-----------
 
✅ JSDoc para funciones exportadas:
  /**
   * Obtiene un usuario por su ID
   * @param id - ID del usuario
   * @returns Usuario encontrado
   * @throws NotFoundError si el usuario no existe
   */
  export async function getUserById(id: string): Promise<IUser> { }
 
✅ Comentarios inline solo cuando sea necesario:
  // HACK: Temporal fix para bug #123
  // TODO: Refactorizar usando nuevo patrón
  // FIXME: Memory leak aquí
 
❌ NO comentar lo obvio:
  // Incrementa counter en 1
  counter++; // ❌ Innecesario
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
ERROR HANDLING
--------------
 
Backend:
  ✅ try/catch en controllers
  ✅ Errores específicos personalizados
 
  if (!user) {
    throw new NotFoundError('User not found');
  }
 
Frontend:
  ✅ Error boundaries para errores de React
  ✅ React Query maneja errores de API
 
  const { data, error, isError } = useQuery(...);
 
  if (isError) {
    return <ErrorMessage error={error} />;
  }
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
TESTING
-------
 
✅ Archivos de test: *.test.ts / *.test.tsx
✅ describe/test (no it)
✅ Nombres descriptivos
 
  describe('UserService', () => {
    describe('getUserById', () => {
      test('retorna usuario cuando existe', async () => { });
      test('lanza NotFoundError cuando no existe', async () => { });
    });
  });
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
CONFIGURACIÓN
-------------
 
Prettier:
  - Semi: true
  - Single quotes: true
  - Trailing comma: es5
  - Print width: 100
 
ESLint:
  - no-console: warn (permitido en desarrollo)
  - no-any: error
  - prefer-const: error
  - no-unused-vars: error
 
Git:
  - Commits: Conventional Commits
    feat: nueva funcionalidad
    fix: corrección de bug
    docs: documentación
    refactor: refactorización
    test: tests
    chore: tareas

Tú: ¿Dónde están los tests y cómo se ejecutan?

🧪 SISTEMA DE TESTS
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
UBICACIÓN
---------
 
Backend:
  backend/tests/
    ├── unit/           → Tests unitarios
    │   ├── services/
    │   ├── utils/
    │   └── models/
    ├── integration/    → Tests de integración
    │   ├── api/
    │   └── database/
    └── e2e/            → Tests end-to-end
 
Frontend:
  frontend/src/
    ├── components/
    │   └── UserProfile/
    │       └── UserProfile.test.tsx
    ├── hooks/
    │   └── useAuth.test.ts
    └── utils/
        └── validation.test.ts
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
FRAMEWORK
---------
 
Frontend y Backend: Vitest
Razón: Más rápido que Jest, mejor DX
 
Testing Library (Frontend):
  - @testing-library/react
  - @testing-library/user-event
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
COMANDOS
--------
 
# Backend
cd backend
 
# Todos los tests
npm test
 
# Tests en watch mode
npm test -- --watch
 
# Tests con coverage
npm test -- --coverage
 
# Tests específicos
npm test userService
 
# Solo unitarios
npm test -- unit/
 
# Solo integración
npm test -- integration/
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
# Frontend
cd frontend
 
# Todos los tests
npm test
 
# Watch mode
npm test -- --watch
 
# Coverage
npm test -- --coverage
 
# Tests de un componente específico
npm test UserProfile
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
COBERTURA ACTUAL
----------------
 
Backend:
  - Statements: 78%
  - Branches: 72%
  - Functions: 81%
  - Lines: 78%
 
Frontend:
  - Statements: 68%
  - Branches: 64%
  - Functions: 71%
  - Lines: 68%
 
Mínimo requerido: 70% (configurado en vitest.config.ts)
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
EJEMPLO: Test unitario
 
[backend/tests/unit/services/userService.test.ts]
 
import { describe, test, expect, vi } from 'vitest';
import { UserService } from '@/services/userService';
 
describe('UserService', () => {
  test('getUserById retorna usuario cuando existe', async () => {
    const mockUser = { id: '1', name: 'Test' };
    vi.spyOn(prisma.user, 'findUnique').mockResolvedValue(mockUser);
 
    const result = await UserService.getUserById('1');
 
    expect(result).toEqual(mockUser);
  });
});
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
EJEMPLO: Test de componente
 
[frontend/src/components/UserProfile/UserProfile.test.tsx]
 
import { render, screen } from '@testing-library/react';
import { UserProfile } from './UserProfile';
 
test('renderiza nombre del usuario', () => {
  const user = { id: '1', name: 'John Doe', email: 'john@example.com' };
 
  render(<UserProfile user={user} />);
 
  expect(screen.getByText('John Doe')).toBeInTheDocument();
});
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
CI/CD
-----
 
Los tests corren automáticamente en:
  - Pre-commit hook (lint-staged)
  - Pull requests (GitHub Actions)
  - Antes de deploy (pipeline)
 
Archivo: .github/workflows/test.yml

Tú: ¿Cuáles son los comandos más importantes que debo conocer?

⚡ COMANDOS ESENCIALES
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
DESARROLLO
----------
 
# Instalar dependencias
npm install
 
# Desarrollo (frontend + backend simultáneamente)
npm run dev
 
# Solo frontend
cd frontend && npm run dev
 
# Solo backend
cd backend && npm run dev
 
# Build de producción
npm run build
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
BASE DE DATOS
-------------
 
# Generar cliente Prisma
cd backend && npm run prisma:generate
 
# Crear migración
npm run prisma:migrate:dev
 
# Aplicar migraciones
npm run prisma:migrate:deploy
 
# Abrir Prisma Studio (GUI para DB)
npm run prisma:studio
 
# Seed de datos
npm run db:seed
 
# Reset completo de DB
npm run db:reset
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
TESTING
-------
 
# Todos los tests
npm test
 
# Tests en watch mode
npm test -- --watch
 
# Coverage
npm test -- --coverage
 
# Tests de un archivo específico
npm test userService
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
LINTING Y FORMATEO
------------------
 
# Lint
npm run lint
 
# Lint con fix automático
npm run lint:fix
 
# Format con Prettier
npm run format
 
# Check de format
npm run format:check
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
TYPESCRIPT
----------
 
# Type check
npm run typecheck
 
# Type check en watch mode
npm run typecheck:watch
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
GIT HOOKS (Husky)
-----------------
 
Automático en:
 
Pre-commit:
  → npm run lint
  → npm run typecheck
  → npm test (solo archivos staged)
 
Pre-push:
  → npm test (todos)
  → npm run build
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
DOCKER
------
 
# Build images
docker-compose build
 
# Levantar servicios
docker-compose up
 
# Levantar en background
docker-compose up -d
 
# Ver logs
docker-compose logs -f
 
# Detener servicios
docker-compose down
 
# Reset completo (incluye volúmenes)
docker-compose down -v
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
SCRIPTS ÚTILES
--------------
 
# Generar tipos TypeScript desde Prisma schema
npm run generate:types
 
# Analizar bundle size
npm run analyze
 
# Limpiar cache y reinstalar
npm run clean && npm install
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
WORKFLOW TÍPICO
---------------
 
# Día 1: Setup inicial
git clone <repo>
npm install
cp .env.example .env
# (Configurar variables de entorno)
npm run prisma:migrate:dev
npm run db:seed
npm run dev
 
# Desarrollo diario
git checkout -b feature/nueva-feature
npm run dev
# (Hacer cambios)
npm test
npm run lint:fix
git add .
git commit -m "feat: nueva feature"
# (Pre-commit hook corre automáticamente)
git push
# (Pre-push hook corre automáticamente)
# (Crear PR en GitHub)

✅ ¿Qué tipo de arquitectura usa? (MVC, Clean, Hexagonal)
✅ ¿Cómo se comunican frontend y backend? (REST, GraphQL, tRPC)
✅ ¿Qué base de datos usa y por qué?
✅ ¿Hay servicios externos integrados? (Stripe, AWS, etc.)
✅ ¿Cómo se maneja el estado global? (Redux, Zustand, Context)

✅ ¿Cómo funciona la autenticación? (JWT, sessions, OAuth)
✅ ¿Cómo se protegen las rutas? (middleware, guards)
✅ ¿Dónde se almacenan los tokens?
✅ ¿Hay refresh tokens implementados?
✅ ¿Qué medidas de seguridad hay? (CORS, rate limiting, etc.)

✅ Explica el flujo completo de [acción principal]
✅ ¿Cómo se manejan los errores en cada capa?
✅ ¿Hay cacheo? ¿Dónde y cómo?
✅ ¿Cómo se sincronizan datos entre cliente y servidor?

✅ ¿Qué convenciones de nomenclatura se usan?
✅ ¿Cómo se estructuran los archivos?
✅ ¿Hay guía de estilo documentada?
✅ ¿Qué patrones de diseño se usan?

✅ ¿Dónde están los tests?
✅ ¿Qué framework de testing se usa?
✅ ¿Cuál es la cobertura actual?
✅ ¿Cómo ejecuto los tests?
✅ ¿Hay tests e2e?

✅ ¿Cómo levanto el proyecto localmente?
✅ ¿Qué variables de entorno necesito?
✅ ¿Cómo se hace el deployment?
✅ ¿Hay pipeline de CI/CD?
✅ ¿Cómo se manejan las migraciones de DB?

□ Clonar repositorio
□ Instalar dependencias
□ Configurar variables de entorno
□ Levantar base de datos local
□ Ejecutar migraciones
□ Seed de datos de prueba
□ Levantar servidor de desarrollo
□ Verificar que todo funciona
□ Ejecutar tests
□ Leer documentación en /docs
□ Entender estructura del proyecto
□ Mapear flujos principales
□ Identificar patrones de código
□ Conocer comandos esenciales
□ Configurar IDE (extensiones, snippets)
□ Revisar issues abiertos
□ Hacer primera contribución pequeña

┌─────────────────────────────────────────────────┐
│  /code-review  (orquestador principal)          │
└─────────────────┬───────────────────────────────┘
                  │
      ┌───────────┴───────────┐
      │  Análisis Paralelo    │
      └───────────┬───────────┘
                  │
      ┌───────────┴────────────────────────────┐
      │                                        │
      ▼                                        ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Agente #1   │  │  Agente #2   │  │  Agente #3   │  │  Agente #4   │
│              │  │              │  │              │  │              │
│ Cumplimiento │  │ Cumplimiento │  │    Bugs      │  │  Histórico   │
│  CLAUDE.md   │  │  CLAUDE.md   │  │  Obvios      │  │  git blame   │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │                 │
       └─────────────────┴─────────────────┴─────────────────┘
                          │
                          ▼
                 ┌────────────────┐
                 │  Scoring 0-100 │
                 │  por problema  │
                 └────────┬───────┘
                          │
                          ▼
                 ┌────────────────┐
                 │ Filtro (>80)   │
                 │ Threshold      │
                 └────────┬───────┘
                          │
                          ▼
                 ┌────────────────┐
                 │ Reporte Final  │
                 └────────────────┘

# En una rama con cambios sin mergear
/code-review

🔍 Analizando cambios en el PR...
 
📋 Contexto detectado:
  - CLAUDE.md encontrado: .claude/CLAUDE.md
  - Archivos cambiados: 8
  - Líneas añadidas: +247
  - Líneas eliminadas: -103
 
🤖 Ejecutando análisis con 4 agentes en paralelo...
 
✅ Análisis completado
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 CRÍTICO (P1) - Score: 95
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
📁 src/auth/validateToken.ts:42
 
⚠️ Vulnerabilidad de seguridad: JWT sin verificación de expiración
 
Código actual:
```typescript
function validateToken(token: string) {
  const decoded = jwt.decode(token); // ❌ No verifica firma ni expiración
  return decoded;
}

function validateToken(token: string) {
  const decoded = jwt.verify(token, SECRET_KEY); // ✅ Verifica firma y expiración
  return decoded;
}

dates.map(d => new Date(d).toISOString());

// Si d ya es Date, evitar recreación
dates.map(d => (d instanceof Date ? d : new Date(d)).toISOString());

const data = users.filter(u => u.active);

const activeUsers = users.filter(user => user.active);

 
### Publicar como Comentario en PR
 
```bash
/code-review --comment

// ❌ Bug detectado
function divide(a: number, b: number) {
  return a / b; // No valida división por cero
}
 
// ✅ Sugerencia de Claude
function divide(a: number, b: number) {
  if (b === 0) {
    throw new Error('Cannot divide by zero');
  }
  return a / b;
}