Cómo escribir ADRs (Architecture Decision Records): plantilla, ejemplos y buenas prácticas

Por Felipe Traina · 28/9/2026 · 7 min · arquitectura, adr, documentacion, liderazgo-tecnico

Casi todo equipo con algunos años de historia tiene una decisión que nadie sabe explicar: por qué hay dos colas de mensajes, por qué ese servicio usa otra base de datos, por qué no se usa el ORM en tal módulo. Quien llega tiene dos opciones, y Michael Nygard las describió en 2011 en el artículo que popularizó los ADRs: aceptar la decisión a ciegas (y arriesgarse a sostener algo que ya no tiene sentido) o cambiarla a ciegas (y arriesgarse a romper un requisito que nadie recuerda).

Un Architecture Decision Record (ADR) es la forma más barata de evitar ese dilema: un documento corto, versionado junto al código, que registra una decisión importante, su contexto y sus consecuencias. Esta guía explica qué documentar, propone una plantilla y repasa las prácticas que recomiendan Nygard, Microsoft y la comunidad de adr.github.io.

Qué es exactamente un ADR

La comunidad de adr.github.io usa tres definiciones:

La idea clave es "una decisión por documento". Un ADR no es un documento de diseño, ni una wiki de arquitectura, ni un RFC de veinte páginas.

Qué decisiones merecen un ADR

Nygard propuso documentar las decisiones "arquitectónicamente significativas": las que afectan la estructura, las características no funcionales, las dependencias, las interfaces o las técnicas de construcción. La guía de Azure Well-Architected agrega un criterio práctico: incluir las decisiones que afectan la estructura, los atributos de calidad clave o que son difíciles de revertir.

Ejemplos típicos:

Ejemplos que normalmente no necesitan un ADR: elegir una librería de fechas, renombrar un módulo o cambiar el linter. La pregunta útil es: "¿alguien dentro de dos años va a necesitar saber por qué hicimos esto?".

La plantilla de Nygard (y qué agregarle)

El formato original tiene cinco partes:

  1. Título: una frase nominal corta, numerada. Por ejemplo, "ADR 9: LDAP para integración multitenant".
  2. Contexto: las fuerzas en juego (técnicas, políticas, sociales, del proyecto), descritas de forma neutral.
  3. Decisión: la respuesta a esas fuerzas, en voz activa: "Vamos a…".
  4. Estado: propuesta, aceptada, deprecada o reemplazada (superseded).
  5. Consecuencias: todas, no solo las positivas.

Nygard sugiere que todo el documento ocupe una o dos páginas y que se escriba como una conversación con un desarrollador futuro, con oraciones completas.

La guía de Microsoft suma elementos que en la práctica ayudan mucho: opciones consideradas, trade-offs explícitos y el nivel de confianza de la decisión. Registrar que una decisión se tomó con poca confianza es valioso cuando llega el momento de revisarla.

Una plantilla que combina ambas:

# ADR-0012: Usar PostgreSQL con pgvector para búsqueda semántica

- Estado: Aceptada
- Fecha: 2026-09-28
- Decisores: equipo de plataforma
- Confianza: media
- Reemplaza a: -
- Reemplazada por: -

## Contexto
Necesitamos búsqueda semántica sobre ~2 millones de documentos internos.
Ya operamos PostgreSQL en producción y el equipo tiene experiencia con él.
No tenemos a nadie dedicado a operar una base vectorial separada.

## Opciones consideradas
1. PostgreSQL + pgvector
2. Base de datos vectorial gestionada
3. Motor de búsqueda existente con soporte de vectores

## Decisión
Vamos a usar PostgreSQL con la extensión pgvector en el clúster actual.

## Consecuencias
- (+) Un solo sistema que operar, respaldar y monitorear.
- (+) Transacciones y joins entre vectores y datos de negocio.
- (-) Si el volumen crece un orden de magnitud, puede hacer falta migrar.
- (-) Las búsquedas compiten por recursos con la carga transaccional.

## Cuándo revisar esta decisión
Si superamos 20 millones de documentos o la latencia p95 de búsqueda supera 300 ms.

El contenido del ejemplo es ilustrativo, pero la sección final no es decorativa: definir de antemano qué cambio de contexto justificaría revisar la decisión evita tanto la aceptación ciega como el cambio ciego.

Si preferís no diseñar tu propia plantilla, MADR (Markdown Architectural Decision Records) es una plantilla mantenida por la comunidad de adr.github.io, con variantes completa, mínima y "bare".

Dónde guardarlos y cómo numerarlos

Nygard propuso guardarlos en el repositorio del proyecto, en archivos Markdown numerados de forma secuencial, sin reutilizar números. Una estructura común:

docs/adr/
├── 0001-registrar-decisiones-de-arquitectura.md
├── 0002-monorepo-con-pnpm-workspaces.md
├── 0011-usar-elasticsearch-para-busqueda.md   (Reemplazada por 0012)
└── 0012-postgresql-pgvector-busqueda-semantica.md

Tenerlos en el repo tiene ventajas concretas: se revisan en pull requests como cualquier cambio, quedan versionados y están al lado del código que explican. Un buen primer ADR, de hecho, es el que registra la decisión de usar ADRs.

Regla de oro: no editar decisiones aceptadas

La guía de Azure lo dice sin ambigüedad: el registro es un log de solo agregado (append-only). No se editan los ADRs aceptados. Si la decisión cambia, se escribe uno nuevo que reemplaza al anterior y se enlazan entre sí. Nygard proponía lo mismo: el ADR viejo se conserva, marcado como reemplazado, porque sigue siendo relevante saber que esa fue la decisión, aunque ya no lo sea.

Así se preserva la historia del razonamiento: se ve cuándo y por qué cambió el rumbo. Corregir un error de tipeo está bien; reescribir la decisión o su contexto, no.

Cómo integrarlos al flujo de trabajo

Los ADRs fracasan cuando se escriben después, como burocracia. Funcionan cuando son parte del proceso:

Errores comunes

Qué hacer con esto

¿Qué decisión de tu sistema actual te gustaría que alguien hubiera documentado hace tres años?

Lecturas relacionadas

Fuentes

← Volver al blog