Los 14 documentos que tu IA necesita para programar tu app

Si programas con IA, conseguir que escriba código es lo fácil. Lo difícil es darle el contexto suficiente para que entienda cómo tiene que funcionar tu producto, cómo se construye y cómo saber que de verdad funciona. Lo que no le cuentas, se lo inventa.

Para eso sirven estos documentos. Son catorce, cada uno responde una pregunta que no responde ningún otro, y todos cuentan el mismo proyecto inventado para que veas cómo encajan: Turnio, una app de reservas para peluquerías.

Cómo se organizan

AGENTS.md va en la raíz, porque es lo que los agentes buscan al abrir un proyecto. El resto vive en docs/. Van en tres grupos: qué construyes, cómo se construye y cómo se trabaja.

turnio/
├── AGENTS.md                  ← el agente empieza aquí
├── CLAUDE.md                  ← una línea: @AGENTS.md
└── docs/
    ├── PRD.md                 qué y para quién
    ├── APP_FLOW.md            por dónde se mueve cada usuario
    ├── DESIGN_SYSTEM.md       cómo se ve
    ├── TRD.md                 cómo funciona por dentro
    ├── DATABASE.md            dónde viven los datos
    ├── API.md                 cómo se hablan las piezas
    ├── SECURITY.md            qué no se puede romper
    ├── CODE_STYLE.md          cómo se escribe
    ├── IMPLEMENTATION_PLAN.md en qué orden
    ├── TESTING.md             cómo sabes que funciona
    ├── DEPLOYMENT.md          cómo llega a producción
    ├── DECISIONS.md           por qué es así
    └── PROGRESS.md            dónde lo dejamos

No hace falta tener los catorce el primer día. Una landing se apaña con PRD, DESIGN_SYSTEM y AGENTS. Un MVP suma APP_FLOW, TRD, DATABASE, IMPLEMENTATION_PLAN y PROGRESS. Los demás llegan cuando hay usuarios y dinero de por medio. Lo importante es que la IA tenga un contexto claro y ordenado en lugar de adivinar.

En cada documento del árbol de ficheros puedes pulsar cualquier otro para saltar a él.

1. PRD.md: qué construyes y para quién

Es el documento del que salen todos los demás. Le dice a la IA qué problema resuelve el producto, para quién, qué entra en la primera versión y, casi más importante, qué no entra.

El error más común es no escribir «Fuera de alcance». Sin esa lista, la IA añade lo que le parece buena idea, y en una semana tienes un chat, un programa de puntos y ninguna reserva funcionando.

2. APP_FLOW.md: por dónde se mueve cada usuario

Convierte el PRD en recorridos: qué pantallas hay, en qué orden se pasa por ellas y qué ve el usuario en cada una. Evita que la IA se invente pantallas o se deje el camino de vuelta.

/                    landing
/[negocio]           página pública
/[negocio]/reservar  servicio y hueco
/reserva/[id]        cambiar o cancelar
/entrar  /registro
/panel               agenda de hoy
/panel/servicios
/panel/horario
/panel/clientes
/panel/ajustes       pagos y equipo

Lo que casi nadie escribe son los estados vacío y error y los caminos alternativos. Son justo lo que la IA no se imagina sola, y lo primero que se encuentra un usuario de verdad.

3. DESIGN_SYSTEM.md: cómo se ve y cómo se mueve

Colores, tipografía, espacios, componentes y movimiento, con valores exactos. Con él, cada pantalla nueva se parece a las anteriores; sin él, cada una estrena un gris y un radio distintos.

No basta con la paleta: escribe la regla de cada componente («un solo botón primario por pantalla») y cuánto duran las animaciones. Y si además quieres que no parezca hecha con IA, aquí tienes seis cosas que lo arreglan.

4. TRD.md: cómo funciona por dentro

El documento técnico: stack, arquitectura, estructura de carpetas y requisitos con cifras. Si el PRD dice qué, el TRD dice con qué y cómo.

