Saltar al contenido
Lección 10 de 12

Full-Stack en una Sesion — Construyendo Funcionalidades Completas

9 min read

La Sesion como Unidad de Trabajo

El desarrollo tradicional divide las funcionalidades en tickets, repartidos a lo largo de dias o semanas. Un cambio de base de datos hoy, un endpoint de API manana, el frontend la proxima semana. Este enfoque fragmentado introduce sobrecarga de coordinacion, perdida de contexto entre sesiones y bugs de integracion cuando las piezas finalmente se unen.

El enfoque 5.7x trata la sesion como la unidad de trabajo. Una sesion, una funcionalidad completa -- desde el esquema de base de datos hasta la UI desplegada. Esto es posible porque la IA maneja la velocidad de ejecucion mientras tu manejas la arquitectura y la revision.

Una sola sesion puede producir de manera realista:

  • Una migracion de base de datos con nuevas tablas y relaciones
  • Endpoints de API con validacion, manejo de errores y autenticacion
  • Componentes de frontend con gestion de estado y estilos
  • Tests cubriendo las rutas criticas
  • Actualizaciones de documentacion
  • Un commit y despliegue a produccion

La sesion no es una maraton de programacion. Es un periodo enfocado de dirigir, revisar y verificar. La mayor parte del tiempo se pasa tomando decisiones, no escribiendo codigo.

El Blueprint de Sesion

Cada sesion productiva sigue un blueprint:

Paso 1: Planificar la Funcionalidad (5-10 minutos)

Antes de que se genere cualquier codigo, define el alcance completo de la funcionalidad:

claude "/plan Necesito un sistema de preferencias de usuario. Aqui esta
       el alcance completo:

Base de datos:
- Nueva tabla 'preferences': id, user_id (FK), theme, language,
  email_notifications, created_at, updated_at

API:
- GET /api/preferences — devolver preferencias del usuario actual
- PUT /api/preferences — actualizar preferencias (actualizaciones parciales OK)
- Validacion con zod, autenticacion requerida

Frontend:
- Pagina de configuracion en /settings
- Toggle switches para tema y notificaciones
- Selector dropdown de idioma
- Boton de guardar con estado de carga y retroalimentacion de exito

Infraestructura:
- Migracion de base de datos con rollback
- Datos seed para desarrollo
- Tests de integracion para endpoints de API
"

Este paso de planificacion captura problemas de alcance antes de que se escriba cualquier codigo. Tambien le da a la IA el panorama completo, reduciendo la posibilidad de inconsistencias entre capas.

Paso 2: Crear la Lista de Tareas (2-3 minutos)

Divide el plan en una lista de tareas ordenada con conciencia de dependencias:

## Lista de Tareas

### Independientes (pueden paralelizarse)
- [ ] Migracion de base de datos
- [ ] Esquemas de validacion zod
- [ ] Componente UI de pagina de configuracion (con datos mock)

### Secuenciales (despues de dependencias)
- [ ] Rutas de API (necesita migracion + esquemas)
- [ ] Conectar UI a API (necesita API + UI)
- [ ] Tests de integracion (necesita API)

### Finales
- [ ] Verificacion end-to-end
- [ ] Commit y deploy

Paso 3: Ejecutar Tareas

Comienza con tareas independientes en paralelo:

# Ejecucion paralela de tareas independientes
claude --background "Crea la migracion de base de datos para la tabla
       preferences. Campos: id (uuid, PK), user_id (uuid, FK a users),
       theme (enum: light/dark, default light), language (enum: en/es,
       default en), email_notifications (boolean, default true),
       created_at, updated_at."

claude --background "Crea los esquemas de validacion zod para preferencias
       en src/lib/schemas/preferences.ts. Esquema para respuesta GET y
       cuerpo de solicitud PUT. El cuerpo PUT debe permitir actualizaciones
       parciales."

claude "Crea la pagina de Configuracion UI en src/app/settings/page.tsx.
       Usa datos mock por ahora. Incluye toggle switches para tema y
       notificaciones, selector de idioma, y boton de guardar con
       estado de carga."

Luego procede con tareas dependientes:

# Despues de que migracion y esquemas esten listos
claude "Crea las rutas de API para preferencias en
       src/app/api/preferences/route.ts. Usa el esquema de migracion
       y validadores zod. GET devuelve las preferencias del usuario
       actual. PUT actualiza con soporte parcial. Ambos requieren
       autenticacion via getServerSession."

# Despues de que API y UI esten listos
claude "Conecta la pagina de Configuracion a la API real. Reemplaza
       datos mock con llamadas a la API. Agrega estados de carga,
       manejo de errores y retroalimentacion de exito al guardar."

# Despues de que la API este completa
claude "Escribe tests de integracion para la API de preferencias. Prueba:
       GET sin auth (401), GET con auth (200 + datos), PUT con datos
       validos (200), PUT con datos invalidos (400), PUT sin auth (401)."

Paso 4: Build y Verificar (5-10 minutos)

Ejecuta el build completo y la suite de tests:

# Ejecutar migraciones
npx prisma migrate dev

# Ejecutar tests
npm test

# Build para detectar errores de tipos
npm run build

# Iniciar servidor de desarrollo para testing manual
npm run dev

Prueba la funcionalidad manualmente:

  • Navega a /settings
  • Verifica que las preferencias cargan correctamente
  • Cambia cada preferencia y guarda
  • Recarga la pagina para confirmar persistencia
  • Prueba estados de error (falla de red, errores de validacion)

Paso 5: Commit y Deploy (2-3 minutos)

# Revisar todos los cambios
git diff --stat

# Stage y commit
git add -A
git commit -m "feat: add user preferences with settings page, API, and tests"

