5 min read
“¿Por qué usamos MongoDB acá si el resto del sistema es PostgreSQL?” Nadie en el equipo sabe la respuesta. La persona que tomó la decisión se fue de la empresa hace un año.
Lo único que queda es el código, que no explica el porqué — solo el qué.
Esta escena se repite en casi todos los equipos de software, y tiene una solución sorprendentemente simple que muy pocos equipos aplican de forma consistente: los ADR (Architecture Decision Records — Registros de Decisiones de Arquitectura).
¿Qué es un ADR?
Un ADR es un documento corto — típicamente menos de una página — que registra una decisión de arquitectura significativa: qué se decidió, por qué, qué alternativas se consideraron y por qué se descartaron.
Se guarda en el mismo repositorio de código, versionado junto con el proyecto, no en una wiki externa que nadie actualiza.
La idea la formalizó Michael Nygard (el mismo autor de Release It!, que ya mencionamos en los posts de Circuit Breaker y Bulkhead) y se popularizó porque resuelve un problema real: las decisiones técnicas importantes se toman en una reunión, en un canal de Slack, o en la cabeza de una sola persona, y luego se pierden para siempre.
Qué merece un ADR (y qué no)
No todo necesita un ADR — escribir uno por cada variable que renombrás sería ruido, no documentación. Los buenos candidatos son decisiones que cumplen al menos una de estas condiciones:
- Son costosas de revertir (elegir una base de datos, un lenguaje, un proveedor cloud).
- Afectan a todo el equipo o a varios equipos, no solo a quien las toma.
- Alguien, en algún momento, preguntó “¿por qué hicimos esto así?” más de una vez.
- Hubo alternativas reales sobre la mesa, y se descartaron por una razón que vale la pena recordar.
La plantilla que funciona
No hace falta reinventar el formato — esta estructura, derivada del formato original de Nygard, cubre lo esencial sin volverse burocrática:
# ADR-012: Uso de Redis para caché de sesiones
## Estado
Aceptado
## Contexto
Nuestro servicio de autenticación consulta la base de datos principal
en cada request para validar la sesión del usuario. Con el crecimiento
de tráfico, esto se convirtió en el 40% de la carga de lectura de la
base de datos, según las métricas de Datadog del último mes.
## Decisión
Vamos a introducir Redis como caché de sesiones, con un TTL de 30
minutos alineado a la expiración del token de sesión.
## Alternativas consideradas
- Aumentar réplicas de lectura de PostgreSQL: descartado porque no
resuelve el problema de raíz, solo lo distribuye, y el costo mensual
es mayor al de Redis para este volumen.
- Cachear en memoria por instancia: descartado porque con múltiples
instancias detrás del load balancer, la tasa de cache hit sería
demasiado baja e inconsistente entre instancias.
## Consecuencias
- Se agrega una nueva dependencia de infraestructura (Redis) que
requiere monitoreo y un plan de alta disponibilidad.
- Se reduce la carga de lectura estimada en un 35-40% sobre la base
de datos principal.
- Se introduce el riesgo de servir sesiones desactualizadas por hasta
30 minutos si un usuario es deshabilitado manualmente.
Guía paso a paso
Paso 1 — Creá una carpeta docs/adr en el repositorio
Numerá los archivos secuencialmente: 0001-titulo-de-la-decision.md, 0002-otra-decision.md. El orden numérico cuenta la historia arquitectónica del proyecto.
Paso 2 — Escribí el ADR antes o justo después de tomar la decisión
Escribirlo antes obliga a pensar en las alternativas de forma explícita. Escribirlo justo después captura el razonamiento mientras está fresco — esperar semanas garantiza que el contexto se pierda.
Paso 3 — Mantené el estado actualizado
Un ADR puede estar “Propuesto”, “Aceptado”, “Rechazado”, o “Reemplazado por ADR-0023”. Nunca edites un ADR viejo para cambiar la decisión — creá uno nuevo que referencie al anterior. El historial de decisiones es tan valioso como la decisión actual.
Paso 4 — Revisalo en el mismo Pull Request de la implementación
El ADR entra a revisión junto con el código que lo implementa. Así el equipo discute el razonamiento, no solo la sintaxis.
Paso 5 — Referencialo desde el código cuando sea relevante
Un comentario simple como // Ver docs/adr/0012-cache-redis.md junto a la configuración de Redis conecta el código con su razón de ser, para quien lo encuentre meses después.
Para tener en cuenta en producción
- Los ADR no son documentación de diseño detallado: no describen cómo funciona el sistema paso a paso — para eso está la documentación técnica tradicional. El ADR responde específicamente “¿por qué elegimos este camino y no otro?”.
- Cortos, siempre: si tu ADR supera una página, probablemente estás mezclando la decisión con detalles de implementación que deberían vivir en otro lado.
- Herramientas como adr-tools automatizan lo repetitivo: numeración automática, plantillas, y hasta generación de un índice — útil si el equipo empieza a acumular muchos ADRs.
- El mejor momento para empezar es ahora, no retroactivamente: no intentés documentar todas las decisiones históricas del proyecto de una sola vez. Empezá con la próxima decisión importante y construí el hábito desde ahí.
Conclusión
Un ADR cuesta quince minutos escribirlo. Ahorra horas de arqueología de código, reuniones repetidas discutiendo lo mismo, y decisiones que se revierten sin entender por qué se tomaron originalmente.
Es documentación técnica, sí, pero en el fondo es lo mismo que un buen commit message a mayor escala: dejarle una nota clara a la persona que va a heredar tus decisiones — que probablemente seas vos mismo, dentro de un año, preguntándote “¿por qué hicimos esto así?”.
Recordá suscribirte aquí para recibir los próximos posts directamente en tu correo.
Referencias:
Michael Nygard — Documenting Architecture Decisions — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
adr-tools — https://github.com/npryce/adr-tools