turnio/
├─ app/
│  ├─ (publico)/[negocio]/   # página y reserva
│  ├─ (panel)/panel/         # zona privada
│  └─ api/v1/                # rutas de la API
├─ components/
│  ├─ ui/                    # shadcn adaptado
│  └─ booking/               # piezas de la reserva
├─ lib/                      # lógica, sin React
├─ supabase/migrations/
└─ docs/

Escribe las restricciones. «Sin servidor aparte» o «menos de 50 € al mes» son las frases que impiden que la IA te monte microservicios para una app de reservas.

5. DATABASE.md: dónde viven los datos

Las tablas, cómo se relacionan, quién puede leer y escribir cada una y cómo se cambia el esquema. Es el que más caro sale no tener: un error en la base de datos no se arregla con un despliegue.

businesses 1──n services
businesses 1──n staff 1──n availability
businesses 1──n customers 1──n bookings
services   1──n bookings n──1 staff
bookings   1──1 payments

# Base de datos local con los datos de prueba
supabase start && supabase db reset
# Nueva migración
supabase migration new add_no_show_to_bookings
# Tipos de TypeScript a partir del esquema
supabase gen types typescript --local > lib/database.types.ts

Pon en la base las reglas que no se pueden romper, como que un empleado no tenga dos citas a la vez. Una regla que solo vive en el código se la salta el primer endpoint que se olvida de ella.

6. API.md: el contrato entre las piezas

Cada endpoint con su método, quién puede llamarlo, qué recibe, qué devuelve y cómo falla. Con él, la IA escribe el frontend y el backend sin que se contradigan.

{
  "serviceId": "3f2a…",
  "staffId": "9b1c…",
  "startsAt": "2026-10-14T09:30:00Z",
  "customer": {
    "name": "Laura Gil",
    "phone": "+34600111222",
    "email": "laura@correo.com"
  }
}

{
  "data": {
    "bookingId": "c71d…",
    "status": "held",
    "heldUntil": "2026-10-01T10:10:00Z",
    "checkoutUrl": "https://checkout.stripe.com/…"
  }
}

Define los errores una vez y para todos. Si no, cada endpoint falla a su manera y el frontend se llena de casos especiales.

7. SECURITY.md: lo que no se puede romper

Las reglas de seguridad que el código cumple siempre, lo escriba quien lo escriba. La IA no escribe código inseguro por maldad: lo escribe porque nadie le ha dicho qué proteger.

Content-Security-Policy: default-src 'self'; frame-src https://checkout.stripe.com
Strict-Transport-Security: max-age=63072000; includeSubDomains
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=()

Escríbelas como reglas que se pueden comprobar («el business_id sale de la sesión, nunca del cuerpo»), no como deseos («la app debe ser segura»). La lista completa está en la guía para que no te hackeen.

8. CODE_STYLE.md: una sola forma de escribir

Nombres, carpetas, reglas del lenguaje y del framework, errores y commits. Hace que el código de cinco sesiones distintas parezca escrito por la misma persona.

components/booking/SlotPicker.tsx      # lo que se ve
lib/bookings/create-booking.ts         # lo que decide
lib/bookings/create-booking.test.ts    # lo que lo prueba
app/api/v1/bookings/route.ts           # solo valida y llama a lib/

// ✗ Así no
const d = await fetch('/api/v1/slots?s=' + s).then(r => r.json()) as any

// ✓ Así sí
const { data: slots, error } = await getFreeSlots({ serviceId, date })
if (error) return <SlotsError />

feat(bookings): retener el hueco 10 minutos mientras se paga
fix(slots): los huecos salían una hora corridos con el cambio de hora
docs(progress): cierre de la sesión del 29 de octubre

Un ejemplo de «así no, así sí» vale más que diez reglas. La IA imita mejor de lo que obedece.

9. AGENTS.md: por dónde empieza el agente

El único que va en la raíz y el primero que se lee. No repite a los demás: dice cuál leer según la tarea, cómo se trabaja y qué no se toca nunca. Claude Code lee CLAUDE.md y el resto de agentes, AGENTS.md; con una línea que importa uno desde el otro, sirven los dos.