# Desplegar
git push origin main

Ejemplo Real: Modo Oscuro en 19 Archivos

Asi se desarrollo una implementacion real de modo oscuro en una sola sesion:

Duracion de la sesion: 45 minutos

Desglose de tareas:
1. Infraestructura (5 min)
   - Instalar next-themes
   - Crear componente ThemeProvider
   - Envolver layout raiz en ThemeProvider
   - Agregar configuracion de modo oscuro en Tailwind

2. Actualizaciones de componentes (15 min, paralelizado)
   - Agente 1: Actualizar Navbar, Footer, Sidebar (3 archivos)
   - Agente 2: Actualizar componentes Card, Button, Badge (3 archivos)
   - Agente 3: Actualizar layouts de pagina y secciones de contenido (6 archivos)
   - Principal: Actualizar componentes de formulario y modales (4 archivos)

3. Toggle y persistencia (5 min)
   - Crear componente ThemeToggle
   - Agregar a Navbar
   - Configurar persistencia en localStorage
   - Deteccion de preferencia del sistema

4. Verificacion (10 min)
   - Probar modo claro en todas las paginas
   - Probar modo oscuro en todas las paginas
   - Probar cambio de preferencia del sistema
   - Probar persistencia al recargar pagina

5. Commit y deploy (5 min)
   - Revisar diff (19 archivos cambiados)
   - Commit y push
   - Verificar despliegue en produccion

Resultado: Modo oscuro completo en todo el sitio.
Archivos cambiados: 19
Estimacion manual: 3-4 horas

Gestionando Sesiones Largas

Algunas funcionalidades requieren sesiones mas largas de una hora. Aqui hay estrategias para mantener la efectividad:

Gestion de Contexto con /compact

A medida que tu conversacion crece, la ventana de contexto de Claude Code se llena. Usa /compact para resumir la conversacion y liberar espacio:

# Despues de completar un bloque importante de trabajo
/compact

# Claude resume lo que se logro y lo que queda pendiente
# Ahora tienes contexto fresco para el siguiente bloque

Cuando compactar:

  • Despues de completar un grupo de tareas (ej. todas las rutas de API listas, pasando al frontend)
  • Cuando notas que la IA empieza a perder contexto sobre decisiones anteriores
  • Antes de empezar un tipo de trabajo completamente diferente dentro de la misma sesion

Checkpointing para Seguridad

Crea checkpoints de git en hitos clave:

# Despues de que la infraestructura esta en su lugar
git add -A && git commit -m "checkpoint: infraestructura de preferencias"

# Despues de que las rutas de API funcionan
git add -A && git commit -m "checkpoint: rutas de API de preferencias"

# Despues de que la UI esta conectada
git add -A && git commit -m "checkpoint: UI de preferencias conectada"

Estos checkpoints te permiten revertir a cualquier hito si un paso posterior introduce problemas.

El Enfoque "Inbox Zero"

Trata tu lista de tareas como una bandeja de entrada. Limpia cada elemento antes de terminar la sesion:

## Lista de Tareas de la Sesion
- [x] Migracion de base de datos
- [x] Esquemas zod
- [x] Rutas de API
- [x] UI de pagina de configuracion
- [x] Conectar UI a API
- [x] Tests de integracion
- [x] Verificacion manual
- [x] Commit y deploy

No dejes la sesion con trabajo a medio terminar. Es mejor reducir el alcance y entregar algo completo que dejar una funcionalidad parcialmente implementada que requiere reconstruccion de contexto en la proxima sesion.

Ejemplo Real: 12 Proyectos de Portafolio en Una Sesion

Otro logro de una sola sesion: agregar 12 nuevas entradas de proyectos a un sitio de portafolio.

Cada proyecto requeria:
- Tarjeta de proyecto con imagen, titulo, descripcion, tags de stack tecnologico
- Pagina individual del proyecto con descripcion detallada
- Enlaces a GitHub y demo en vivo
- Categorizacion y ordenamiento correcto

Enfoque de la sesion:
1. Definir los 12 proyectos en una lista estructurada (10 min)
2. Crear entradas de datos de proyectos en paralelo (3 agentes, 15 min)
3. Verificar renderizado en la pagina de portafolio (5 min)
4. Ajustar estilos y orden (5 min)
5. Commit y deploy (5 min)

Tiempo total: 40 minutos
Estimacion manual: 4-6 horas

Plantilla de Planificacion de Sesion

Usa esta plantilla para planificar tu proxima sesion full-stack:

## Funcionalidad: [Nombre]
## Objetivo: Entregar en una sesion

### Alcance
- Base de datos: [tablas, migraciones]
- API: [endpoints, metodos]
- Frontend: [paginas, componentes]
- Tests: [que cubrir]

### Lista de Tareas (ordenada)
Independientes:
1. [ ] ...
2. [ ] ...

Secuenciales:
3. [ ] ... (depende de 1)
4. [ ] ... (depende de 2, 3)

Finales:
5. [ ] Verificar
6. [ ] Commit y deploy

### Criterios de Exito
- [ ] La funcionalidad trabaja para todos los casos de uso principales
- [ ] Los tests pasan
- [ ] El build tiene exito
- [ ] Desplegado en produccion

El blueprint de sesion es lo que hace posible el full-stack-en-una-sesion. Sin el, las sesiones degeneran en resolucion reactiva de problemas. Con el, trabajas sistematicamente a traves de un plan con dependencias claras, oportunidades paralelas y checkpoints de verificacion. Este enfoque estructurado, combinado con la velocidad de ejecucion de la IA, es como entregas funcionalidades que solian tomar una semana en una sola sentada.