Spec-driven development con Claude — specs antes que código

> Necesito agregar paginación a la lista de pedidos. NO escribas código todavía.

Antes de codear, escribime una spec en docs/specs/pedidos-pagination.md con:
- Qué API expone (endpoint, params, response shape)
- Cómo se compone con el frontend
- Edge cases: página vacía, filtros que cambian, navegación con browser back
- Performance esperada: latencia objetivo, índices que necesita la DB
- Out of scope: qué NO incluye esta feature

> Perfecto. Ahora listame los archivos que vas a tocar y en qué orden vas a
  hacer los cambios. No empieces todavía.

1. lib/db/queries/orders.ts — agregar limit/offset args
2. lib/api/orders/route.ts — exponer params en el endpoint
3. components/OrdersList.tsx — UI de paginación
4. components/OrdersList.test.tsx — tests
5. migrations/202605_orders_index.sql — índice si hace falta

> Dale, implementá siguiendo la spec y el plan. Hacé los cambios en el orden
  que listaste. Después de cada archivo, decime "listo X" y pasá al siguiente.

# Spec: [Feature]

## 1. Problema
2-3 líneas. ¿Qué problema resuelve y para quién?

## 2. Solución propuesta
1 párrafo describiendo el approach. Incluí "por qué este approach y no otros considerados".

## 3. API / Interface
Si es backend: endpoints, params, response shape.
Si es frontend: props de componentes, estados que maneja.
Si es lib: funciones exportadas con sus signatures.

## 4. Modelo de datos (si aplica)
- Tablas nuevas / columnas nuevas
- Relaciones
- Migraciones necesarias

## 5. Flujo end-to-end
Paso a paso del happy path. Cómo se ve el flujo desde input del usuario hasta efecto observable.

## 6. Edge cases
Lista. Para cada uno: comportamiento esperado.
- Input vacío
- Permisos insuficientes
- Timeouts
- Datos corruptos
- Race conditions

## 7. Performance / scale
- Latencia objetivo
- Throughput esperado
- Índices/cache que necesita
- Qué pasa si crece 10×

## 8. Seguridad
- Qué input se valida
- Permisos requeridos
- Logging / auditoría

## 9. Out of scope
Lista explícita de cosas que NO incluye esta spec. Esto evita que Claude (o vos) agregue features sin pensar.

## 10. Tests
- Unit tests críticos
- Integration tests si hay flujo multi-componente
- E2E si la feature toca UI

---
name: spec-first
description: Para features grandes (>3 archivos o cambios estructurales), forzá
  escribir una spec antes de tocar código. Úsala cuando el usuario diga
  "necesito implementar", "agregame la feature X" o describe algo que va a
  requerir varios archivos.
---

# Spec-first workflow

Cuando el usuario pide implementar algo no trivial, NO escribas código.

## Protocolo

### Paso 1
Detectá el alcance. Si es chico (1 archivo, < 30 minutos), seguí normal.
Si es grande, pasá al paso 2.

### Paso 2
Pediime confirmar que querés modo spec-first. Si dice sí:

a) Generá una spec en `docs/specs/<slug>.md` siguiendo el template:
   [acá pegás el template de arriba]

b) Mostrame el draft. Esperá feedback. NO toques código.

### Paso 3
Cuando la spec esté aprobada, listame los archivos a modificar en orden
de dependencia (primero modelo, después lógica, después UI, después tests).
Esperá confirmación del plan.

### Paso 4
Recién ahora implementá. Archivo por archivo. Después de cada uno, pausá
y reportá "listo X". Esperá ok para el siguiente.

## Reglas

- No proponer un approach radicalmente distinto al de la spec sin avisar
- Si descubrís un problema con la spec mientras codeás, parar y discutirlo
- La spec se mergea al repo junto con el código

> Agregame paginación en la lista de pedidos.
Claude implementa con cursor pagination.
> Pero quiero offset, no cursor.
Claude rehace, pero deja el cursor en algunos lados.
> Sacá el cursor.
Claude saca, pero rompe los tests.
> Arreglá los tests.
Claude arregla, pero la nueva paginación no respeta los filtros.
...

> Necesito agregar paginación a pedidos. Hacé la spec primero.
[Claude escribe docs/specs/pedidos-pagination.md]
> Cambiá "cursor" por "offset", y aclará que respeta los filtros activos.
[Claude actualiza la spec]
> Perfecto. Dale, implementá.
[Claude implementa de una toma]