Qué documentar antes de desarrollar una aplicación con IA

Resumen ejecutivo: qué necesitas para documentar una aplicación con IA

Para documentar una aplicación con IA no necesitas nueve PDFs, un comité ni trescientas páginas. Necesitas una fuente de verdad que permita responder las preguntas importantes sin improvisar cada vez.

Yo partiría de ocho artefactos. Si el agente además puede ejecutar herramientas, modificar código y encadenar acciones por su cuenta, añadiría un noveno: la política de su agentic loop.

El agente solo sabe lo que el proyecto consigue explicarle

Una persona nueva en el equipo puede levantar la mano y preguntar por qué ese módulo funciona así. Un agente no lo hace por instinto. Trabaja con lo que tiene delante: archivos, instrucciones, código, herramientas y mensajes.

Por eso «ya se lo expliqué en el chat de ayer» no es contexto. Documentar una aplicación con IA significa precisamente conseguir que las decisiones que condicionan el software sobrevivan a la sesión: persistentes, versionadas y fáciles de encontrar.

OpenAI permite guiar Codex mediante archivos AGENTS.md. Claude Code utiliza archivos CLAUDE.md y reglas de proyecto. GitHub Copilot admite instrucciones personalizadas del repositorio.

1. PRD para documentar una aplicación con IA: decide el producto antes del stack

Si el PRD empieza discutiendo frameworks, ya hemos saltado una pregunta. El Product Requirements Document existe para fijar primero el problema, los usuarios, el valor, el alcance y las reglas que hacen que una funcionalidad sea correcta.

En la práctica, si vas a documentar una aplicación con IA, yo no bajaría de este mínimo para el PRD:

• Contexto y problema: qué ocurre hoy, quién lo sufre y por qué merece resolverse.
• Usuarios y roles: perfiles, necesidades, permisos y diferencias relevantes.
• Objetivos: qué resultado debe mejorar y cómo sabremos que ha ocurrido.
• Alcance: funcionalidades incluidas en la versión actual.
• Fuera de alcance: decisiones que el agente no debe incorporar «por si acaso».
• Reglas de negocio: condiciones, cálculos, transiciones y excepciones.
• Criterios de aceptación: resultados observables que permiten considerar una historia terminada.
• Métricas: adopción, tiempo ahorrado, tasa de éxito, errores o indicadores específicos del producto.
• Riesgos y dependencias: integraciones, datos, decisiones legales, terceros y bloqueos conocidos.

Un requisito vago y uno implementable

El segundo requisito es menos vistoso. Mejor. A cambio, ya habla de límites, seguridad, persistencia y trazabilidad. Varias decisiones que podrían acabar escondidas dentro de un controlador han quedado resueltas antes de escribir una línea.

# PRD.md

## 1. Resumen
## 2. Problema y evidencia
## 3. Usuarios y roles
## 4. Objetivos y métricas
## 5. Alcance de la versión
## 6. Fuera de alcance
## 7. Historias de usuario
## 8. Reglas de negocio
## 9. Criterios de aceptación
## 10. Riesgos, dependencias y preguntas abiertas

# PRD.md

## 1. Resumen
## 2. Problema y evidencia
## 3. Usuarios y roles
## 4. Objetivos y métricas
## 5. Alcance de la versión
## 6. Fuera de alcance
## 7. Historias de usuario
## 8. Reglas de negocio
## 9. Criterios de aceptación
## 10. Riesgos, dependencias y preguntas abiertas

2. App Flow para documentar una aplicación con IA: el camino feliz no basta

El PRD te dice qué puede hacer el producto. El App Flow te obliga a enseñar cómo ocurre de verdad.

Una lista de funcionalidades queda preciosa en una reunión. Luego llega el usuario sin datos, pierde la sesión a mitad del formulario, repite un pago o entra con un rol que nadie había probado. Ahí empieza la aplicación real.

Por eso, al documentar una aplicación con IA, para cada flujo importante dejaría por escrito:

• actor que inicia la acción;
• punto de entrada y precondiciones;
• secuencia de pantallas o pasos;
• decisiones y bifurcaciones;
• estado de carga, vacío, éxito y error;
• comportamiento ante permisos insuficientes;
• persistencia parcial y recuperación;
• notificaciones o efectos posteriores;
• resultado final y siguiente acción posible.

Ejemplo: invitar a una persona al equipo

1. El administrador abre “Equipo”.
2. Pulsa “Invitar persona”.
3. Introduce email y rol.
4. El frontend valida formato y campos obligatorios.
5. El backend comprueba:
   - pertenencia del administrador a la organización;
   - capacidad para asignar ese rol;
   - ausencia de invitación activa;
   - ausencia de usuario ya incorporado.
6. Si es válido:
   - crea una invitación con caducidad;
   - registra auditoría;
   - encola el email;
   - devuelve estado “pending”.
7. Si el email ya pertenece al equipo:
   - no crea otra invitación;
   - devuelve un error de dominio identificable;
   - la interfaz ofrece abrir la ficha del usuario.
8. El enlace caducado permite solicitar una nueva invitación.

1. El administrador abre “Equipo”.
2. Pulsa “Invitar persona”.
3. Introduce email y rol.
4. El frontend valida formato y campos obligatorios.
5. El backend comprueba:
   - pertenencia del administrador a la organización;
   - capacidad para asignar ese rol;
   - ausencia de invitación activa;
   - ausencia de usuario ya incorporado.
6. Si es válido:
   - crea una invitación con caducidad;
   - registra auditoría;
   - encola el email;
   - devuelve estado “pending”.
7. Si el email ya pertenece al equipo:
   - no crea otra invitación;
   - devuelve un error de dominio identificable;
   - la interfaz ofrece abrir la ficha del usuario.
8. El enlace caducado permite solicitar una nueva invitación.

En la práctica, ese flujo ya está hablando con frontend, backend, datos, correo, auditoría y tests a la vez. Un buen APP_FLOW.md no adorna la documentación. Evita que seis piezas implementen seis versiones distintas del mismo comportamiento.

3. Diseño técnico al documentar una aplicación con IA: el stack no es la arquitectura

Aquí es donde una idea empieza a pagar alquiler técnico. El documento de diseño —TDD, TSD o Tech Design Document— explica cómo se va a construir la solución y, sobre todo, por qué.

Ahora bien, es fácil convertir esta sección en una lista de compra: Next.js, PostgreSQL, Redis, Kubernetes. Suena técnico. Sigue sin ser una arquitectura.

Al documentar una aplicación con IA, lo que de verdad necesito encontrar en el diseño técnico es esto:

• Contexto de la solución: sistemas, usuarios y servicios externos.
• Arquitectura lógica: dominios, módulos, capas y responsabilidades.
• Arquitectura física: procesos, servicios, bases de datos, colas y despliegue.
• Stack y versiones: frameworks, runtimes, dependencias críticas y criterios de selección.
• Modelo de datos: entidades, relaciones, propiedad del dato, retención y migraciones.
• Integraciones: APIs, eventos, webhooks, autenticación y tratamiento de fallos.
• Seguridad: identidad, autorización, secretos, datos sensibles, auditoría y amenazas relevantes.
• Operación: logs, métricas, trazas, alertas, backups, rollback y recuperación.
• Calidad: estrategia de pruebas, análisis estático, revisión y criterios de despliegue.
• Decisiones y alternativas: qué se descartó y qué coste se acepta.

Incluye diagramas, pero acompáñalos de texto

Los diagramas C4, de secuencia o despliegue comprimen muy bien la arquitectura. También pueden engañar muy bien. Una flecha que pone «API» no te cuenta quién autentica, qué se reintenta, quién es dueño del dato ni qué pasa cuando el servicio cae.

flowchart LR
    UI[Aplicación web] --> API[API de aplicación]
    API --> AUTH[Servicio de identidad]
    API --> DB[(Base de datos)]
    API --> QUEUE[Cola de trabajos]
    QUEUE --> WORKER[Worker]
    WORKER --> MAIL[Proveedor de correo]
    API --> OBS[Logs, métricas y trazas]