npm run dev          # localhost:3000
npm run lint
npm run test         # Vitest
npm run test:e2e     # Playwright
supabase db reset    # base local limpia

# CLAUDE.md
@AGENTS.md

La tentación es meterlo todo aquí. Si AGENTS.md pasa de dos pantallas, el agente lo lee en diagonal. Que dirija, no que explique.

10. IMPLEMENTATION_PLAN.md: en qué orden

El proyecto partido en fases y tareas numeradas, cada una con lo que tiene que pasar para darla por hecha. La IA hace una tarea cada vez, y tú sabes exactamente cuál.

Lee AGENTS.md y PROGRESS.md.
Implementa solo la tarea 3.4 del plan.
Antes de escribir código, dime qué archivos
vas a tocar y cómo lo vas a probar.

El error es pedir «hazme la app» en un solo mensaje. Cada fase tiene que poder probarse sola; si no, cuando algo falla no sabes en cuál de las cuarenta cosas nuevas está.

11. TESTING.md: cómo sabes que funciona

Qué tipo de test para qué, los flujos que se prueban de punta a punta, los casos límite y cuándo se ejecuta cada cosa. Convierte «parece que funciona» en algo que se puede comprobar.

npm run test               # unitarios e integración
npm run test -- --watch    # mientras programas
npm run test:e2e           # Playwright
npm run test:e2e -- --ui   # viéndolo en el navegador

Nombra los casos límite de tu producto. En una app de reservas son el cambio de hora y dos personas cogiendo el mismo hueco, y la IA no los va a probar si no se los dices.

12. DEPLOYMENT.md: cómo llega a producción

No está en la mayoría de listas y es de los que más sustos ahorra: qué hay en cada entorno, qué variables hacen falta, en qué orden se sube cada cosa y cómo se deshace.

El plan de marcha atrás se escribe antes de necesitarlo: a las once de la noche y con la app caída, nadie lo improvisa bien. Las trece comprobaciones antes de subir a producción lo completan.

13. DECISIONS.md: por qué es así

Un registro de decisiones, cada una con su contexto, lo que se descartó y lo que cuesta. Impide que una IA sin memoria deshaga en cinco minutos algo que te costó una semana decidir.

## ADR-000: Título corto
Fecha · Estado: propuesta | aceptada | sustituida
Contexto: qué problema había
Decisión: qué se eligió
Alternativas: qué se descartó y por qué
Consecuencias: qué ganamos y qué pagamos

No escribas una por cada cosa. Solo cuando había dos opciones razonables o cuando deshacerlo sale caro.

14. PROGRESS.md: dónde lo dejamos

La memoria entre sesiones. La IA no recuerda la conversación de ayer, pero puede leer un archivo: qué está hecho, qué falta, en qué rama estás y qué ha fallado ya.

Lo más valioso son las trampas conocidas: cada error apuntado es un error que el agente no repite. Ciérralo al final de cada sesión con el segundo prompt del artículo.

Que los lea y que sigan siendo verdad

Un documento desactualizado es peor que ninguno, porque la IA se lo cree. Seis reglas para que no pase:

• Cada dato en un solo sitio. Si el precio de la señal está en el PRD y en la base de datos, un día dirán cosas distintas. Uno lo cuenta y el otro enlaza.
• En el mismo commit. El cambio de código que contradice un documento lo corrige en el mismo commit, no «luego».
• Cortos. Una o dos pantallas cada uno. Lo que no ayuda al agente a decidir, sobra.
• Nómbralos en el prompt. «Sigue DATABASE.md» funciona mejor que esperar a que lo encuentre.
• Cifras en vez de adjetivos. «Menos de 2,5 segundos» se puede comprobar; «rápido», no.
• Revísalos cada mes. Pide al agente que compare cada documento con el código y te diga dónde mienten.

Los tres prompts: el primero te hace las preguntas y escribe los documentos, el segundo cierra cada sesión y el tercero comprueba que la documentación sigue diciendo la verdad.