Metodología de Documentación y Desarrollo Asistido por IA

Metodología personal del driver (válida para equipos pequeños) para proyectos de principio a fin usando agentes como Claude Code, Codex o Antigravity CLI. El principio central: cada documento es una unidad atómica, enlazada a las demás por IDs y menciones, nunca por duplicación de contenido. Ningún documento repite información que ya vive en otro — la referencia.

DocuGraph automatiza esta metodología: el grafo es el de depends_on de META-01, el validador audita su integridad y get_task_context entrega el contexto mínimo de cada tarea (MASTER-00, ROADMAP-00).

Convención de nombres v0.01

Los identificadores atómicos (US-XX, IX-XX, BE-XX, FE-XX) son estables y no se renombran.
Los nombres de archivo usan el identificador, un guion bajo y un slug descriptivo en minúsculas.
Las palabras del slug se separan con guiones (BE-02_project-create.md); no se usan puntos ni CamelCase.
Los documentos de gobierno conservan su prefijo numérico (00_–04_); los documentos técnicos usan el nombre de su contrato (MCP_SPEC.md, METADATA_SPEC.md).
El catálogo histórico conserva sus IDs y contenido, pero no define el alcance operativo de v0.01.

Roles

Analista de negocio (Fase 1): traduce el problema de negocio en actores, reglas y user stories.
Arquitecto (Fase 2): define stack, servicios, modelo de datos preliminar y alcance.
Interaction Designer (Fase 2.5): define cómo se comporta cada pantalla, qué dispara qué, y qué endpoint origina cada acción del usuario.
Diseñador de producto (Fase 2.6): elabora mockups/wireframes por pantalla, enlazados a la interaction spec de origen.
Implementador (Fase 4): traduce specs de tarea en código, con la IA como ejecutor y el driver como revisor.

Fase 0: Preparación del Entorno de Trabajo

Objetivo: dejar listo lo que cualquier sesión de IA necesita cargar automáticamente, y lo que un desarrollador nuevo necesita para arrancar sin perder tiempo.

Salida:

AGENTS.md (o CLAUDE.md): memoria persistente que se carga en cada sesión.
Stack y comandos exactos de build/test/lint.
Convenciones de código no cubiertas en 02_GLOBAL_SPEC.md.
Reglas de "no hacer" acumuladas por error recurrente — si una regla ya la garantiza un linter o un hook, se elimina de aquí.
Mapa de qué documento vive dónde.
README.md: instalación de dependencias, variables de entorno (.env), comando exacto para levantar el proyecto.

Fase 1: Investigación, Requisitos y User Stories

Objetivo: entender el negocio, definir el problema y los requisitos funcionales, y expresar lo que el usuario necesita en formato verificable. NO SE ESCRIBE CÓDIGO AQUÍ.

Técnica:

"Actúa como un analista de negocios. Te voy a describir un proyecto. Hazme todas las preguntas que necesites para entender los actores, los procesos, las reglas de negocio y los objetivos. No propongas soluciones técnicas aún."

Si el dominio es grande o multi-módulo, delega la exploración de cada subdominio a una sesión o subagente separado y consolida después manualmente.

Salida:

docs/00_BUSINESS_VISION.md — solo para humanos, no se usa en implementación:
Requisitos del problema: enunciado del problema y lista de requisitos funcionales (RF-XX) explícitos, derivados de la investigación. Cada RF es una frase verificable ("el sistema debe…").
Matriz de roles y casos de uso: tabla actor → responsabilidades → casos de uso que protagoniza, sin duplicar el detalle de los flujos (esos viven en Fase 2.5).
Actores y responsabilidades.
Flujos de trabajo (Mermaid o texto).
Reglas de negocio explícitas.
Diccionario de términos (germen del glosario).
docs/user_stories/US-XX_[nombre].md — una por historia, formato:
Como [rol], quiero [acción], para [beneficio].
2-3 escenarios en Dado / Cuando / Entonces.
Criterios de aceptación a nivel de negocio (no técnico — el detalle técnico vive en la spec de tarea de Fase 3).

Cobertura: cada caso de uso de la matriz de roles debe estar cubierto por al menos una user story o un flujo de interacción; si no lo está, es un hueco de alcance que se cierra antes de seguir.

Estado del progreso: checklist manual dentro de 00_BUSINESS_VISION.md.

