> ## Documentation Index > Fetch the complete documentation index at: https://ai-first.falcux.com/llms.txt > Use this file to discover all available pages before exploring further. # La cadena de artefactos > El flujo completo: Idea → PRD → Arquitectura → Schema → Contexto AI → Código > *Idea → PRD → Arquitectura → Schema → Contexto AI → Código* > > El flujo que convierte una idea en software funcional sin perder > el hilo en el camino. *** ## La historia de los 5 restarts En mis primeros laboratorios con AI coding agents, el flujo era simple: inicializar un proyecto con un stack, describir una idea en un par de líneas, y pedirle al agente que implementara. El primer resultado siempre parecía prometedor. La UI aparecía rápido, con menús, botones, y secciones que se veían completas. Pero al probar, la realidad era otra: la mayoría de las opciones eran mockups — se veían pero no hacían nada. Botones decorativos. Formularios que no enviaban. Navegación que no llevaba a ningún lado. Lo peor venía después, cuando empezaba a implementar las features de verdad. La AI cambiaba el diseño cada vez que le pedía algo nuevo. Funcionalidades se duplicaban en distintas partes de la interfaz. Features nuevas aparecían visibles en la UI pero sin funcionalidad real, mientras las anteriores dejaban de funcionar. Y cuando pedía ajustar el diseño, la AI perdía el contexto de lo que ya existía. Llegaba un punto — siempre llegaba — donde era imposible continuar. El proyecto se había convertido en capas de implementaciones parciales, sin coherencia entre ellas. La única opción era empezar de cero. Tuve que reiniciar un mismo MVP al menos 5 veces. Cada restart era un intento de descubrir cómo mantener el contexto del proyecto a lo largo de múltiples sesiones de implementación. Lo que descubrí, después de esos 5 intentos, no fue un truco de prompting ni una configuración mágica. Fue algo más fundamental: **la AI necesita saber qué está construyendo antes de escribir la primera línea de código.** Y esa información no se puede dar en un párrafo — necesita una cadena de documentos, cada uno alimentando al siguiente. Esa cadena es lo que este capítulo documenta. *** ## La cadena completa ``` Idea ↓ PRD (qué se construye y para quién) ↓ Arquitectura (cómo se estructura técnicamente) ↓ DB Schema (qué datos existen y cómo se relacionan) ↓ Contexto AI (AGENTS.md + GUIA_DISEÑO.md) ↓ Implementación con AI coding agent ↓ Documentación post-implementación ``` Cada eslabón produce un artefacto que el siguiente eslabón consume. Romper la cadena — saltar un eslabón — significa que la AI trabaja con información incompleta. A veces funciona. A veces produce los mockups decorativos del inicio de esta historia. *** ## Los eslabones en detalle ### Eslabón 1: PRD — El contrato de qué se construye **Qué es:** Un documento que describe el producto desde la perspectiva del usuario. Qué hace, para quién, qué problema resuelve, y cuáles son los límites de lo que se construye en esta fase. **Por qué es el eslabón más crítico:** De toda la cadena, el PRD es el único artefacto que no debería saltarse nunca. Sin PRD, la AI no tiene un norte. Puede generar código que funcione técnicamente pero que no resuelve el problema correcto, o que incluye features que nadie pidió mientras omite las que sí importan. **Quién lo produce:** Típicamente el PO o el product designer. En equipos pequeños, un LLM puede generar un borrador a partir de un documento de requerimientos o una descripción verbal — pero un humano debe validar que refleja lo que realmente se necesita. **Señales de un buen PRD para AI:** * Describe comportamiento esperado, no solo features ("el usuario puede registrar una decisión en 30 segundos" vs. "formulario de decisiones") * Define explícitamente qué NO se incluye en esta fase * Lista criterios de aceptación verificables * Es independiente de la implementación técnica **El error más común:** PRDs generados por AI que agregan features que nadie pidió. El LLM tiende a "completar" lo que parece faltar basándose en patrones de productos similares. Siempre validar que cada feature listada fue explícitamente solicitada. **Formato:** Markdown (`docs/PRD.md`). Puede dividirse por módulo si el producto es grande (`docs/PRD-MODULE1.md`, `docs/PRD-MODULE2.md`). *** ### Eslabón 2: Arquitectura — El plano técnico **Qué es:** Un documento que define cómo se estructura el sistema: qué tecnologías se usan, cómo se organizan las capas, cómo fluyen los datos, cómo se maneja la autenticación, y qué patrones de diseño se siguen. **Por qué importa para la AI:** Sin un documento de arquitectura, la AI toma decisiones arquitectónicas por ti. A veces acierta. A veces crea un monolito cuando necesitas microservicios, o pone lógica de negocio en los controllers cuando debería ir en use cases. El documento de arquitectura elimina esa ambigüedad. **Quién lo produce:** El tech lead o el developer senior. Un LLM puede generar un borrador basado en el PRD + el stack elegido, pero las decisiones de arquitectura son inherentemente humanas — dependen de contexto que la AI no tiene (tamaño del equipo, presupuesto de infraestructura, experiencia del equipo, requisitos de escalabilidad). **Qué incluir como mínimo:** * Stack tecnológico con versiones * Patrón de arquitectura (monolito, clean architecture, microservicios, etc.) * Estructura del proyecto (monorepo, multi-repo, carpetas) * Flujo de autenticación * Patrones de comunicación entre módulos * Decisiones técnicas y sus justificaciones **Cuándo se puede saltar:** En prototipos muy rápidos donde el objetivo es validar una idea en horas, no construir algo mantenible. Pero hay que ser honesto: si saltas la arquitectura, estás aceptando deuda técnica desde el día uno. **Formato:** Markdown (`docs/ARQUITECTURA.md`). *** ### Eslabón 3: DB Schema — La estructura de los datos **Qué es:** La definición de los modelos de datos, sus relaciones, y las reglas de integridad. En proyectos con Prisma, es el `schema.prisma`. En otros ORMs, sus equivalentes. **Por qué importa para la AI:** El schema de BD es el contrato más estricto del sistema. Si la AI empieza a implementar features sin saber qué datos existen y cómo se relacionan, va a inventar modelos sobre la marcha — y cada modelo inventado sobre la marcha es una migración futura que probablemente falle. **Quién lo produce:** Es el artefacto más variable. Tres escenarios comunes: 1. **El humano lo diseña completo:** Basándose en el PRD y la arquitectura, define los modelos antes de implementar. Máximo control, más tiempo. 2. **La AI lo propone, el humano valida:** Se le da el PRD y se le pide que proponga un schema. Rápido, pero hay que revisar con cuidado — la AI tiende a sobre-normalizar o crear relaciones que no se necesitan. 3. **Se define incrementalmente:** Se empieza con los modelos mínimos y se agregan conforme se implementan features. Funciona en MVPs, pero requiere disciplina en migraciones. **El gotcha de las migraciones:** Las migraciones de Prisma (y de otros ORMs) a veces fallan cuando la AI modifica el schema sin considerar los datos existentes. Esto es especialmente problemático cuando hay campos que pasan de opcionales a obligatorios, o cuando se renombran tablas. Documentar el estado actual del schema antes de cada cambio reduce significativamente estos problemas. **Formato:** El archivo del ORM (`packages/prisma/schema.prisma`) + documentación de las decisiones de modelado en `docs/ARQUITECTURA.md` o `docs/SPECS_POR_MODULO.md`. *** ### Eslabón 4: Contexto AI — La interfaz entre el humano y el agente **Qué es:** Los archivos que le dan a la AI la información que necesita para trabajar en el proyecto: AGENTS.md (reglas, comandos, restricciones), GUIA\_DISEÑO.md (cómo debe verse y comportarse la UI), y skills (conocimiento especializado on-demand). **Por qué es donde todo converge:** Los tres eslabones anteriores (PRD, arquitectura, schema) producen conocimiento. El contexto AI es donde ese conocimiento se traduce a instrucciones que la AI puede seguir. Sin este eslabón, los documentos anteriores existen pero la AI no los consulta automáticamente. **Qué incluye:** * `AGENTS.md` — El cerebro del proyecto. Reglas críticas, comandos, estructura, "What NOT to Do". Máximo \~150 líneas, el resto delegado a docs y skills. (Template: AGENTS\_MD\_TEMPLATE.md) * `GUIA_DISEÑO.md` — La guía visual. Tokens de color, tipografía, componentes, patrones de página, gotchas. Crece con el proyecto. (Template: GUIA\_DISENO\_TEMPLATE.md) * `.claude/skills/` (o equivalente) — Conocimiento especializado que se carga on-demand: clean architecture, testing, i18n, dominio del negocio. **El principio del AGENTS.md:** Cada línea debe responder a la pregunta "¿la AI cometería un error sin esta instrucción?" Si la respuesta es no, la línea no necesita estar ahí. **Cuándo se puede simplificar:** Para un prototipo rápido, un AGENTS.md mínimo con descripción del proyecto + stack + comandos + 5 reglas críticas es suficiente. La guía de diseño puede esperar hasta que haya UI que implementar. **Formato:** Markdown en la raíz del proyecto y en `docs/`. *** ### Eslabón 5: Implementación — Donde la AI trabaja **Qué es:** Las sesiones de implementación con el AI coding agent, siguiendo el Protocolo de Desarrollo de Features. **Cómo se alimenta de la cadena:** Cada sesión de implementación consume los artefactos anteriores: * El PRD le dice QUÉ construir * La arquitectura le dice CÓMO estructurarlo * El schema le dice QUÉ DATOS existen * El AGENTS.md le dice QUÉ REGLAS seguir * La GUIA\_DISEÑO le dice CÓMO DEBE VERSE Cuando todos los eslabones están en su lugar, la AI produce resultados consistentes desde el primer intento. Cuando falta alguno, la AI llena el vacío con suposiciones — y esas suposiciones son la causa de los mockups decorativos, las inconsistencias de diseño, y los restarts. *** ### Eslabón 6: Documentación post-implementación — Cerrar el loop **Qué es:** La actualización de la documentación después de cada sesión, siguiendo el Protocolo de Cierre de Sesión. **Por qué es un eslabón de la cadena y no un paso suelto:** La documentación que se produce al cerrar una sesión alimenta la siguiente sesión. El SESSION\_LOG.md le dice a la próxima sesión qué se hizo. Los anti-patrones descubiertos se agregan al AGENTS.md. Los gotchas de CSS se agregan a la GUIA\_DISEÑO. Sin este eslabón, cada sesión empieza desde cero — que es exactamente lo que causaba los restarts. *** ## Los artefactos: quién los produce y con qué | Eslabón | Artefacto | Quién produce | Con qué herramienta | | ------------------- | ------------------------------- | ------------------------------------------------- | -------------------------------------------------- | | PRD | `docs/PRD.md` | PO/Designer valida, LLM puede generar borrador | Claude.ai, ChatGPT, o cualquier LLM conversacional | | Arquitectura | `docs/ARQUITECTURA.md` | Tech lead/Dev senior decide, LLM puede documentar | LLM + conocimiento humano del contexto | | Schema | `schema.prisma` o equivalente | Variable: humano, AI propone, o incremental | Claude Code, herramienta de diseño de BD | | Contexto AI | `AGENTS.md` + `GUIA_DISEÑO.md` | Humano estructura, AI puede llenar detalles | Editor de texto + templates de Blueprint AI-First | | Implementación | Código fuente | AI coding agent ejecuta, humano valida | Claude Code, Antigravity, Cursor, etc. | | Post-implementación | SESSION\_LOG, docs actualizados | AI documenta, humano verifica | El mismo AI coding agent de la sesión | **Patrón predominante:** El humano define la estructura y valida. El LLM genera el contenido detallado. Esto aplica a casi todos los eslabones — la AI es excelente produciendo texto estructurado a partir de una dirección clara, pero mala decidiendo qué dirección tomar. *** ## Qué pasa cuando saltas un eslabón No todos los eslabones son obligatorios en todas las circunstancias. Pero saltar un eslabón tiene consecuencias predecibles: | Eslabón saltado | Consecuencia más probable | Cuándo es aceptable saltarlo | | ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ | | PRD | La AI implementa features que nadie pidió o ignora las que sí importan | Nunca — siempre tener al menos una spec mínima | | Arquitectura | La AI toma decisiones de arquitectura inconsistentes entre sesiones | Prototipos de validación rápida (menos de 1 día) | | Schema | Migraciones que fallan, modelos inventados sobre la marcha | Cuando la AI propone y el humano valida inmediatamente | | AGENTS.md | La AI no respeta convenciones, repite errores ya conocidos | Nunca en proyectos con más de 1 sesión | | GUIA\_DISEÑO | Inconsistencia visual, cada componente se ve diferente | Primera sesión de un MVP (se crea durante, no antes) | | Post-implementación | La siguiente sesión no tiene contexto, pendientes se pierden | Cambios triviales (fix de typo, ajuste cosmético) | **La regla práctica:** En un MVP rápido, el mínimo absoluto es PRD + AGENTS.md mínimo. Todo lo demás acelera la calidad pero no es bloqueante para empezar. Conforme el proyecto crece, la deuda de artefactos faltantes se acumula — y pagarla después siempre cuesta más que crearlos desde el inicio. *** ## La cadena adaptada por contexto No todos los proyectos necesitan la cadena completa al mismo nivel de detalle. ### Prototipo rápido (validar idea en horas) ``` Idea → Spec mínima (1 página) → AGENTS.md mínimo (50 líneas) → Implementar → Evaluar ``` Se saltan: arquitectura formal, schema previo, guía de diseño. Se aceptan las consecuencias: la AI va a tomar atajos. El objetivo no es calidad — es velocidad de validación. ### MVP serio (construir algo que se shippea) ``` Idea → PRD → Arquitectura → Schema → AGENTS.md completo + GUIA_DISEÑO básica → Implementar por features → Docs post-sesión ``` Todos los eslabones presentes. La guía de diseño empieza básica (tokens, layout, breakpoints) y crece con cada feature implementado. ### Producto en crecimiento (equipo, múltiples features en paralelo) ``` PRD por módulo → Arquitectura viva → Schema con migraciones controladas → AGENTS.md + skills + GUIA_DISEÑO madura → Protocolos completos (features, cambios, cierre, UX) ``` La cadena completa con los 4 protocolos activos. El AGENTS.md delega a skills para mantener el contexto ligero. La guía de diseño tiene cientos de líneas documentando cada componente y gotcha. *** ## El costo de la cadena vs. el costo de no tenerla La objeción más común: "Esto es mucho trabajo antes de empezar a codear." La respuesta está en los números: **Sin cadena de artefactos:** * 5 restarts de un MVP buscando cómo mantener contexto * 11 horas de un tech lead construyendo un prompt para un proyecto sin documentación * Features tipo mockup que hay que reimplementar * Inconsistencias de diseño que hay que corregir sesión tras sesión **Con cadena de artefactos:** * 2 horas implementando algo que hubiera tomado un sprint * Features que funcionan desde el primer intento * Sesiones que retoman donde quedó la anterior sin perder contexto * Una guía de diseño de 1134 líneas que crece sola mientras se construye El tiempo que inviertes en artefactos previos no es overhead — es la diferencia entre construir sobre una base sólida y construir sobre arena. *** ## Resumen accionable 1. **Siempre** empieza con un PRD o spec mínima — nunca le pidas a la AI que implemente una idea sin documentar qué es. 2. **El AGENTS.md es obligatorio** a partir de la segunda sesión — sin él, cada sesión es un restart parcial. 3. **Deja que la AI genere borradores** de PRD, arquitectura, y schema — pero valida todo antes de implementar. 4. **La guía de diseño crece con el proyecto** — no intentes escribirla completa al inicio. Empieza con tokens y layout, agrega componentes y gotchas conforme aparecen. 5. **Cierra cada sesión actualizando la documentación** — el eslabón de post-implementación es lo que hace que la cadena sea un ciclo, no una línea recta. 6. **Adapta la cadena al contexto** — un prototipo no necesita lo mismo que un producto en producción. Pero sé consciente de qué estás saltando y qué deuda estás asumiendo.