Una de las preguntas que más he escuchado en revisiones de arquitectura no es "¿esto funciona?", es "¿por qué está hecho así?". Y la respuesta más común, honestamente, es un silencio incómodo seguido de "creo que fue una decisión de hace dos años, no sé si sigue siendo válida".

El código te dice qué hace el sistema. Casi nunca te dice por qué se decidió hacerlo así en vez de de otras cinco formas igual de razonables. Esa segunda parte —el contexto, las alternativas descartadas, el trade-off que se aceptó a sabiendas— es la que se pierde primero, porque vivía en la cabeza de alguien o en un canal de Slack que ya nadie puede buscar.

Qué es un ADR

Un Architecture Decision Record es un documento corto, versionado junto al código, que registra una decisión de arquitectura en el momento en que se toma. No es documentación exhaustiva del sistema — es una nota específica sobre una decisión específica, escrita mientras el contexto todavía está fresco.

La plantilla que uso, deliberadamente mínima:

# ADR 007: Usar PostgreSQL en vez de un motor NoSQL para el catálogo de productos

## Estado

Aceptado

## Contexto

Necesitamos persistir el catálogo con relaciones fuertes entre producto, categoría e inventario.
El equipo evaluó DynamoDB (ya usado en otros servicios) y PostgreSQL administrado.

## Decisión

Usamos PostgreSQL. Las consultas del catálogo requieren joins frecuentes y transacciones
multi-tabla que un modelo de acceso por clave no resuelve bien sin duplicar lógica de aplicación.

## Consecuencias

Ganamos integridad referencial y consultas ad-hoc simples. Perdemos la escalabilidad horizontal
automática de DynamoDB — aceptable porque el volumen proyectado no lo requiere en los próximos 3
años. Revisar si el volumen cambia significativamente.

Cuatro secciones. Contexto, decisión, consecuencias, y un estado que se puede actualizar ("Propuesto", "Aceptado", "Reemplazado por ADR-014"). Nada de plantillas de veinte campos que nadie va a llenar completas después de la tercera vez.

Vive en el repositorio, no en una wiki

Un ADR en docs/adr/ dentro del mismo repositorio que el código que documenta tiene tres ventajas que ninguna wiki externa te da gratis: se revisa en el mismo pull request que el cambio que implementa la decisión, queda versionado junto con el código al que aplica (si vuelves tres años a un commit viejo, el ADR de esa época sigue ahí), y aparece en las búsquedas de código de cualquiera que esté trabajando en esa parte del sistema — no hace falta que alguien recuerde que existe una wiki y sepa buscarla ahí.

¿Cuándo escribir uno? (y cuándo no)

No cada decisión merece un ADR. Si la escribes para todo, nadie las va a leer y el ritual pierde sentido. El criterio que uso: ¿esta decisión es cara de revertir, o afecta a más de un equipo, o alguien razonable podría haber elegido la alternativa contraria? Si la respuesta es sí a cualquiera de las tres, vale la pena los diez minutos que toma escribirla. Elegir un nombre de variable no necesita un ADR. Elegir entre monolito y microservicios, entre SQL y NoSQL, o adoptar un patrón como CQRS, sí.

El verdadero destinatario

Un ADR no se escribe para el equipo de hoy — se escribe para la persona que va a heredar el sistema dentro de dos años, se va a preguntar "¿por qué está hecho así?", y en vez de reconstruir la decisión desde cero o asumir que fue un error, va a poder leer exactamente qué se consideró y por qué se descartó. Muchas veces esa persona eres tú mismo, en un momento en que ya olvidaste el contexto que hoy tienes fresco. Escribir el ADR es, en el fondo, un favor que le haces a tu propia memoria futura.