Antes de escribir una línea de código, alguien tiene que responder una pregunta simple: ¿qué es exactamente lo que estamos construyendo? Un Domain Model Document es donde esa respuesta queda escrita. No en la cabeza de un dev, no en un chat de Slack que nadie vuelve a leer. En un documento que cualquiera del equipo puede abrir y entender.
¿Qué es un Domain Model Document?
Un DMD describe cómo está estructurado el negocio antes de que exista una sola línea de código. No es lo mismo que un PRD. Un PRD dice qué quiere el negocio: “el usuario debe poder verificar su identidad”. Un DMD dice cómo está organizado ese dominio para que alguien (un dev, o una IA) lo pueda construir sin adivinar: qué estados existen, qué los dispara, qué reglas no se pueden romper.
Es la diferencia entre pedir una casa y entregar los planos.
Qué contiene un DMD, con un ejemplo real
Tomemos el mismo caso que usamos en nuestra página principal: un flujo de verificación de identidad (KYC) para una fintech. Esto es parte real de un DMD para ese sistema.
Glosario del dominio
Cada término tiene un significado exacto, acordado por escrito. “Usuario verificado” no significa lo mismo para el equipo de producto que para el de compliance, y esa diferencia es exactamente el tipo de ambigüedad que después se paga como bug en producción.
Entidades y sus estados
Un usuario en este sistema no está “activo” o “inactivo”. Tiene un estado KYC específico: pendiente, en_revisión, aprobado, rechazado. Cada estado tiene reglas sobre a qué otro estado puede pasar, y bajo qué condición.
Event map
Qué evento dispara qué cambio. Por ejemplo:
DADO QUE usuario con estado KYC 'pendiente' ha subido cédula con ambas caras
CUANDO el verificador externo devuelve score: 87 y los datos coinciden
ENTONCES el perfil cambia a 'aprobado' automáticamente y queda habilitadoBounded contexts
Qué partes del sistema no se mezclan entre sí. El módulo de verificación de identidad no necesita saber cómo funciona el módulo de pagos, y viceversa. Definir esa frontera por escrito evita que, seis meses después, alguien acople dos cosas que nunca debieron tocarse.
Qué pasa cuando no existe un DMD
Sin este documento, la IA genera código sin saber qué significa “aprobado” para tu negocio específico. Dos desarrolladores interpretan “usuario activo” de forma distinta, cada uno programa su propia versión, y el sistema termina con tres definiciones de la misma palabra conviviendo en el mismo repositorio. Cuando un inversionista pide ver la arquitectura, nadie en el equipo puede explicarla de forma completa porque nunca estuvo escrita en un solo lugar. Solo vivía en la memoria de la persona que la construyó, y esa persona puede irse.
Cómo se usa un DMD en Spec Driven Development
En nuestra metodología, el DMD es el primer entregable de la Fase 1 (Discovery & Domain Modeling). Antes de tocar el teclado, documentamos el dominio completo y lo revisamos contigo. Solo cuando ese mapa está aprobado, avanzamos a diseñar la arquitectura. La IA construye después, siguiendo ese mapa. No lo inventa sobre la marcha.
Cómo escribir tu primer DMD
No necesitas contratar a nadie para empezar uno. Cuatro pasos que puedes hacer con tu propio equipo esta semana:
- Lista los términos que tu equipo usa distinto entre sí. Pregunta a dos personas qué significa “cliente activo” en tu sistema. Si responden distinto, ya tienes el primer punto del glosario.
- Define los estados posibles de cada entidad clave. No “activo/inactivo”. Los estados reales, con nombre, que existen en tu negocio.
- Dibuja qué evento dispara qué cambio de estado. Un diagrama simple basta para empezar. Lo importante es que quede escrito, no que se vea bonito.
- Haz que alguien fuera del equipo técnico lo lea. Si no lo entiende, todavía no está lo suficientemente claro.
Plantilla de Domain Model Document
Este es el esqueleto que usamos como punto de partida. Cópialo y llénalo con tu propio dominio:
# Domain Model Document — [Nombre del proyecto]
## Glosario
- Término: definición exacta, acordada por el equipo
## Entidades
- Nombre de la entidad
- Estados posibles
- Transiciones válidas entre estados
## Event Map
- DADO QUE [condición inicial]
CUANDO [evento]
ENTONCES [resultado]
## Bounded Contexts
- Qué módulos existen y qué no comparten entre síSi ya armaste el tuyo y quieres que alguien con criterio externo lo revise antes de empezar a construir, escríbenos a hola@glsolutions.tech.
Relacionado: Vibe Coding vs Spec Driven Development · Nuestra metodología completa