El dibujo necesita letra pequeña útil: quién puede llamar a cada servicio, qué es síncrono, qué debe ser idempotente, cuánto vive un evento y qué ocurre después del tercer fallo. Si no, tienes un mapa bonito y pocas instrucciones para sobrevivir al viaje.

4. Frontend: que cada prompt no invente una aplicación distinta

Además, un agente puede fabricar ocho pantallas antes de que alguien se pregunte por qué hay cinco tarjetas distintas, tres escalas de espaciado y cuatro formas de mostrar un error. La velocidad también multiplica inconsistencias.

Las reglas de frontend sirven para que cada prompt no vuelva a inventar la interfaz. De hecho, la documentación para desarrollar con IA también debe fijar cómo se comporta la experiencia visual cuando cambian los datos, los permisos o el estado del sistema.

Como mínimo, dejaría cerrados estos puntos:

• sistema de diseño, tokens, tipografía, color, espaciado y densidad;
• librería de componentes y criterio para crear uno nuevo;
• estructura de páginas, layouts y navegación;
• formularios, validación, mensajes y confirmaciones;
• estados de carga, vacío, error, éxito y solo lectura;
• comportamiento responsive y dispositivos soportados;
• accesibilidad: teclado, foco, semántica, contraste y lectores de pantalla;
• gestión de estado, consultas, caché y sincronización;
• internacionalización, fechas, números y textos;
• pruebas de componentes y flujos críticos.

# FRONTEND_GUIDELINES.md

- Reutiliza componentes de `src/components/ui` antes de crear otros.
- No introduzcas colores fuera de los design tokens.
- Todo formulario debe definir:
  - validación de cliente;
  - errores del servidor;
  - estado de envío;
  - prevención de doble envío;
  - confirmación de éxito.
- Toda consulta remota debe contemplar loading, empty, error y retry.
- Las acciones destructivas requieren confirmación y describen el efecto.
- Los flujos críticos deben poder completarse con teclado.
- No añadas una dependencia de UI sin registrar la decisión.

# FRONTEND_GUIDELINES.md

- Reutiliza componentes de `src/components/ui` antes de crear otros.
- No introduzcas colores fuera de los design tokens.
- Todo formulario debe definir:
  - validación de cliente;
  - errores del servidor;
  - estado de envío;
  - prevención de doble envío;
  - confirmación de éxito.
- Toda consulta remota debe contemplar loading, empty, error y retry.
- Las acciones destructivas requieren confirmación y describen el efecto.
- Los flujos críticos deben poder completarse con teclado.
- No añadas una dependencia de UI sin registrar la decisión.

5. Backend: donde una suposición empieza a salir cara

En frontend una decisión inventada puede dejar un botón raro. En backend puede dejar una tabla que nadie sabe migrar, un permiso mal aplicado o un dato que nadie sabe borrar. Aquí el coste de improvisar sube rápido.

En backend, la documentación para agentes de código exige hacer explícito, al menos, lo siguiente:

• dominios y módulos: qué responsabilidad tiene cada área;
• capas: entrada, aplicación, dominio, persistencia e infraestructura;
• contratos de API: rutas, payloads, respuestas, errores y versionado;
• modelo de datos: entidades, claves, restricciones, índices y migraciones;
• autenticación y autorización: actor, tenant, rol, recurso y política;
• transacciones e idempotencia: cómo impedir operaciones dobles o estados parciales;
• trabajos asíncronos: colas, reintentos, tiempos de espera y cola de errores;
• archivos y almacenamiento: propiedad, permisos, caducidad y borrado;
• eventos y auditoría: qué se registra y cómo se correlaciona;
• observabilidad: logs estructurados, métricas, trazas y alertas;
• pruebas: unitarias, integración, contrato y end-to-end.

Documenta el lenguaje del dominio