Fase 2: Arquitectura, Alcance y Modelo de Datos Preliminar

Objetivo: traducir la visión de negocio en una solución técnica de alto nivel y fijar los límites del proyecto.

Entrada: 00_BUSINESS_VISION.md, user_stories/.

Salida:

docs/01_PROJECT_MANIFEST.md — se crea aquí (ver estructura más abajo).
docs/02_GLOBAL_SPEC.md — documento único que fusiona propósito de negocio y especificación técnica en 1-2 páginas:
Propósito (por qué existe el proyecto).
Alcance: qué hace y qué NO hace el proyecto explícitamente.
Objetivos medibles.
Stack elegido y reglas de oro técnicas.
Requisitos no funcionales (NFR-XX): rendimiento, seguridad, disponibilidad y privacidad explícitos. Si un proceso (p. ej. corporativo) exige NFRs, aquí es la fuente única.
Este documento es el juez ante cualquier duda de alcance: si algo no está aquí, no se implementa sin antes actualizarlo.
docs/03_ARCHITECTURE.md — servicios, puertos, infraestructura, MCPs.
docs/domain/01_DATABASE_SCHEMA.md — modelo de datos de alto nivel: entidades, relaciones, atributos clave. Sin DDL final (se completa en Fase 3.1).
docs/domain/02_GLOSSARY.md.

Prompt:

"Basado en 00_BUSINESS_VISION.md y las user stories en user_stories/, propón una arquitectura de alto nivel usando el stack [X], un modelo de entidades y relaciones (sin DDL todavía), y el alcance explícito (qué SÍ y qué NO cubre el proyecto). Genera 02_GLOBAL_SPEC.md, 03_ARCHITECTURE.md, domain/01_DATABASE_SCHEMA.md y domain/02_GLOSSARY.md. Máximo 6 páginas en total."

Estado del progreso: se crea 01_PROJECT_MANIFEST.md con las epics en BACKLOG. A nivel epic las columnas de spec no aplican todavía — se completan cuando las epics se desglosan en tareas (Fase 3.2):

ID	Módulo	Epic	Dependencia	Estado
BE-EPIC-01	Backend	Autenticación y usuarios	Ninguna	BACKLOG
FE-EPIC-01	Frontend	Autenticación	BE-EPIC-01	BACKLOG

Fase 2.5: Diseño de Interacción

Objetivo: definir, para cada user story relevante, cómo se comporta la interfaz de punta a punta — pantallas, transiciones, estados del sistema, y qué acción del usuario dispara qué llamada — antes de que backend y frontend se descompongan en tareas.

Entrada: user_stories/, 02_GLOBAL_SPEC.md.

Rol: Interaction Designer.

Salida: docs/interaction/IX-XX_[nombre].md, uno por flujo, con esta estructura fija:

Metadata — ID, user story de origen, tareas derivadas (se completan en Fase 3), estado.
Objetivo del flujo — qué logra el usuario, en pocas frases.
Actores involucrados.
Precondiciones.
Pantallas involucradas — lista ordenada.
Diagrama de flujo — Mermaid stateDiagram, camino feliz y caminos de error.
Detalle por pantalla — repetido por cada pantalla:
Estados del sistema (inicial, cargando, éxito, error, vacío) y qué ve el usuario en cada uno.
Elementos interactivos: acción del usuario → qué dispara → a qué endpoint referencia (solo el operationId, nunca el contrato completo).
Feedback visual / microinteracciones.
Validaciones en tiempo real.
Casos borde — pérdida de conexión, doble submit, cierre a mitad de flujo, etc.
Accesibilidad — requisitos mínimos si aplican.
Referencias — user story, tareas, endpoints.

Regla: este documento es la fuente de la que derivan tanto la spec de frontend como el contrato de API de ese flujo. Ninguno de los dos redefine estados o transiciones desde cero — los referencian.

Estado del progreso: cada IX-XX se añade a 01_PROJECT_MANIFEST.md vinculado a su user story.

Fase 2.6: Diseño Visual (mockups / wireframes)

Objetivo: materializar cada pantalla definida en la interacción antes de escribir código. Un mockup mal hecho revela pantallas que faltan, estados no contemplados y navegaciones rotas — es la fase donde se ataca el hueco "me faltó una navegación o un dato".

Rol: Diseñador de producto.

