Skip to main content

​
Capítulo 3: La cadena de artefactos

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ónArtefactoQuién produceCon qué herramienta
PRDdocs/PRD.mdPO/Designer valida, LLM puede generar borradorClaude.ai, ChatGPT, o cualquier LLM conversacional
Arquitecturadocs/ARQUITECTURA.mdTech lead/Dev senior decide, LLM puede documentarLLM + conocimiento humano del contexto
Schemaschema.prisma o equivalenteVariable: humano, AI propone, o incrementalClaude Code, herramienta de diseño de BD
Contexto AIAGENTS.md + GUIA_DISEÑO.mdHumano estructura, AI puede llenar detallesEditor de texto + templates de Blueprint AI-First
ImplementaciónCódigo fuenteAI coding agent ejecuta, humano validaClaude Code, Antigravity, Cursor, etc.
Post-implementaciónSESSION_LOG, docs actualizadosAI documenta, humano verificaEl 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 saltadoConsecuencia más probableCuándo es aceptable saltarlo
PRDLa AI implementa features que nadie pidió o ignora las que sí importanNunca — siempre tener al menos una spec mínima
ArquitecturaLa AI toma decisiones de arquitectura inconsistentes entre sesionesPrototipos de validación rápida (menos de 1 día)
SchemaMigraciones que fallan, modelos inventados sobre la marchaCuando la AI propone y el humano valida inmediatamente
AGENTS.mdLa AI no respeta convenciones, repite errores ya conocidosNunca en proyectos con más de 1 sesión
GUIA_DISEÑOInconsistencia visual, cada componente se ve diferentePrimera sesión de un MVP (se crea durante, no antes)
Post-implementaciónLa siguiente sesión no tiene contexto, pendientes se pierdenCambios 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.