De hecho, hay bugs que empiezan con una palabra. «Cliente», «cuenta», «organización», «tenant» y «workspace» parecen intercambiables hasta que dejan de serlo en producción. Si el equipo no distingue el lenguaje del dominio, el agente tampoco va a hacerlo por nosotros.

6. Contexto del agente: enseñarle dónde pisa en el repositorio

Hasta aquí ya sabemos qué construir y con qué límites. Falta algo más mundano: enseñarle al agente dónde pisa cuando entra en el repositorio.

Ese contexto suele vivir en AGENTS.md, CLAUDE.md, .github/copilot-instructions.md o equivalentes. Yo no los convertiría en otra wiki. Son la tarjeta de acceso y el cartel de normas: dónde mirar, qué comandos usar y qué no tocar.

Aquí cambia la escala: no basta con describir el producto; el agente también necesita contexto persistente del repositorio e instrucciones operativas como estas:

• estructura del repositorio y ubicación de cada tipo de código;
• comandos para instalar, ejecutar, comprobar, probar y construir;
• convenciones de nombres, tipado, errores y documentación;
• arquitectura que debe respetarse y dependencias prohibidas;
• criterios para añadir paquetes o modificar esquemas;
• pruebas obligatorias según el área modificada;
• archivos generados que no deben editarse manualmente;
• datos, secretos o entornos que no pueden utilizarse;
• formato esperado para planes, commits o pull requests;
• momento en el que debe detenerse y pedir una decisión.

# AGENTS.md

## Antes de modificar código
1. Lee `docs/PRD.md` y el flujo relacionado.
2. Consulta `docs/TECH_DESIGN.md`.
3. Localiza implementaciones equivalentes antes de crear patrones nuevos.
4. Expón las suposiciones si el requisito no está confirmado.

## Reglas
- No añadas dependencias de producción sin justificar la necesidad.
- No cambies contratos públicos fuera del alcance de la tarea.
- Mantén la lógica de negocio fuera de controladores y componentes visuales.
- Aplica autorización por organización en backend; no confíes en ocultar UI.
- No registres secretos, tokens ni datos personales completos.

## Validación
- Ejecuta lint y comprobación de tipos.
- Ejecuta las pruebas del módulo modificado.
- Añade pruebas para reglas de negocio nuevas.
- Resume archivos cambiados, decisiones y riesgos pendientes.

# AGENTS.md

## Antes de modificar código
1. Lee `docs/PRD.md` y el flujo relacionado.
2. Consulta `docs/TECH_DESIGN.md`.
3. Localiza implementaciones equivalentes antes de crear patrones nuevos.
4. Expón las suposiciones si el requisito no está confirmado.

## Reglas
- No añadas dependencias de producción sin justificar la necesidad.
- No cambies contratos públicos fuera del alcance de la tarea.
- Mantén la lógica de negocio fuera de controladores y componentes visuales.
- Aplica autorización por organización en backend; no confíes en ocultar UI.
- No registres secretos, tokens ni datos personales completos.

## Validación
- Ejecuta lint y comprobación de tipos.
- Ejecuta las pruebas del módulo modificado.
- Añade pruebas para reglas de negocio nuevas.
- Resume archivos cambiados, decisiones y riesgos pendientes.

7. Plan de implementación: cambios pequeños que todavía puedas revisar

En cambio, «Implementa todo el PRD» parece una forma rápida de avanzar. También es una forma rápida de conseguir un diff que nadie quiere revisar. Mezcla demasiadas decisiones y hace casi imposible saber dónde empezó el problema.

El plan de implementación convierte la arquitectura en cortes pequeños. En un desarrollo de software con IA, esta secuencia importa porque cada fase debería dejar algo que puedas enseñar, probar o romper de forma controlada.

Una tarea útil deja pocas dudas sobre estas cosas:

• objetivo y documento de origen;
• archivos o módulos afectados;
• dependencias y precondiciones;
• criterios de aceptación;
• pruebas que deben ejecutarse;
• riesgos y asuntos que no debe resolver;
• resultado que debe documentarse al terminar.