Entrada: interaction/IX-XX (cada flujo).

Salida: docs/design/DS-XX_[nombre].md, uno por pantalla o conjunto de pantallas, con:

Metadata — ID (DS-XX), interaction spec de origen (IX-XX), estado.
Wireframe — diagrama Mermaid o imagen (Figma/Excalidraw exportada), nunca texto descriptivo duplicado de la interaction spec.
Elementos del wireframe — lista de componentes, no su comportamiento (el comportamiento ya vive en IX-XX).
Estados visuales — referencias a los estados definidos en la interaction spec (inicial, cargando, error, vacío).
Decisión de diseño — solo lo que la interacción no decide: jerarquía visual, etiquetas, densidad, empty states.
Referencias — IX-XX, US-XX.

Regla de no duplicación: el wireframe no reescribe estados ni transiciones; los referencia por ID. El detalle conductual vive en IX-XX; el visual vive en DS-XX.

Estado del progreso: cada DS-XX se añade a 01_PROJECT_MANIFEST.md vinculado a su IX-XX.

Fase 3: Descomposición en Tareas, Contratos y Estrategia de Pruebas

Objetivo: completar el schema de datos, fijar el contrato de API como fuente única de verdad, definir la estrategia de pruebas y escribir la especificación de cada tarea técnica.

3.1 — Completar el schema de datos

Se detalla domain/01_DATABASE_SCHEMA.md: DDL completo, índices, constraints. No se anotan aún las tareas que usan cada tabla — se definen en 3.2. Este paso se aprueba antes de continuar, porque todas las specs de tarea dependerán de él.

3.2 — Contrato de API y especificación de tareas

Salida:

docs/api/openapi.yaml — contrato único de todos los endpoints del proyecto. Cada operación usa un operationId igual al ID de la tarea backend que la implementa (ej. operationId: BE-02). Este archivo es la única fuente de verdad del contrato — ninguna spec de tarea reescribe el body/response en prosa; solo referencia el operationId.
docs/backend/BE-XX_[nombre].md — una por endpoint, con esta estructura fija:
Referencia: user story (US-XX), interaction spec si aplica (IX-XX), operationId en openapi.yaml.
Pasos de lógica de negocio.
Reglas de validación específicas no cubiertas por el contrato.
Errores esperados y su manejo.
Criterios de aceptación / casos a testear.
docs/frontend/FE-XX_[nombre].md — una por componente/página, con esta estructura fija:
Referencia: user story, interaction spec (IX-XX), design spec (DS-XX), operationId(s) que consume.
Props / inputs del componente.
Comportamiento específico de implementación no cubierto por la interaction spec (librería, breakpoints).
Criterios de aceptación testeables (unitarios o de integración visual).

Prompt (backend, ejemplo):

"Para la epic BE-EPIC-01, genera BE-01_auth-register.md y BE-02_project-create.md en backend/, y su contrato correspondiente en api/openapi.yaml con operationId BE-01 y BE-02. Usa domain/01_DATABASE_SCHEMA.md, domain/02_GLOSSARY.md y la interaction spec IX-01 si existe. Cada archivo .md debe referenciar el operationId, no repetir el contrato, e incluir pasos de lógica, errores y criterios de aceptación."

Para proyectos con muchas epics independientes, genera la especificación de cada una en una sesión/subagente separado, con contexto acotado a esa epic. Consolida revisando inconsistencias de nombres entre epics.

Estado del progreso: 01_PROJECT_MANIFEST.md pasa a nivel de tarea:

ID	Epic	User Story	Interaction Spec	Design Spec	Estado	Spec file	operationId
BE-02	BE-EPIC-01	US-01	IX-01	—	TODO	`backend/BE-02_project-create.md`	BE-02
FE-01	FE-EPIC-01	US-01	IX-01	DS-01	TODO	`frontend/FE-01_login-form.md`	BE-02

Paso final de 3.2: con las tareas ya creadas, se actualiza domain/01_DATABASE_SCHEMA.md añadiendo un comentario por tabla con los IDs de tarea que la usan.

3.3 — Estrategia de pruebas

Salida: docs/testing/TEST-01_verification-plan.md — plan de pruebas por nivel, sin duplicar los criterios de aceptación de cada tarea (se referencian por ID):

