# 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.

Gratis, sin cuenta y sin correo. Úsala, modifícala, compártela.

[Descargar la plantilla (.zip)](https://nodary.ai/downloads/plantilla-documento-de-diseno-tecnico.zip)

## 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.

- Documento de diseño técnico: La página que todos leen primero: el resumen, los objetivos y no objetivos, y un enlace a cada parte.
- Contexto y requisitos: Lo que existe hoy, los requisitos que el diseño debe cumplir y las restricciones que lo rodean.
- Arquitectura: Los componentes, cómo se comunican, el recorrido de una petición y las decisiones clave.
- Datos e interfaces: El modelo de datos, las API y los eventos, y cómo pasan los datos existentes a la nueva forma.
- Operación: Cómo se despliega y se supervisa, cómo se mantiene seguro y qué pasa cuando algo falla.
- Alternativas y riesgos: Las opciones descartadas y por qué, los riesgos, el plan de despliegue y las preguntas abiertas.

### 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](https://nodary.ai/es/templates/technical-design-document#doc-context): lo que existe hoy, los requisitos y las restricciones
- [Arquitectura](https://nodary.ai/es/templates/technical-design-document#doc-architecture): los componentes, el recorrido de una petición y las decisiones clave
- [Datos e interfaces](https://nodary.ai/es/templates/technical-design-document#doc-data): el modelo de datos, las API, los eventos y la migración
- [Operación](https://nodary.ai/es/templates/technical-design-document#doc-operations): despliegue, supervisión, seguridad y modos de fallo
- [Alternativas y riesgos](https://nodary.ai/es/templates/technical-design-document#doc-alternatives): opciones descartadas, riesgos, despliegue y preguntas abiertas

_Puedes usar, modificar y compartir esta plantilla libremente. Viene de_ [Nodary](https://nodary.ai/es)_, donde estos archivos se importan como un mapa de documentos enlazados._

### Contexto y requisitos

**Responsable:** [nombre] · **Estado:** borrador · **Última revisión:** [fecha]

#### 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]
- [...]

Ver también: [Documento de diseño técnico](https://nodary.ai/es/templates/technical-design-document#doc-overview) · [Arquitectura](https://nodary.ai/es/templates/technical-design-document#doc-architecture)

### Arquitectura

**Responsable:** [nombre] · **Estado:** borrador · **Última revisión:** [fecha]

#### Componentes

_Sustituye estas cajas por las tuyas. Indica qué es nuevo, qué cambia y qué se queda igual._

```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
```
_Los componentes principales y las llamadas entre ellos_

| 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._

1. [El usuario hace ...]
2. [La API comprueba ...]
3. [El servicio escribe ...]
4. [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] |

Ver también: [Contexto y requisitos](https://nodary.ai/es/templates/technical-design-document#doc-context) · [Datos e interfaces](https://nodary.ai/es/templates/technical-design-document#doc-data) · [Operación](https://nodary.ai/es/templates/technical-design-document#doc-operations)

### Datos e interfaces

**Responsable:** [nombre] · **Estado:** borrador · **Última revisión:** [fecha]

#### Modelo de datos

| Entidad | Campo | Tipo | Notas |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [opcional, indexado, dato personal] |
| [...] | [...] | [...] | [...] |

_Ejemplo (una funcionalidad de muestra): share__link.expires__at: 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._

1. [Añadir los campos nuevos, vacíos]
2. [Escribir en lo antiguo y en lo nuevo]
3. [Rellenar el histórico]
4. [Leer de lo nuevo]
5. [Quitar lo antiguo]

Ver también: [Arquitectura](https://nodary.ai/es/templates/technical-design-document#doc-architecture) · [Operación](https://nodary.ai/es/templates/technical-design-document#doc-operations)

### Operación

**Responsable:** [nombre] · **Estado:** borrador · **Última revisión:** [fecha]

#### 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._

Ver también: [Arquitectura](https://nodary.ai/es/templates/technical-design-document#doc-architecture) · [Alternativas y riesgos](https://nodary.ai/es/templates/technical-design-document#doc-alternatives)

### Alternativas y riesgos

**Responsable:** [nombre] · **Estado:** borrador · **Última revisión:** [fecha]

#### Alternativas consideradas

| Opción | A favor | En contra | Por qué no |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

#### Riesgos

| Riesgo | Impacto | Qué hacemos | Responsable |
| --- | --- | --- | --- |
| [...] | [bajo, medio, alto] | [...] | [nombre] |

#### Despliegue gradual

1. Detrás de un flag, para [el equipo]
2. [Una parte pequeña] de los [usuarios]
3. Todo el mundo
4. Flag retirado

#### Preguntas abiertas

- [ ] [Pregunta], [quién la responde], [para cuándo]

Ver también: [Documento de diseño técnico](https://nodary.ai/es/templates/technical-design-document#doc-overview) · [Contexto y requisitos](https://nodary.ai/es/templates/technical-design-document#doc-context) · [Operación](https://nodary.ai/es/templates/technical-design-document#doc-operations)

## 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.

1. Abre el mapa de un proyecto y elige «Importar».
2. Elige la pestaña «Carpeta o ZIP» y después «Elegir un ZIP».
3. 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.

## 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.

La página: https://nodary.ai/es/templates/technical-design-document