8. Agentic loop: el agente no tiene que acertar a la primera

Este es el detalle que cambia la forma de trabajar: el agente no necesita acertar toda la solución a la primera.

Puede mirar el sistema, hacer un movimiento pequeño, comprobar qué ocurrió y volver a decidir. Al documentar una aplicación con IA con autonomía real, ese comportamiento también debe quedar definido. Ese ciclo es el agentic loop: observar, decidir, actuar, verificar y replantear.

OBSERVE
   ↓
DECIDE
   ↓
ACT
   ↓
VERIFY
   ↓
REPLAN
   ↺

Salidas:
DONE · NEEDS HUMAN · STOP

Sin embargo, lo interesante no es que el agente pueda actuar. Es que el entorno pueda llevarle la contraria. Un test rompe su hipótesis. El esquema revela una restricción. Git enseña que aquel «cambio pequeño» toca doce archivos.

Herramientas, guardrails y condiciones de salida

Dar más herramientas a un agente es darle más palancas. Algunas leen archivos. Otras cambian datos. Por eso la autonomía necesita tres límites muy concretos:

• Herramientas: qué puede leer, modificar, ejecutar o consultar.
• Guardrails: mínimo privilegio, entornos separados, aprobaciones, límites de iteraciones o presupuesto, timeouts, trazabilidad y rollback.
• Stop conditions: cuándo termina, cuándo escala a una persona y cuándo debe detenerse por riesgo o falta de información.

Si cumple los criterios, termina. Si falta una decisión, pregunta. Si necesita salir del alcance, tocar producción o lleva varios intentos dando vueltas, se detiene. Un loop sin salida no es autonomía. Es una máquina consumiendo tiempo y tokens.

AGENTS.md y AGENTIC_LOOP.md no son lo mismo

# AGENTIC_LOOP.md

## Observe
Leer requisito, reglas, estado, tests y diff actual.

## Act
Permitido:
- leer y buscar archivos;
- modificar el módulo asignado;
- ejecutar lint, tipos y tests.

Requiere aprobación:
- dependencias de producción;
- migraciones destructivas;
- cambios de contratos públicos;
- cualquier acceso a producción.

## Verify
Ejecutar las validaciones del área modificada.
Revisar el diff antes de continuar.

## Stop
Detenerse si:
- se cumplen los criterios;
- falta una decisión;
- el cambio sale del alcance;
- varios intentos no aportan progreso;
- la siguiente acción requiere aprobación.

# AGENTIC_LOOP.md

## Observe
Leer requisito, reglas, estado, tests y diff actual.

## Act
Permitido:
- leer y buscar archivos;
- modificar el módulo asignado;
- ejecutar lint, tipos y tests.

Requiere aprobación:
- dependencias de producción;
- migraciones destructivas;
- cambios de contratos públicos;
- cualquier acceso a producción.

## Verify
Ejecutar las validaciones del área modificada.
Revisar el diff antes de continuar.

## Stop
Detenerse si:
- se cumplen los criterios;
- falta una decisión;
- el cambio sale del alcance;
- varios intentos no aportan progreso;
- la siguiente acción requiere aprobación.

9. Estado del proyecto: que cerrar el chat no borre la memoria

Mientras tanto, cierras el chat. Mañana abre otro agente. La semana que viene retoma la tarea otra persona. Si la decisión solo vivía en aquella conversación, una parte del proyecto acaba de perder la memoria.

PROJECT_STATUS.md no pretende sustituir Git, tickets ni pull requests. A cambio, dentro de una documentación viva para desarrollo con IA aporta algo más simple: evita que quien retoma el trabajo tenga que reconstruir la película desde los créditos.

• objetivo de la fase actual;
• funcionalidades terminadas y validadas;
• trabajo en curso;
• bloqueos y preguntas abiertas;
• deuda aceptada temporalmente;
• decisiones recientes y enlace a su ADR;
• próximo corte vertical recomendado;
• estado de pruebas, despliegue y migraciones.

# PROJECT_STATUS.md