Unitarias: por tarea (criterios de aceptación de BE-XX/FE-XX).
Integración: flujos completos (IX-XX) contra el contrato real.
E2E / visual: pantallas (DS-XX → FE-XX) y recorridos críticos.
NFRs: pruebas de rendimiento/seguridad ligadas a los NFR-XX de 02_GLOBAL_SPEC.md.

El documento TEST-01 es la fuente única de la estrategia; cada tarea referenciada no repite aquí su detalle.

Fase 4: Implementación Iterativa

Objetivo: implementar cada tarea usando su spec como contrato, con gate de plan, verificación independiente, y un único commit oficial.

Flujo por tarea:

Preparación: localizas la siguiente tarea TODO sin dependencias bloqueadas en el manifiesto, usando la columna Spec file. Cambias su estado a IN_PROGRESS.
Plan antes de código (tareas no triviales: varios archivos, lógica compleja, integración externa):

"Antes de implementar BE-05, lee backend/BE-05_[nombre].md y propón un plan: qué archivos vas a tocar, qué puede romperse, qué vas a mockear. No escribas código todavía." Apruebas o corriges el plan antes de autorizar la implementación. Tareas triviales saltan este paso.
Implementación (sin commit todavía):

"Implementa la tarea BE-02 usando exclusivamente backend/BE-02_project-create.md, api/openapi.yaml (operationId BE-02) y AGENTS.md. No modifiques nada fuera de esa tarea. Escribe los tests de los criterios de aceptación y corre la suite completa. No hagas commit aún." Commits locales de WIP son opcionales como checkpoint personal; si se usan, se hace squash de todos ellos antes del commit final — el historial compartido muestra un único commit por tarea.
Verificación independiente:

"Revisa el diff de BE-02 contra backend/BE-02_project-create.md y api/openapi.yaml en un contexto nuevo. Reporta solo huecos que afecten corrección o requisitos, no preferencias de estilo." Puede ser una sesión nueva, un subagente, o el driver releyendo el diff contra la spec sin ver el razonamiento que lo produjo.
Commit único y cierre: solo si los tests están en verde y la verificación no reportó huecos críticos, se hace un único commit oficial (código + tests) y se marca DONE. Si la verificación encuentra huecos, se corrigen antes de commitear.

Optimización de tokens:

Usa get_task_context("BE-XX") vía MCP para recibir solo los archivos relevantes de la tarea (spec, operationId específico, no todo openapi.yaml).
Si la conversación se alarga, /clear o compactación.
Nunca cargues 00_BUSINESS_VISION.md en Fase 4 — si falta una regla de negocio, se agrega a la spec de la tarea, no se relee el documento completo.

Estructura Final de Documentos

/
├── README.md
├── AGENTS.md
├── /docs/
│   ├── 00_BUSINESS_VISION.md            # Problema + RF-XX + matriz de roles + flujos + US
│   ├── 01_PROJECT_MANIFEST.md
│   ├── 02_GLOBAL_SPEC.md                # Charter + spec técnica + NFR-XX
│   ├── 03_ARCHITECTURE.md
│   ├── /user_stories/
│   │   └── US-01_login.md
│   ├── /interaction/
│   │   └── IX-01_login-flow.md
│   ├── /design/
│   │   └── DS-01_login_screen.md        # mockups/wireframes enlazados a IX-XX
│   ├── /domain/
│   │   ├── 01_DATABASE_SCHEMA.md
│   │   └── 02_GLOSSARY.md
│   ├── /api/
│   │   └── openapi.yaml                 # Contrato único, fuente de verdad
│   ├── /backend/
│   │   └── BE-02_project-create.md
│   ├── /frontend/
│   │   └── FE-01_login-form.md
│   ├── /testing/
│   │   └── TEST-01_verification-plan.md # Estrategia de pruebas (referencia a tareas)
│   └── /ops/
│       └── env.template.md
└── backend/AGENTS.md                    # Opcional: convenciones locales del módulo

Regla de enlace: todo documento de Fase 3 en adelante referencia a sus documentos de origen por ID (RF-XX, US-XX, IX-XX, DS-XX, operationId, NFR-XX) y nunca repite su contenido. Si necesitas cambiar un comportamiento, se edita en su documento de origen, no en cada lugar que lo menciona.

Trazabilidad

Upstream: MASTER-00, ROADMAP-00.
Relacionados: AGENTS, VISION-00, META-01, GLOBAL-02.