ROADMAP
Construcción de una Aplicación Fullstack
con Desarrollo Asistido por Inteligencia Artificial (AI-Assisted Development)
Proceso paso a paso — de la idea al proyecto con persistencia de datos
Autor: Ing. Marcelo Casanovas
Julio 2026
Introducción
Este documento describe, paso a paso, el flujo de trabajo utilizado para diseñar, construir y documentar
una aplicación fullstack (backend en [Link] + frontend) apoyándose en un agente de Inteligencia
Artificial como copiloto de desarrollo. El enfoque combina arquitectura limpia (Clean Architecture),
documentación viva generada por IA, y revisión humana continua (Human in the Loop) en los puntos
críticos del proceso.
Para cada paso en el que se interactúa con el agente de IA, se incluye un recuadro con el prompt
sugerido, listo para adaptar y utilizar. Los pasos marcados como “Acción manual” son tareas que realiza
el desarrollador directamente, sin intervención del agente.
Se recomienda el uso de un agente ia de consola como Gemini o Claude
Paso 1. Generar la estructura de carpetas (Clean Architecture)
Se solicita al agente de IA que proponga una estructura de carpetas siguiendo los principios de
arquitectura limpia para una aplicación fullstack, separando responsabilidades entre backend
([Link]) y frontend.
PROMPT SUGERIDO
Actúa como arquitecto de software senior. Necesito la estructura de
carpetas para una aplicación fullstack:
- Backend: [Link] (Express o NestJS), aplicando Clean Architecture
(capas de dominio, aplicación, infraestructura y presentación/API).
- Frontend: [React / Vue / Angular — especificar], separando
componentes, páginas, servicios, hooks/stores y tipos.
Quiero solo la estructura de carpetas y archivos (árbol de
directorios), con una breve descripción de la responsabilidad de cada
carpeta. No generes código todavía. Indica también qué reglas de
dependencia debo respetar entre capas (por ejemplo, que el dominio no
dependa de infraestructura).
Paso 2. Crear la estructura de carpetas manualmente
ACCIÓN MANUAL (Human in the loop)
El desarrollador crea físicamente en su máquina/repositorio las carpetas y archivos propuestos por
la IA en el paso anterior, validando que la organización tenga sentido antes de avanzar.
Paso 3. Análisis de la arquitectura → "architecture_analisis.md"
Con la estructura ya creada, se pide al agente que la analice, valide su coherencia con la arquitectura
limpia propuesta y documente los hallazgos en un archivo Markdown.
PROMPT SUGERIDO
Analiza la estructura de carpetas actual del proyecto (recórrela de
forma recursiva) y compárala con los principios de Clean Architecture
que definimos inicialmente.
Genera un archivo llamado "architecture_analisis.md" que incluya:
1) Descripción de cada capa/carpeta y su responsabilidad.
2) Verificación de la regla de dependencias (¿alguna capa interna
depende de una externa?).
3) Inconsistencias o desviaciones respecto a la propuesta original.
4) Recomendaciones de mejora antes de comenzar a programar.
Paso 4. Construcción del documento MVP
ACCIÓN MANUAL (Human in the loop)
El desarrollador redacta el documento de MVP (Producto Mínimo Viable), detallando el problema
que la aplicación busca resolver, los usuarios objetivo, los requisitos funcionales (qué debe hacer la
app) y los requisitos no funcionales (rendimiento, seguridad, escalabilidad, usabilidad, etc.).
Prompt opcional de apoyo (si se desea ayuda de la IA para estructurar el documento, no para definir el
contenido de negocio): se recomienda utilizar el formato disponibilizado anteriormente
PROMPT SUGERIDO
Ayúdame a estructurar (no a inventar el contenido) un documento de MVP
para mi aplicación. Necesito las siguientes secciones: Problema a
resolver, Objetivo del producto, Usuarios/personas, Requisitos
funcionales, Requisitos no funcionales, Alcance (dentro/fuera del MVP)
y Criterios de éxito. Yo completaré el contenido de cada sección.
Paso 5. Consolidar arquitectura + MVP → "analisis_app.md"
Se entregan al agente los dos documentos generados hasta ahora (el MVP y
architecture_analisis.md) para que construya un documento consolidado con la visión completa del
proyecto: arquitectura, requisitos y usuarios.
PROMPT SUGERIDO
Adjunto dos documentos: (1) el documento de MVP y (2)
architecture_analisis.md.
En base a ambos, genera un archivo llamado "analisis_app.md" que
consolide:
- Resumen de la arquitectura a utilizar (capas, tecnologías, reglas de
dependencia).
- Todos los requisitos funcionales extraídos del MVP.
- Todos los requisitos no funcionales extraídos del MVP.
- Usuarios/roles del sistema y sus permisos.
- Cualquier restricción técnica relevante mencionada en los documentos.
El documento debe quedar listo para usarse como especificación única
antes de generar el código.
Paso 6. Generar el proyecto completo a partir de "analisis_app.md"
Con la especificación consolidada, se instruye al agente para que construya el proyecto completo
(backend, frontend, configuración base), respetando la arquitectura y los requisitos documentados.
PROMPT SUGERIDO
Usando exclusivamente el documento "analisis_app.md" como
especificación, genera el proyecto completo:
- Backend en [Link] siguiendo la arquitectura limpia definida,
implementando los requisitos funcionales descritos.
- Frontend correspondiente, consumiendo los endpoints del backend.
- Configuración inicial (variables de entorno de ejemplo, scripts de
arranque, linter/formatter).
- Respeta estrictamente la estructura de carpetas ya creada. No omitas
ningún requisito funcional ni no funcional listado en el documento.
Al finalizar, entrega un resumen de qué se implementó y qué quedó
pendiente.
Paso 7. Revisión manual del proyecto (Human in the Loop)
ACCIÓN MANUAL (Human in the loop)
El usuario revisa manualmente el código generado: ejecuta la aplicación, navega el frontend, prueba
los endpoints y valida que lo construido corresponda con lo especificado en analisis_app.md. Este
punto de control humano es clave antes de continuar iterando.
Paso 8. Iterar cambios y registrar versionamiento en
"[Link]"
A partir de la revisión, el usuario solicita cambios puntuales (estéticos o funcionales), especificando
claramente qué desea modificar. Se pide además que, desde este punto, cada cambio quede
registrado en un archivo de versionamiento.
PROMPT SUGERIDO
Necesito el siguiente cambio en el proyecto: [describir con precisión
el cambio estético o funcional, pantalla/componente afectado,
comportamiento esperado antes y después].
Realiza el cambio respetando la arquitectura y los estándares ya
definidos en el proyecto.
Crea un archivo llamado "[Link]" (si no existe) y registra
en él este cambio con: fecha, descripción del cambio, motivo,
archivos/módulos afectados y tipo (estético/funcional/fix).
A partir de ahora, cada vez que te pida un cambio nuevo, agrega una
entrada adicional en "[Link]" siguiendo el mismo formato,
sin eliminar el historial previo.
Paso 9. Analizar la persistencia de datos → "db_persistencia.md"
Se pide al agente un análisis detallado del backend y de cómo se maneja (o debería manejar) la
persistencia de datos, documentando absolutamente todos los detalles tanto en frontend como en
backend, incluyendo los datos del servidor de base de datos.
PROMPT SUGERIDO
Analiza a detalle el proyecto backend y la forma en que se gestiona (o
debería gestionarse) la persistencia de datos.
Genera un archivo llamado "db_persistencia.md" que documente de forma
exhaustiva:
- Modelo de datos / entidades y sus relaciones.
- Capa de acceso a datos en el backend (repositorios, ORM/driver
utilizado, migraciones).
- Cómo se refleja y consume la persistencia en el frontend (estados,
cache, sincronización).
- Datos de conexión al servidor de base de datos a utilizar: nombre del
motor, nombre del servidor/host, puerto, nombre de la base de datos,
usuario y contraseña.
[Aquí el usuario adjunta/reemplaza con los datos reales del servidor
local: host, puerto, nombre de BD, usuario, password].
- Estrategia de manejo de errores y transacciones.
⚠ Recomendación de seguridad
Buena práctica: evitar registrar contraseñas reales en texto plano dentro de un archivo .md versionado en
el repositorio. Se recomienda usar variables de entorno (.env, fuera de git) o un gestor de secretos, y que
db_persistencia.md referencie los nombres de esas variables en lugar del valor real.
Paso 10. Crear el entorno de base de datos en servidor local
ACCIÓN MANUAL (Human in the loop)
El usuario instala y configura el motor de base de datos en su servidor local (o entorno de
desarrollo), creando la base de datos, el usuario y los permisos correspondientes, según lo
documentado en db_persistencia.md.
Paso 11. Implementar la persistencia completa (Backend, Frontend
y API)
Con el entorno de base de datos ya disponible, se pide al agente que implemente la persistencia real
en todas las capas del proyecto, tomando como única fuente de verdad el documento
db_persistencia.md.
PROMPT SUGERIDO
Usando el documento "db_persistencia.md" como referencia única,
implementa la persistencia de datos de forma completa en el proyecto:
- Backend: conexión real a la base de datos, repositorios/entidades,
migraciones y manejo de errores.
- API: endpoints necesarios para exponer las operaciones CRUD/consultas
requeridas por el frontend.
- Frontend: consumo de la API, manejo de estados de carga/error, y
actualización de la interfaz según los datos persistidos.
Verifica que la conexión funcione contra el servidor de base de datos
local configurado y documenta cualquier variable de entorno nueva que
se requiera.
Registra este cambio en "[Link]" siguiendo el formato ya
establecido.
Próximos pasos
Este roadmap cubre el ciclo inicial de construcción con IA, desde la arquitectura hasta la persistencia
de datos. Las siguientes sesiones extenderán el flujo con dos bloques adicionales, clave para llevar el
proyecto a un estándar profesional:
Paso 12. Pruebas unitarias e integración
Se pedirá al agente de IA que genere pruebas unitarias para la lógica de dominio y de aplicación, y
pruebas de integración para los endpoints y la capa de persistencia, cubriendo casos límite y manejo
de errores, no solo el camino feliz.
Paso 13. Integración con versionamiento de código (Git)
Se formalizará el uso de Git como sistema de control de versiones real (commits atómicos, ramas por
funcionalidad, pull requests), complementando el registro de cambios en lenguaje natural que se
llevó en [Link] durante este roadmap.
¿Por qué esta metodología funciona?
El valor central de este roadmap es que convierte a la IA en un colaborador que trabaja sobre una
especificación explícita y trazable, en lugar de un generador de código a partir de instrucciones
sueltas. Cada paso produce un artefacto (un documento .md) que sirve como fuente de verdad para
el paso siguiente: la arquitectura alimenta el análisis, el análisis y el MVP alimentan la especificación
consolidada, y esa especificación —no la memoria de la conversación— es lo que finalmente se
convierte en código.
Esto tiene tres consecuencias importantes:
1. Trazabilidad: en cualquier momento se puede responder "¿por qué el sistema hace esto?"
señalando el documento que lo originó, en vez de intentar recordar en qué mensaje del chat se
pidió.
2. Repetibilidad: el proceso no depende de una sesión de chat particular ni de la memoria del
agente; los documentos pueden reutilizarse, revisarse entre varias personas o regenerarse con otro
modelo de IA.
3. Puntos de control humano: el desarrollador revisa y aprueba en momentos definidos (tras el
análisis de arquitectura, tras generar el proyecto, tras cada cambio), en vez de aceptar todo lo que la
IA produce de forma continua.
Diferencia con el "vibe coding"
El "vibe coding" —programar dejándose llevar por lo que la IA sugiere, sin especificación previa ni
documentación intermedia— es rápido para prototipos desechables, pero tiene límites claros en un
proyecto real:
Aspecto Este roadmap (spec-driven) Vibe coding
Punto de partida Documento de arquitectura y Prompt improvisado, sin
MVP acordados antes de generar requisitos escritos
código
Trazabilidad Cada decisión queda registrada Las decisiones viven solo en el
Aspecto Este roadmap (spec-driven) Vibe coding
en un .md (arquitectura, historial del chat
requisitos, cambios)
Revisión humana Puntos de control definidos Revisión ad hoc, si es que ocurre
(pasos 7 y 8)
Repetibilidad El proyecto puede regenerarse o Difícil de reproducir o explicar
auditarse a partir de los después
documentos
Escalabilidad del equipo Otro desarrollador puede Depende de quien tuvo la
sumarse leyendo los .md conversación original
Riesgo típico Mayor esfuerzo inicial en Deuda técnica oculta y requisitos
documentación no funcionales olvidados
En resumen: el vibe coding optimiza para velocidad inmediata; esta metodología optimiza para que
el resultado sea explicable, auditable y sostenible en el tiempo algo especialmente valioso en un
contexto educativo, donde el objetivo no es solo "que la app funcione", sino que los alumnos
entiendan y puedan justificar cada decisión técnica.
Fin del roadmap.