Última actualización: 2026-08-07

## Objetivo actual
Completar el flujo de invitación y alta de miembros.

## Terminado
- Modelo Invitation y migración.
- Caso de uso CreateInvitation.
- Política de autorización por organización.
- Pruebas unitarias del dominio.

## En curso
- Endpoint POST /api/v1/invitations.
- Plantilla de correo.

## Bloqueos
- Confirmar duración de la invitación.
- Decidir si un email puede tener invitaciones activas en varias organizaciones.

## Siguiente paso
Finalizar contrato API y construir la pantalla de invitación.

## No abordar todavía
- Importación masiva.
- SSO corporativo.
- Roles personalizados.

# PROJECT_STATUS.md

Última actualización: 2026-08-07

## Objetivo actual
Completar el flujo de invitación y alta de miembros.

## Terminado
- Modelo Invitation y migración.
- Caso de uso CreateInvitation.
- Política de autorización por organización.
- Pruebas unitarias del dominio.

## En curso
- Endpoint POST /api/v1/invitations.
- Plantilla de correo.

## Bloqueos
- Confirmar duración de la invitación.
- Decidir si un email puede tener invitaciones activas en varias organizaciones.

## Siguiente paso
Finalizar contrato API y construir la pantalla de invitación.

## No abordar todavía
- Importación masiva.
- SSO corporativo.
- Roles personalizados.

Cuando una decisión arquitectónica tuvo alternativas reales, un ADR pequeño vale mucho: contexto, decisión, opciones descartadas y consecuencias. Así no reabres el mismo debate cada tres meses ni conviertes una solución provisional en una verdad religiosa.

Si el agente no encuentra la documentación, es como si no existiera

La documentación puede ser excelente y seguir siendo inútil si nadie sabe dónde encontrarla. Por eso, documentar una aplicación con IA también requiere una estructura predecible. Requisitos en un chat, arquitectura en una presentación, reglas en Drive y decisiones escondidas en comentarios no forman un sistema. Forman una búsqueda del tesoro.

/
├── AGENTS.md
├── README.md
├── docs/
│   ├── PRD.md
│   ├── APP_FLOW.md
│   ├── TECH_DESIGN.md
│   ├── FRONTEND_GUIDELINES.md
│   ├── BACKEND_STRUCTURE.md
│   ├── AGENTIC_LOOP.md
│   ├── IMPLEMENTATION_PLAN.md
│   ├── PROJECT_STATUS.md
│   ├── GLOSSARY.md
│   ├── SECURITY.md
│   ├── RUNBOOK.md
│   ├── adr/
│   │   ├── 0001-modular-monolith.md
│   │   └── 0002-async-email-delivery.md
│   └── diagrams/
│       ├── context.mmd
│       ├── containers.mmd
│       └── invitation-sequence.mmd
├── apps/
├── packages/
└── tests/

/
├── AGENTS.md
├── README.md
├── docs/
│   ├── PRD.md
│   ├── APP_FLOW.md
│   ├── TECH_DESIGN.md
│   ├── FRONTEND_GUIDELINES.md
│   ├── BACKEND_STRUCTURE.md
│   ├── AGENTIC_LOOP.md
│   ├── IMPLEMENTATION_PLAN.md
│   ├── PROJECT_STATUS.md
│   ├── GLOSSARY.md
│   ├── SECURITY.md
│   ├── RUNBOOK.md
│   ├── adr/
│   │   ├── 0001-modular-monolith.md
│   │   └── 0002-async-email-delivery.md
│   └── diagrams/
│       ├── context.mmd
│       ├── containers.mmd
│       └── invitation-sequence.mmd
├── apps/
├── packages/
└── tests/

El archivo raíz debería funcionar como recepción: te dice dónde está cada cosa. El detalle vive en documentos especializados y cada tarea carga solo lo que necesita.

No documentes una prueba de concepto como si fuera un banco

No documentaría igual una prueba de dos tardes que un producto con pagos y datos sensibles. Al documentar una aplicación con IA, el nivel de detalle debe crecer con el riesgo, la vida útil, el número de personas —y agentes— y el coste de equivocarse.

