Plantilla de documento de diseño técnico
Seis documentos enlazados que llevan un sistema de los requisitos al despliegue: el contexto, la arquitectura, los datos y las interfaces, cómo funciona y cómo falla, y las opciones descartadas. Descárgalos como archivos Markdown: se abren en cualquier editor, viven junto al código en un repositorio, dibujan sus diagramas en GitHub y en Obsidian, y se importan en Nodary como un mapa.
6 archivos Markdown en un .zip, 7 kB
Gratis, sin cuenta y sin correo. Úsala, modifícala, compártela.
Lee cada página antes de descargarla
La visión general cabe en una pantalla y enlaza cinco partes: quien revisa lee el resumen y va directo a la parte que le toca. Las líneas en cursiva dicen qué escribir; los ejemplos siguen una misma funcionalidad de ejemplo, enlaces para compartir que caducan.
Documentos
Archivo Plantilla de documento de diseño técnico/Documento de diseño técnico.md
Documento de diseño técnico
Cómo usar esta plantilla: las líneas en cursiva son indicaciones. Sustitúyelas por tus palabras y luego bórralas. Los valores entre corchetes los rellenas tú. Mantén esta página en una pantalla: quien revisa debe saber por ella qué aprueba.
De un vistazo
| Campo | Este diseño |
|---|---|
| Sistema o funcionalidad | [Nombre] |
| Autor | [nombre] |
| Revisores | [nombres] |
| Estado | [borrador, en revisión, aprobado, construido] |
| Requisitos | [enlace al PRD] |
| Versión prevista | [fecha o versión] |
Resumen
Tres frases: qué vas a construir, por qué, y la decisión que hay que mirar primero.
Ejemplo (una funcionalidad de muestra): Los enlaces para compartir reciben una fecha de fin opcional. Cada petición comprueba la fecha, así que un enlace deja de funcionar en el momento en que termina. Una tarea programada revoca cada minuto los enlaces caducados; solo limpia, y un retraso no cambia nada para quien abre el enlace.
[Tu resumen]
Objetivos y no objetivos
- Objetivo: [...]
- Objetivo: [...]
- No objetivo: [...]
- No objetivo: [...]
El resto del diseño
Cada parte es un documento propio. Enlázala en vez de copiarla, para que cada dato viva en un solo sitio.
- Contexto y requisitos: lo que existe hoy, los requisitos y las restricciones
- Arquitectura: los componentes, el recorrido de una petición y las decisiones clave
- Datos e interfaces: el modelo de datos, las API, los eventos y la migración
- Operación: despliegue, supervisión, seguridad y modos de fallo
- Alternativas y riesgos: opciones descartadas, riesgos, despliegue y preguntas abiertas
Puedes usar, modificar y compartir esta plantilla libremente. Viene de Nodary, donde estos archivos se importan como un mapa de documentos enlazados.
Archivo Plantilla de documento de diseño técnico/Documento de diseño técnico/01 Contexto y requisitos.md
Contexto y requisitos
Estado actual
Lo que existe hoy y lo que falla, en pocas frases. Enlaza el código, los paneles y los diseños anteriores.
[Estado actual]
Requisitos
Los requisitos que dan forma al diseño, cada uno enlazado a su origen. Deja fuera los que el diseño no toca.
| ID | Requisito | Origen |
|---|---|---|
| [R1] | [...] | [PRD, incidente, normativa] |
| [R2] | [...] | [...] |
Ejemplo (una funcionalidad de muestra): R1: un enlace deja de abrirse en el minuto siguiente a su fecha de fin. Origen: los criterios de aceptación del PRD.
Restricciones
- Rendimiento: [...]
- Seguridad y privacidad: [...]
- Compatibilidad: [...]
- Equipo y plazos: [...]
Supuestos
- [Supuesto], comprobado por [nombre]
- [...]
Archivo Plantilla de documento de diseño técnico/Documento de diseño técnico/02 Arquitectura.md
Arquitectura
Componentes
Sustituye estas cajas por las tuyas. Indica qué es nuevo, qué cambia y qué se queda igual.
- ClienteAPI
- APIServicio
- ServicioBase de datosCola de tareasAlmacén de archivos
- Cola de tareasBase de datos
Mermaid
flowchart TD n0["Cliente"] n1["API"] n2["Servicio"] n3["Base de datos"] n4["Cola de tareas"] n5["Almacén de archivos"] n0 --> n1 n1 --> n2 n2 --> n3 n2 --> n4 n4 --> n3 n2 --> n5
| Componente | Responsabilidad | Equipo | Nuevo o modificado |
|---|---|---|---|
| [API] | [...] | [equipo] | [nuevo, modificado, sin cambios] |
| [...] | [...] | [...] | [...] |
Recorrido de una petición
Sigue una petición desde la acción del usuario hasta la respuesta. Numera los pasos: quien revisa los comenta por número.
- [El usuario hace ...]
- [La API comprueba ...]
- [El servicio escribe ...]
- [La respuesta dice ...]
Decisiones clave
Las elecciones con las que quien revisa debe estar de acuerdo. Da a cada una importante una ficha en el registro de decisiones del equipo y enlázala aquí.
| Decisión | Por qué | Ficha |
|---|---|---|
| [...] | [...] | [enlace] |
Archivo Plantilla de documento de diseño técnico/Documento de diseño técnico/03 Datos e interfaces.md
Datos e interfaces
Modelo de datos
| Entidad | Campo | Tipo | Notas |
|---|---|---|---|
| [...] | [...] | [...] | [opcional, indexado, dato personal] |
| [...] | [...] | [...] | [...] |
Ejemplo (una funcionalidad de muestra): sharelink.expiresat: una marca de tiempo con zona horaria, vacía cuando el enlace no tiene fin, indexada para la tarea que revoca los enlaces caducados.
API
| Método | Ruta | Propósito | Quién puede llamarla |
|---|---|---|---|
| [POST] | [/...] | [...] | [...] |
| [...] | [...] | [...] | [...] |
Eventos
| Evento | Se emite cuando | Lo leen |
|---|---|---|
| [...] | [...] | [...] |
Migración
Cómo pasan los datos existentes a la nueva forma sin cortes, y cómo lo desharías.
- [Añadir los campos nuevos, vacíos]
- [Escribir en lo antiguo y en lo nuevo]
- [Rellenar el histórico]
- [Leer de lo nuevo]
- [Quitar lo antiguo]
Archivo Plantilla de documento de diseño técnico/Documento de diseño técnico/04 Operación.md
Operación
Despliegue
- Dónde se ejecuta: [...]
- Cómo se publica: [pipeline, flags]
- Configuración y secretos: [...]
Supervisión y alertas
| Señal | Normal | Alerta cuando | La alerta va a |
|---|---|---|---|
| [tasa de errores] | [...] | [...] | [equipo] |
| [...] | [...] | [...] | [...] |
Seguridad y privacidad
- Cada petición comprueba quién pide y qué puede hacer
- Datos personales listados, con dónde se guardan y cuánto tiempo
- Secretos fuera del código y de los registros
- Entradas comprobadas donde entran en el sistema
- Abuso y límites de frecuencia considerados
Modos de fallo
| Fallo | Qué ven los usuarios | Cómo lo notamos | Cómo nos recuperamos |
|---|---|---|---|
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |
Ejemplo (una funcionalidad de muestra): La tarea de revocación se detiene: los enlaces caducados se siguen rechazando, porque cada petición comprueba la fecha; solo la limpieza se retrasa. Salta una alerta cuando la tarea lleva cinco minutos sin ejecutarse.
Archivo Plantilla de documento de diseño técnico/Documento de diseño técnico/05 Alternativas y riesgos.md
Alternativas y riesgos
Alternativas consideradas
| Opción | A favor | En contra | Por qué no |
|---|---|---|---|
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |
Riesgos
| Riesgo | Impacto | Qué hacemos | Responsable |
|---|---|---|---|
| [...] | [bajo, medio, alto] | [...] | [nombre] |
Despliegue gradual
- Detrás de un flag, para [el equipo]
- [Una parte pequeña] de los [usuarios]
- Todo el mundo
- Flag retirado
Preguntas abiertas
- [Pregunta], [quién la responde], [para cuándo]
Cómo usarla
Parte de los requisitos
Enlaza los requisitos de producto en la página de contexto y lista los que dan forma al diseño. Un diseño que no responde a ningún requisito es una refactorización disfrazada.
Dibuja y después escribe
Dibuja los componentes y las llamadas entre ellos antes de la prosa. Quien revisa ve una caja que falta más rápido que un párrafo que falta.
Escribe lo que descartaste
Rellena las alternativas con las opciones que consideraste en serio. La revisión no las reabrirá una a una.
Actualízalo tras construirlo
Cuando el código esté publicado, marca lo que cambió respecto al plan. Quien venga después lee el diseño para saber cómo funciona el sistema, no cómo se imaginó.
Impórtala en Nodary como un mapa
Nodary es un espacio de trabajo nativo de IA donde los documentos de un equipo se enlazan en vez de amontonarse. Importa el .zip y el diseño llega con sus cinco partes debajo, los enlaces conservados y el diagrama dibujado como un diagrama Mermaid editable. Quien revisa comenta un pasaje o un elemento del diagrama, la autora pide una aprobación, y agentes de programación como Cursor, Claude Code o VS Code, conectados por MCP, leen el diseño antes de escribir el código.
- Abre el mapa de un proyecto y elige «Importar».
- Elige la pestaña «Carpeta o ZIP» y después «Elegir un ZIP».
- Selecciona el archivo descargado, revisa el árbol e importa.
El plan Free admite diez documentos por espacio de trabajo, contando la página del propio proyecto: los seis de la plantilla dejan sitio para tres más. Nodary también trae integrada una plantilla de diseño técnico de una página.
Conectar Cursor, Claude Code o VS Code a Nodary
Escribir un diseño que se pueda aprobar
Un documento de diseño técnico falla cuando quien revisa no sabe qué aprueba, o cuando el sistema descrito no es el que se publicó. Estos hábitos evitan las dos cosas.
Empieza por la decisión
Di en el resumen qué vas a construir y la elección que debe mirarse primero. Nadie debería encontrarla en la página tres.
Dibuja antes de escribir
Un diagrama de seis cajas y sus llamadas vale más que seis páginas de prosa, y muestra enseguida la pieza que falta.
Di lo que no harás
Los no objetivos mantienen la revisión en el diseño presentado y no en el que alguien habría preferido leer.
Muestra las opciones descartadas
Para cada elección importante, di qué más consideraste y por qué no. Así se discuten tus razones, no tu conclusión.
Planifica el fallo
Di qué pasa cuando falla cada parte, cómo lo notarás y cómo te recuperas. La operación forma parte del diseño, no es un anexo.
Mantenlo cierto tras construirlo
Marca lo que cambió durante la construcción y enlaza las decisiones que lo explican. Un diseño fiel al código es documentación; uno que no lo es, una trampa.
Preguntas sobre el documento de diseño técnico
¿Qué es un documento de diseño técnico?
Un documento de diseño técnico (technical design document, TDD) describe cómo se construirá un sistema o una funcionalidad antes de escribir el código: su contexto y requisitos, su arquitectura, sus datos e interfaces, cómo se despliega y se supervisa, los riesgos y las alternativas consideradas. Lo escriben los ingenieros para que otros revisen el enfoque mientras aún es barato cambiarlo.
¿Qué debe incluir un documento de diseño técnico?
Un resumen con objetivos y no objetivos, el estado actual y los requisitos, los componentes y cómo se comunican, el modelo de datos y las API, el despliegue, la supervisión, la seguridad y los modos de fallo, las alternativas consideradas, los riesgos, el plan de despliegue y las preguntas abiertas. Esta plantilla tiene un documento para cada grupo.
¿Qué diferencia hay con un PRD?
El documento de requisitos de producto dice qué debe hacer la funcionalidad y por qué. El documento de diseño técnico dice cómo lo hará el sistema. Escribe primero el PRD y enlázalo desde el diseño para poder seguir cada requisito.
¿Cuándo necesita un cambio un documento de diseño?
Cuando afecta a varios componentes o equipos, cambia datos que ya existen, es difícil de deshacer o tiene un riesgo que merece otra mirada. Un cambio pequeño dentro de un componente suele necesitar una buena pull request, no un documento de diseño.
¿Quién debe revisar un documento de diseño técnico?
Los ingenieros que lo construirán y lo operarán, un ingeniero de cada sistema afectado y una persona responsable de seguridad cuando trate datos personales o accesos. Pide la revisión pronto, antes de que exista la mayor parte del código.
¿Los equipos de videojuegos también escriben documentos de diseño técnico?
Sí. La plantilla de documento de diseño de juego tiene una parte de diseño técnico para el motor, los objetivos y el pipeline; un sistema grande, como la red, las partidas guardadas o las herramientas, merece su propio documento de diseño técnico, enlazado desde el GDD.
Mantén el diseño junto a quienes lo construyen, personas y agentes.
Importa la plantilla en Nodary y el diseño se convierte en un mapa que tu equipo y tus agentes de programación leen antes de cambiar el sistema. Gratis con dos miembros, un proyecto y diez documentos, sin tarjeta.