ADR para decisiones de arquitectura: 3 plantillas con ejemplo

Un ADR (Architecture Decision Record) es un archivo Markdown corto que registra una decisión técnica, su contexto y sus consecuencias. Para empezar te basta con una plantilla de cinco campos: título, estado, contexto, decisión y consecuencias. Guárdalos numerados en docs/adr dentro del repositorio y escribe uno cada vez que una elección sea cara de revertir.

Qué resuelve un ADR en un proyecto pequeño

Un ADR responde a una sola pregunta: ¿por qué está hecho así? El código ya cuenta el qué y el cómo. El porqué se pierde en una conversación, en un ticket cerrado o en tu cabeza de hace ocho meses.

Imagina un SaaS pequeño que procesa tareas en segundo plano con una tabla de PostgreSQL en vez de Redis o una cola dedicada. Dentro de un año alguien, quizá tú, verá esa tabla jobs y pensará que es un apaño. Sin registro, la tentación es migrarla «porque sí». Con un ADR de quince líneas descubres que la decisión fue deliberada: menos piezas que mantener y el volumen esperado no justificaba otra infraestructura. También descubres qué condición haría cambiar la decisión.

Documentar decisiones no es lo mismo que tomarlas bien. Para lo segundo te sirve un criterio como el de decisiones de arquitectura sin arrepentimiento. El ADR es solo la huella escrita de ese proceso.

Plantilla ADR mínima: cinco campos en Markdown

La plantilla mínima cabe en una pantalla y es la que más se usa. Si eres un equipo de uno o de tres personas, empieza aquí:

# 0007. Usar PostgreSQL como cola de tareas

- Estado: Aceptada
- Fecha: AAAA-MM-DD

## Contexto
Necesitamos ejecutar envíos de email y generación de PDF fuera de la petición HTTP. Ya tenemos PostgreSQL en producción.

## Decisión
Usaremos una tabla jobs con SELECT ... FOR UPDATE SKIP LOCKED y un worker propio.

## Consecuencias
- Una pieza menos de infraestructura.
- Si superamos el volumen que aguanta la base de datos, habrá que migrar a una cola dedicada.

Fíjate en dos detalles. El estado permite que una decisión envejezca sin borrarla. Las consecuencias incluyen lo malo, no solo lo bueno. Un ADR que solo enumera ventajas es marketing interno, no documentación.

Plantilla ADR de Nygard: el formato clásico

El formato propuesto por Michael Nygard es el origen de casi todas las variantes y añade poco a la mínima: título, estado, contexto, decisión y consecuencias. La diferencia es de tono. Nygard insiste en escribir el contexto como hechos neutrales, incluidas las fuerzas en tensión: presupuesto, plazos, conocimiento del equipo y restricciones legales.

La regla práctica que sale de ese formato es escribir la decisión en voz activa y en futuro: «Usaremos…», «No soportaremos…». Nada de «se valoró la posibilidad de». Si no puedes escribir la decisión en una frase, probablemente todavía no la has tomado.

Plantilla ADR estilo MADR ligera: cuando comparas opciones

MADR (Markdown Any Decision Records) añade una sección de opciones consideradas con pros y contras. Es útil cuando la decisión fue reñida y quieres que nadie reabra el debate sin argumentos nuevos:

# 0012. Almacenamiento de archivos subidos por usuarios

- Estado: Aceptada
- Decisores: equipo backend

## Contexto y problema
Los usuarios suben imágenes y audio. El disco del VPS no escala y complica tener dos réplicas.

## Opciones consideradas
1. Disco local con volumen compartido
2. Almacenamiento de objetos compatible con S3
3. Guardar binarios en la base de datos

## Decisión
Opción 2, porque desacopla los archivos del servidor y permite varias réplicas sin sincronizar disco.

### Pros y contras
- Opción 1: simple, pero rompe el failover entre servidores.
- Opción 2: coste por uso y una dependencia externa más.
- Opción 3: backups enormes y consultas más lentas.

## Cuándo revisar
Si el coste de salida de datos supera lo previsto o cambian los requisitos de residencia de datos.

La sección Cuándo revisar no es estándar en todas las variantes, pero te la recomiendo. Convierte el ADR en una decisión con fecha de caducidad condicional, no en una ley eterna.

Comparativa de plantillas ADR según el tamaño del proyecto

Mi recomendación general: usa la mínima por defecto y sube a MADR solo cuando hubo al menos dos opciones serias sobre la mesa.

Dónde guardar los ADR en el repositorio y cómo numerarlos

Los ADR viven en el mismo repositorio que el código, en docs/adr/, con nombres como 0007-postgres-como-cola.md. Así viajan con cada rama, se revisan en el mismo pull request que el cambio y aparecen en cualquier búsqueda con grep.

No necesitas herramientas especiales. Un script de pocas líneas genera el siguiente número y copia la plantilla:

#!/usr/bin/env bash
# uso: ./new-adr.sh postgres-como-cola
set -e
dir=docs/adr
mkdir -p "$dir"
last=$(ls "$dir" | grep -E '^[0-9]{4}-' | sort | tail -n1 | cut -c1-4)
next=$(printf '%04d' $((10#${last:-0} + 1)))
file="$dir/$next-$1.md"
sed "s/NUMERO/$next/" "$dir/template.md" > "$file"
echo "Creado $file"

Tres reglas de mantenimiento:

• Nunca reescribas un ADR aceptado. Si cambias de opinión, crea uno nuevo y marca el antiguo como «Reemplazada por 0019».
• Añade un índice en docs/adr/README.md con número, título y estado. Diez segundos por entrada.
• Exige el ADR en la revisión cuando el pull request introduce una dependencia nueva, un servicio externo o un cambio de esquema importante. Si ya tienes CI con GitHub Actions, puedes añadir un paso que avise si cambia el package.json y no hay ningún archivo nuevo en docs/adr.

5 errores que convierten un registro ADR en un cementerio

1. Documentar todo. Elegir una librería de fechas no merece un ADR. Elegir base de datos, autenticación o proveedor de pagos, sí. La pregunta filtro es: ¿cuesta más de un día revertirlo?
2. Escribirlo semanas después. El contexto se evapora rápido. Escríbelo en el mismo pull request o, como tarde, el mismo día de la decisión.
3. Ocultar las consecuencias negativas. La parte más valiosa de un ADR es la que dice qué sacrificaste. Es justo lo que tu yo futuro necesita para no repetir el análisis.
4. Guardarlos fuera del repo. Una wiki aparte se desincroniza del código en cuanto alguien hace un refactor y nadie la abre.
5. No cerrar el ciclo. Una decisión «Propuesta» que lleva meses en ese estado no ayuda a nadie. Acéptala, recházala o bórrala.

Los ADR encajan bien con la idea de documentar para tu yo futuro: poca fricción, formato fijo y cerca del código. Y también con asumir la deuda técnica como estrategia. Un atajo consciente y documentado es una decisión; uno sin registro es solo un problema esperando su turno.

Empieza hoy con un único archivo: la última decisión importante que tomaste y que nadie más entiende. Quince minutos. El resto del registro crecerá solo si cada nueva decisión gorda trae su ADR en el mismo pull request.