En una prueba de concepto puedes permitirte tirar código mañana. En un sistema con pagos, historiales académicos o datos sensibles, «ya lo arreglaremos después» deja de ser agilidad y empieza a parecer una estrategia de riesgo.

Usa la IA para documentar. No para decidir por ti

La propia IA puede ayudarte a documentar una aplicación con IA. Parece circular, pero es útil: puede ordenar preguntas, detectar huecos y redactar borradores. La trampa está en pedirle que rellene lo que tú todavía no has decidido.

Yo no empezaría con «genera un PRD completo». Empezaría haciendo que la IA pregunte.

1. Expón el problema y la evidencia. Describe el proceso actual, las personas implicadas y el coste de no cambiarlo.
2. Pide preguntas, no soluciones. Haz que el modelo detecte ambigüedades sobre usuarios, reglas, datos, permisos, integraciones y operación.
3. Clasifica cada afirmación. Confirmada, inferida, propuesta o desconocida.
4. Genera un primer documento. Mantén una sección visible de preguntas abiertas y supuestos.
5. Revísalo con producto y técnica. Un requisito válido para negocio puede ser inviable, inseguro o mucho más caro de lo previsto.
6. Deriva los documentos técnicos. El flujo nace del PRD; la arquitectura nace de ambos; las reglas concretan la arquitectura.
7. Busca contradicciones. Roles presentes en el PRD pero ausentes en permisos, estados del flujo sin modelo de datos o integraciones sin tratamiento de errores.
8. Aprueba una línea base. Versiona los documentos antes del primer bloque de implementación.

Prompt para iniciar la entrevista

Actúa como product engineer y arquitecto de software.

No redactes todavía el PRD ni propongas stack.

Primero, entrevista el proyecto para detectar decisiones ausentes.
Agrupa tus preguntas en:

1. Problema y evidencia
2. Usuarios y roles
3. Alcance y fuera de alcance
4. Reglas de negocio
5. Flujo y estados
6. Datos e integraciones
7. Seguridad y privacidad
8. Operación y soporte
9. Métricas y criterios de aceptación
10. Restricciones técnicas y organizativas

Para cada respuesta, clasifica la información como:
- Confirmada
- Inferida
- Propuesta
- Desconocida

No conviertas una inferencia en requisito.
Al terminar, resume contradicciones, riesgos y decisiones pendientes.

Actúa como product engineer y arquitecto de software.

No redactes todavía el PRD ni propongas stack.

Primero, entrevista el proyecto para detectar decisiones ausentes.
Agrupa tus preguntas en:

1. Problema y evidencia
2. Usuarios y roles
3. Alcance y fuera de alcance
4. Reglas de negocio
5. Flujo y estados
6. Datos e integraciones
7. Seguridad y privacidad
8. Operación y soporte
9. Métricas y criterios de aceptación
10. Restricciones técnicas y organizativas

Para cada respuesta, clasifica la información como:
- Confirmada
- Inferida
- Propuesta
- Desconocida

No conviertas una inferencia en requisito.
Al terminar, resume contradicciones, riesgos y decisiones pendientes.

Prompt para derivar el diseño técnico desde el PRD y el App Flow

Con base en el PRD y el APP_FLOW, genera un borrador de TECH_DESIGN.md.

Incluye:

1. Arquitectura lógica propuesta: capas, módulos y responsabilidades.
2. Stack sugerido con justificación breve.
3. Modelo de datos inicial: entidades y relaciones clave.
4. Integraciones necesarias y tratamiento de fallos.
5. Autenticación, autorización y datos sensibles.
6. Observabilidad, operación y recuperación.
7. Estrategia inicial de pruebas.
8. Decisiones abiertas y alternativas todavía no exploradas.

Reglas:
- No inventes restricciones técnicas que el PRD no justifica.
- Separa Confirmado, Inferido, Propuesto y Desconocido.
- Explica qué decisiones requieren validación humana.
- No conviertas una preferencia de stack en una necesidad arquitectónica.

