Plantilla de registro de decisiones con ADR
Un registro de decisiones y sus fichas, en seis documentos enlazados: el registro que lista cada decisión con su estado, cómo decide tu equipo, una ficha en blanco para copiar y tres fichas de ejemplo, una de ellas reemplazada por la siguiente. Descárgalos como archivos Markdown: se abren en cualquier editor, encajan en un repositorio de código 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
El registro es la página que todos abren: una línea por decisión, enlazada a su ficha. Las fichas siguen el formato ADR (architecture decision record) y sirven para cualquier decisión, técnica o no. Los ejemplos siguen un mismo producto de muestra que decide dónde guardar los archivos subidos.
Documentos
Archivo Plantilla de registro de decisiones/Registro de decisiones.md
Registro de decisiones
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ú. Cada decisión tiene su ficha, enlazada desde la tabla de abajo; una ficha nunca se borra, y una decisión que cambia recibe una ficha nueva que la reemplaza.
Decisiones
| Número | Decisión | Estado | Fecha | Decidido por | Reemplazada por |
|---|---|---|---|---|---|
| ADR-001 | Guardar las decisiones en este registro | aceptada | [fecha] | [nombres] | |
| ADR-002 | Guardar los archivos subidos en el servidor de aplicaciones | reemplazada | [fecha] | [nombres] | ADR-003 |
| ADR-003 | Guardar los archivos subidos en almacenamiento de objetos | aceptada | [fecha] | [nombres] | |
| [ADR-004] | [Tu próxima decisión] | [propuesta] | [fecha] | [nombres] |
Estados
- PropuestaAceptadaRechazada
- AceptadaReemplazadaObsoleta
Mermaid
flowchart LR n0["Propuesta"] n1["Aceptada"] n2["Rechazada"] n3["Reemplazada"] n4["Obsoleta"] n0 --> n1 n0 --> n2 n1 --> n3 n1 --> n4
| Estado | Significado |
|---|---|
| Propuesta | Escrita y abierta a revisión, aún sin decidir |
| Aceptada | Decidida: el equipo trabaja según ella |
| Rechazada | Decidida en contra, y guardada para que nadie tenga que volver a preguntar |
| Reemplazada | Sustituida por una decisión posterior, cuyo número indica |
| Obsoleta | Ya no se aplica, y nada la ha sustituido |
Cuándo escribir una ficha
- La decisión es difícil de deshacer: [una base de datos, un proveedor, una API pública, un precio]
- Se consideraron en serio varias opciones
- Alguien preguntará por qué dentro de seis meses
- Cambia el trabajo de otro equipo
El resto del registro
- Cómo decidimos: quién propone, quién decide y cómo se revisa una ficha
- Ficha de decisión en blanco: la ficha en blanco que se copia para cada decisión nueva
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 registro de decisiones/Registro de decisiones/01 Cómo decidimos.md
Cómo decidimos
Las reglas del registro, acordadas una vez. Sin ellas, se escriben fichas para cosas pequeñas y faltan para las grandes.
Quién decide
| Tipo de decisión | Propuesta por | Decidida por | Consultados |
|---|---|---|---|
| [Arquitectura] | [cualquier ingeniero] | [responsable técnico] | [...] |
| [Alcance del producto] | [...] | [responsable de producto] | [...] |
| [Proveedor o gasto] | [...] | [...] | [...] |
De la propuesta a la decisión
- Copia la ficha en blanco, dale el número siguiente y el estado propuesta.
- Escribe el contexto y al menos dos opciones antes de la decisión.
- Pide a quienes deciden que la revisen antes del [fecha].
- Pasa el estado a aceptada o rechazada, con la fecha y quién decidió.
- Añade una línea al registro de decisiones.
Cambiar una decisión
Nunca edites una ficha aceptada para que diga otra cosa. Escribe una ficha nueva que la reemplace, pasa la antigua a reemplazada con el número de la nueva y enlaza las dos en ambos sentidos.
Revisiones
- Las decisiones aceptadas se revisan: [cada trimestre, en cada hito]
- Las propuestas con más de [dos semanas] se deciden o se retiran
Archivo Plantilla de registro de decisiones/Registro de decisiones/02 Ficha de decisión en blanco.md
Ficha de decisión en blanco
Copia esta página para cada decisión nueva y dale el número siguiente, por ejemplo ADR-004 seguido de la decisión en pocas palabras.
| Campo | Valor |
|---|---|
| Número | [ADR-000] |
| Estado | [propuesta, aceptada, rechazada, reemplazada por ADR-..., obsoleta] |
| Fecha | [fecha] |
| Decidido por | [nombres] |
| Reemplaza a | [ninguna, o ADR-...] |
Contexto
Las fuerzas en juego: qué es cierto hoy, qué duele, qué limita la elección. Hechos, no la decisión.
[Contexto]
Opciones consideradas
| Opción | A favor | En contra |
|---|---|---|
| [Opción A] | [...] | [...] |
| [Opción B] | [...] | [...] |
Decisión
Lo que vais a hacer, en frases completas, empezando por “Vamos a”.
Vamos a [...].
Consecuencias
- Más fácil: [...]
- Más difícil: [...]
- A vigilar: [...]
Archivo Plantilla de registro de decisiones/Registro de decisiones/03 ADR-001 Guardar las decisiones en este registro.md
ADR-001 Guardar las decisiones en este registro
| Campo | Valor |
|---|---|
| Número | ADR-001 |
| Estado | aceptada |
| Fecha | [fecha] |
| Decidido por | [nombres] |
| Reemplaza a | ninguna |
Contexto
Las decisiones se toman en reuniones, chats y llamadas. Unos meses después nadie recuerda por qué el equipo eligió lo que eligió, y quienes llegan repiten viejos debates o deshacen decisiones sin saber lo que costaron.
Opciones consideradas
| Opción | A favor | En contra |
|---|---|---|
| No escribir nada | Rápido | Las razones se pierden |
| Actas de cada reunión | Todo queda guardado | Nadie las lee, y las decisiones se pierden entre el resto |
| Una ficha corta por decisión importante, listada en un registro | Fácil de encontrar y de leer | Unos quince minutos por decisión |
Decisión
Vamos a escribir una ficha por cada decisión importante, numerada en orden, y listarla en el registro de decisiones. Una ficha nunca se borra ni se reescribe: una ficha nueva la reemplaza.
Consecuencias
- Más fácil: saber el porqué y poner al día a quien llega
- Más difícil: decidir rápido sin escribir nada
- A vigilar: fichas escritas a posteriori, o nunca escritas
Archivo Plantilla de registro de decisiones/Registro de decisiones/04 ADR-002 Guardar los archivos subidos en el servidor de aplicaciones.md
ADR-002 Guardar los archivos subidos en el servidor de aplicaciones
| Campo | Valor |
|---|---|
| Número | ADR-002 |
| Estado | reemplazada por ADR-003 |
| Fecha | [fecha] |
| Decidido por | [nombres] |
| Reemplaza a | ninguna |
Un ejemplo de ficha reemplazada. Cuando ADR-003 la reemplazó no cambió nada en ella, salvo su estado.
Contexto
Los usuarios adjuntan archivos a sus documentos. El producto funciona en un solo servidor de aplicaciones con un disco grande, y el equipo tiene dos ingenieros.
Opciones consideradas
| Opción | A favor | En contra |
|---|---|---|
| El disco del servidor de aplicaciones | Sencillo, nada nuevo que mantener | Difícil de respaldar y de compartir con un segundo servidor |
| Almacenamiento de objetos | Crece sin límite, barato | Un servicio más que aprender y pagar |
Decisión
Vamos a guardar los archivos subidos en el disco del servidor de aplicaciones y a hacer una copia de seguridad del disco cada noche.
Consecuencias
- Más fácil: lanzar la subida de archivos este mes
- Más difícil: añadir un segundo servidor más adelante
- A vigilar: el espacio libre del disco y el tiempo de una restauración
Archivo Plantilla de registro de decisiones/Registro de decisiones/05 ADR-003 Guardar los archivos subidos en almacenamiento de objetos.md
ADR-003 Guardar los archivos subidos en almacenamiento de objetos
| Campo | Valor |
|---|---|
| Número | ADR-003 |
| Estado | aceptada |
| Fecha | [fecha] |
| Decidido por | [nombres] |
| Reemplaza a | ADR-002 |
Contexto
El tráfico ya necesita un segundo servidor de aplicaciones, y un archivo escrito en el disco de un servidor falta en el otro. Restaurar la copia nocturna llevó cuatro horas en el último simulacro. ADR-002 suponía un solo servidor; eso ya no es cierto.
Opciones consideradas
| Opción | A favor | En contra |
|---|---|---|
| Un disco compartido entre los servidores | Ningún cambio en el código | Otra cosa que mantener, y un único punto de fallo |
| Almacenamiento de objetos | Cada servidor ve cada archivo, versiones guardadas, restauración en minutos | Cambios de código para subir y descargar |
Decisión
Vamos a guardar los archivos subidos en almacenamiento de objetos con versionado activado, y a servirlos con enlaces firmados que caducan. Esta ficha reemplaza a ADR-002.
Consecuencias
- Más fácil: añadir servidores y restaurar un archivo borrado
- Más difícil: ejecutar el producto en un portátil sin el servicio de almacenamiento
- A vigilar: la factura de almacenamiento y los enlaces compartidos antes de caducar
Cómo usarla
Acordad quién decide
Rellena primero la página del proceso: qué decisiones necesitan ficha, quién propone, quién decide y a quién se consulta.
Copia la ficha para cada decisión
Dale el número siguiente y el estado propuesta. Escribe el contexto y al menos dos opciones antes de que nadie escriba la decisión.
Decide y luego regístrala
Pasa el estado a aceptada o rechazada, con la fecha y quién decidió, y añade una línea al registro. Una decisión rechazada se queda: ahorra el próximo debate.
Reemplaza, nunca reescribas
Cuando una decisión cambie, escribe una ficha nueva que reemplace a la antigua y marca la antigua como reemplazada con el número nuevo. La historia sigue siendo legible.
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 registro llega con sus fichas debajo y los enlaces entre ellas conservados. Marca cada ficha como Canon, Exploración, Obsoleto o Reemplazado por la ficha que la sustituyó: el estado se ve en el documento, y los agentes de IA conectados por MCP reciben el aviso antes de leer una ficha reemplazada. Cuando dos documentos se contradicen, Nodary muestra los dos pasajes uno al lado del otro.
- 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 fichas más. Nodary también trae integrada una plantilla de Architecture Decision Record de una página.
Cómo se conectan los agentes de IA a Nodary por MCP
Llevar un registro de decisiones fiable
Un registro de decisiones falla cuando nadie escribe en él, o cuando lo que dice ya no coincide con lo que hace el equipo. Estos hábitos evitan las dos cosas.
Una decisión por ficha
Una ficha que resuelve tres cosas se reabre tres veces. Limita cada una a una sola decisión con un solo estado.
El contexto antes que la decisión
Escribe lo que es cierto hoy y lo que limita la elección antes de la decisión misma. Seis meses después, el contexto es lo que la explica.
Siempre dos opciones
Una ficha con una sola opción es un anuncio. Nombra las alternativas que consideraste en serio y por qué no las elegiste.
Reemplaza, nunca reescribas
Una ficha aceptada nunca se edita para decir otra cosa. Una ficha nueva la reemplaza y las dos se quedan, así el registro cuenta la historia real.
Di quién decidió
Cada ficha nombra a quién decidió y su fecha. Una decisión sin nombre no tiene a quién preguntar, ni a nadie que la cambie.
Enlaza lo que cambia
Enlaza cada ficha con los documentos que cambia, y esos documentos con ella. Quien lea el diseño encontrará la razón en un clic.
Preguntas sobre el registro de decisiones
¿Qué es un registro de decisiones?
Un registro de decisiones es una lista al día de las decisiones importantes de un equipo: qué se decidió, cuándo, quién, su estado y un enlace a la ficha que la explica. Permite a cualquiera, incluido un compañero nuevo o un agente de IA, saber por qué las cosas son como son sin ir preguntando.
¿Qué es un ADR?
Un ADR (architecture decision record, registro de decisión de arquitectura) es un documento corto para una decisión importante: su contexto, las opciones consideradas, la decisión y sus consecuencias, con un número y un estado. El formato viene de la arquitectura de software y sirve para cualquier decisión que un equipo quiera conservar.
¿Qué significa “reemplazada”?
Una decisión reemplazada ha sido sustituida por otra posterior. Se queda en el registro, sin cambios, con el número de la ficha que la reemplazó, y la ficha nueva dice a cuál reemplaza. No se borra nada, así la historia sigue siendo cierta.
¿Cuándo debe un equipo escribir una ficha de decisión?
Cuando la decisión es difícil de deshacer, cuando se consideraron en serio varias opciones, cuando cambia el trabajo de otro equipo o cuando alguien preguntará por qué dentro de seis meses. Las elecciones pequeñas y reversibles no la necesitan.
¿Las fichas deben vivir con el código o con los documentos?
Los equipos que solo comparten sus decisiones entre desarrolladores suelen guardarlas en el repositorio de código. Cuando producto, diseño, soporte o clientes también tienen que leerlas, un espacio de trabajo compartido las hace más fáciles de encontrar. Los archivos de esta plantilla funcionan en los dos sitios.
¿Puedo usarla fuera de Nodary?
Sí. Los archivos son Markdown con enlaces relativos: pon la carpeta en un repositorio, ábrela como bóveda en Obsidian o léela en GitHub, diagrama incluido.
Mantén cada decisión donde trabaja el equipo.
Importa la plantilla en Nodary y el registro se convierte en un mapa que dice qué decisiones siguen en pie, para tu equipo y tus agentes de IA. Gratis con dos miembros, un proyecto y diez documentos, sin tarjeta.