8 documentos antes de pedir código
@ux.jonathanBlueprint de documentación para construir con IA: del vibe coding a Spec Driven Development, con la mirada de un Design Engineer.
El problema
Con IA es fácil pasar de una idea a software que funciona. El problema llega cuando la app crece: tu agente de código empieza a adivinar qué hace cada funcionalidad, cómo se ve, cómo se guardan los datos, cómo funciona la autenticación y dónde va cada archivo. Con el tiempo, cada parte de la app sigue supuestos distintos.
Dale suficiente contexto para que adivine menos e implemente más.
Cómo usar esta guía
- Abre cada documento en orden, del 01 al 08
- Resumen: cómo se ve lleno, con un proyecto real
- Plantilla: el .md completo para copiar
- Skills: lo que instalas para trabajarlo con tu agente
- Marca cada doc en el panel cuando lo tengas listo
Los 8 documentos
| Documento | Pregunta | Absorbe |
|---|---|---|
| PRD.md | ¿Qué construimos y cómo sabemos que está listo? | Historias, criterios de aceptación, roadmap |
| UX_FLOWS.md | ¿Qué hace el usuario y qué ve en cada estado? | Matriz de estados, casos borde |
| DESIGN_SYSTEM.md | ¿Cómo se ve y suena el producto? | Tokens, accesibilidad, contenido y UX writing |
| COMPONENTS.md | ¿Qué hace cada componente, en cada estado? | Contratos, Storybook, Figma |
| ARCHITECTURE.md | ¿Cómo funciona el sistema y dónde viven los datos? | Base de datos, API, entorno, errores, despliegue, decisiones |
| SECURITY.md | ¿Qué hay que proteger y cómo lo revisamos? | Secretos, auditorías con IA, infraestructura |
| TESTING.md | ¿Cómo probamos que funciona? | Playwright, QA visual, accesibilidad, seguridad, observabilidad |
| AGENTS.md | ¿Cómo debe trabajar el agente? | Reglas, flujo de trabajo, prompts, skills instaladas |
Estructura del proyecto
mi-app/
├── src/
├── tests/
├── docs/
│ ├── PRD.md
│ ├── UX_FLOWS.md
│ ├── DESIGN_SYSTEM.md
│ ├── COMPONENTS.md
│ ├── ARCHITECTURE.md
│ ├── SECURITY.md
│ ├── TESTING.md
│ └── AGENTS.md ← en Claude Code, CLAUDE.md
├── tokens.json
├── .env.example
└── package.json
Lo que agrega un Design Engineer
Con 8 documentos en docs/ cubres todo. Cada uno responde una pregunta, trae su plantilla completa y las skills que conviene instalar para trabajarlo con tu agente. Las partes marcadas Design Engineer son lo que casi ninguna guía cubre: convertir los artefactos de diseño en specs que el agente puede cumplir y las pruebas pueden verificar.
Las skills y los comandos de esta guía cambian rápido. Antes de instalar, abre el repositorio de cada una y confirma el comando vigente.