Con base en el PRD y el APP_FLOW, genera un borrador de TECH_DESIGN.md.

Incluye:

1. Arquitectura lógica propuesta: capas, módulos y responsabilidades.
2. Stack sugerido con justificación breve.
3. Modelo de datos inicial: entidades y relaciones clave.
4. Integraciones necesarias y tratamiento de fallos.
5. Autenticación, autorización y datos sensibles.
6. Observabilidad, operación y recuperación.
7. Estrategia inicial de pruebas.
8. Decisiones abiertas y alternativas todavía no exploradas.

Reglas:
- No inventes restricciones técnicas que el PRD no justifica.
- Separa Confirmado, Inferido, Propuesto y Desconocido.
- Explica qué decisiones requieren validación humana.
- No conviertas una preferencia de stack en una necesidad arquitectónica.

Errores al documentar para desarrollar con IA: antes y después

Algunos errores se entienden mejor sin teoría. Pones la versión que solemos escribir con prisa al lado de la versión que realmente permite trabajar y la diferencia aparece sola.

Documentación viva: si actualizarla duele, dejará de actualizarse

La documentación útil envejece al mismo ritmo que el código. Por tanto, documentar una aplicación con IA también implica mantener esa fuente de verdad cerca del repositorio. Si actualizarla requiere una reunión especial, una plantilla de veinte campos y permiso de tres personas, pronto dejará de actualizarse.

• Versiona en Git los documentos que condicionan la implementación.
• Asigna propiedad: producto mantiene requisitos; arquitectura mantiene decisiones; cada equipo mantiene sus guías.
• Incluye documentación en la definición de terminado cuando cambia comportamiento, contrato o operación.
• Enlaza cada tarea con la sección concreta que la justifica.
• Automatiza lo comprobable: esquemas, contratos, diagramas, referencias rotas y ejemplos ejecutables.
• Archiva decisiones sustituidas sin borrar la historia que explica la migración.
• Revisa por riesgo: más frecuencia para seguridad, contratos e integraciones; menos para contexto estable.

Hay una práctica barata que funciona muy bien: al terminar, pide al agente que diga qué documentación ha quedado desfasada. No hace falta darle permiso para reescribirla a ciegas. Primero que señale la grieta.

Checklist para documentar una aplicación con IA antes del primer commit

Resumen de una página: antes de dejar que el agente programe

Conclusión: documentar una aplicación con IA sigue siendo una decisión humana

Generar la primera implementación ya no es la parte cara. Puedes tener pantallas, endpoints y tests en horas. Lo que no se ha abaratado es decidir qué producto quieres, qué reglas no puede romper, cómo proteges el dato y quién responde cuando algo sale mal.

Ese es el cambio que merece atención.

Antes, una ambigüedad podía sobrevivir semanas en una reunión. Ahora puede aterrizar en producción convertida en código esa misma tarde.

Por eso documentar una aplicación con IA no es papeleo antes del trabajo. Es parte del control del sistema. El PRD fija el producto. El flujo, el comportamiento. El diseño técnico, la arquitectura. Las reglas, la forma de construir. El agentic loop, hasta dónde puede actuar el agente. El plan marca el siguiente paso. El estado conserva la memoria.

Con esas piezas, el agente deja de adivinar el proyecto mientras lo construye. Puede ejecutar decisiones explícitas, recibir feedback real, detenerse cuando toca y producir cambios que una persona todavía puede entender y revisar.

Lecturas relacionadas

• Modernización de software legacy con IA: comprender antes de reescribir.
• Auditoría técnica de software: qué revisar antes de seguir construyendo.
• Interoperabilidad, datos y agentes de IA en sistemas conectados.
• Consultoría tecnológica y arquitectura de software.

Preguntas frecuentes sobre documentación y desarrollo con IA

Documentación, alcance y diseño técnico

Contexto del repositorio, herramientas y mantenimiento

Agentic loop, autonomía y ejecución