Registros de decisiones arquitectónicas (ADR)

Seis meses después de lanzar un sistema, alguien pregunta: «¿por qué usamos una cola de mensajes aquí, si una llamada HTTP sería más simple?». Si nadie recuerda la respuesta, el equipo tiene dos malas opciones: no tocar nada por miedo, o cambiarlo y repetir un error que ya se había evitado.

Un registro de decisión arquitectónica (ADR, Architecture Decision Record) es un documento breve que captura una decisión significativa, su contexto y sus consecuencias. Juntos, los ADR forman la memoria del proyecto.

Qué decisiones merecen un ADR

No todas. Una buena regla: escribe un ADR cuando la decisión sea costosa de revertir o cuando sea probable que alguien la cuestione en el futuro.

Elegir un estilo arquitectónico (monolito modular, microservicios, eventos).
Adoptar una base de datos, un broker de mensajes o un proveedor de nube.
Definir cómo se autentican los servicios entre sí.
Aceptar conscientemente una deuda técnica con fecha de revisión.

Estructura de un ADR

El formato más difundido, propuesto por Michael Nygard, tiene cinco secciones:

# 7. Usar una cola para el envío de notificaciones

- Estado: Aceptado
- Fecha: 2026-03-14

## Contexto
El envío de correos tarda hasta 4 s y falla un 2 % de las veces. Hoy ocurre
dentro de la petición de inscripción, que se vuelve lenta y falla si el
proveedor de correo no responde.

## Decisión
Publicaremos un evento `InscripcionConfirmada` en una cola. Un proceso
independiente enviará el correo con reintentos y backoff exponencial.

## Consecuencias
+ La inscripción responde en < 300 ms aunque el correo falle.
+ Los reintentos dejan de bloquear al usuario.
− Añadimos un componente que operar y monitorear (la cola).
− El correo llega con unos segundos de retraso (consistencia eventual).

El ciclo de vida de una decisión

Los ADR no se editan para «cambiar de opinión». Cuando una decisión deja de ser válida, se escribe un ADR nuevo que la reemplaza, y el antiguo se conserva con su estado actualizado. Así se preserva la historia completa.

Estados de un ADR: Propuesto pasa a Aceptado o Rechazado; Aceptado puede pasar a Obsoleto o Reemplazado por un ADR nuevo — Ciclo de vida de un ADRSVG Fuente .excalidraw

El mismo flujo, como diagrama Mermaid (útil cuando quieres mantenerlo como texto dentro del repositorio):

stateDiagram-v2
    direction LR
    [*] --> Propuesto
    Propuesto --> Aceptado: revisión del equipo
    Propuesto --> Rechazado
    Aceptado --> Obsoleto: el contexto desaparece
    Aceptado --> Reemplazado: nuevo ADR lo sustituye
    Rechazado --> [*]
    Obsoleto --> [*]
    Reemplazado --> [*]

Estados de un ADR

Dónde guardarlos

Junto al código, en Markdown, versionados con Git. Así se revisan en los mismos pull requests que los cambios que motivan, y nadie tiene que buscar en una wiki desactualizada.

Directoriodocs/
- Directorioadr/
  - 0001-registrar-decisiones-arquitectonicas.md
  - 0002-monolito-modular-como-punto-de-partida.md
  - 0007-usar-cola-para-notificaciones.md
  - README.md índice con el estado de cada ADR
Directoriosrc/
- …
README.md

Recursos

Plantilla de ADRFormato Nygard ampliado con alternativas consideradas. Lista para copiar en docs/adr/.MD · 1 KB

Practica

EjercicioEscribe el ADR de una decisión realintermedio⏱ 30 min

Piensa en un proyecto en el que hayas participado (académico o laboral) y elige una decisión técnica relevante: la base de datos, el framework, la forma de desplegar…

Escribe su ADR con la plantilla. Debe incluir al menos dos alternativas consideradas y dos consecuencias negativas. Después, intercámbialo con un compañero: ¿podría entender la decisión sin haber estado en el proyecto?

Ver solución

No hay una única respuesta correcta. Revisa tu ADR con estas preguntas:

¿El contexto describe fuerzas y restricciones concretas (números, plazos, habilidades del equipo) y no solo «queríamos algo moderno»?
¿La decisión está redactada en voz activa y en una o dos frases («Usaremos…»)?
¿Las alternativas se descartan por razones vinculadas al contexto?
¿Las consecuencias negativas son honestas y verificables?

Para profundizar

Michael Nygard, Documenting Architecture Decisions (2011).
adr.github.io: plantillas alternativas (MADR, Y-statements) y herramientas.