El porqué de tu arquitectura, por escrito: para qué sirve un ADR
Todos los equipos de ingeniería han vivido esta conversación. Un desarrollador abre un módulo, se queda mirando una implementación que parece innecesariamente compleja y pregunta: "¿por qué se hizo así?". Silencio en la sala. La persona que tomó la decisión se marchó hace ocho meses. Alguien recuerda vagamente un hilo de Slack. Otro, una sesión de pizarra que nadie llegó a fotografiar. Nadie sabe explicar el razonamiento real.
A partir de ahí, el equipo hace una de dos cosas. O lo deja todo como está por miedo ("por algo sería"), creando deuda técnica permanente que nadie tocará. O lo refactoriza y, sin saberlo, reintroduce justo el problema que la implementación original quería evitar. He visto ambas cosas más veces de las que puedo contar.
Los Architecture Decision Records resuelven esto. Son una de las prácticas más simples y de mayor retorno que puede adoptar un equipo de ingeniería, y la mayoría de los equipos no la usa.
Un ADR es un registro, no una especificación
Un ADR es un documento breve — normalmente menos de una página — que captura una única decisión de arquitectura. No es un documento de diseño. No es un RFC. No es una especificación. Es solo un registro de qué se decidió, por qué se decidió y qué consecuencias se esperan.
El formato es deliberadamente mínimo. La estructura más extendida, basada en la propuesta original de Michael Nygard, tiene cinco secciones:
- Título. Una frase nominal corta. "Usar PostgreSQL para los datos transaccionales." "Adoptar event sourcing para el procesamiento de pedidos." "Implementar autenticación basada en JWT."
- Estado. Propuesto, aceptado, obsoleto o reemplazado. Si está reemplazado, enlaza al ADR nuevo.
- Contexto. ¿Cuál es la situación? ¿Qué fuerzas están en juego? ¿Qué restricciones existen? Aquí es donde se retrata el estado del mundo en el momento de la decisión.
- Decisión. ¿Qué decidimos? Exprésalo de forma clara y directa.
- Consecuencias. ¿Qué se deriva de esta decisión? Tanto lo positivo como lo negativo. ¿Qué se vuelve más fácil? ¿Qué se vuelve más difícil? ¿Qué nuevas restricciones aparecen?
Eso es todo. Sin plantillas de veinte páginas. Sin flujos de aprobación. Sin comités. Un desarrollador lo escribe, el equipo lo revisa y vive en el repositorio junto al código que describe.
Por qué la sección de contexto lo es todo
La decisión en sí suele ser evidente con solo mirar el código. Se ve que el sistema usa RabbitMQ. Se ve que la autenticación pasa por tokens JWT. Se ve que la capa de datos sigue un patrón de event sourcing.
Lo que no se ve es el porqué. Y en el porqué está todo el valor.
Una buena sección de contexto captura el panorama en el momento de decidir: las alternativas que existían, las restricciones bajo las que operaba el equipo, los compromisos que se sopesaron. Podría leerse así:
"Necesitamos una cola de mensajes para procesar de forma asíncrona los eventos de pedidos. El volumen actual es de 500 mensajes por segundo, con un crecimiento proyectado de 5.000 por segundo en 12 meses. El equipo tiene experiencia con RabbitMQ, pero no con Kafka. Somos cuatro personas y no podemos asumir la carga operativa de gestionar un clúster de Kafka. Nuestro proveedor cloud ofrece RabbitMQ gestionado, pero no Kafka gestionado."
Seis meses después, cuando un ingeniero nuevo pregunte "¿por qué no usamos Kafka?", la respuesta estará ahí mismo. Sin arqueología. Sin escribir por Slack a alguien que puede acordarse o no. Y, lo más importante: cuando el equipo sí crezca hasta el punto en que Kafka tenga sentido, podrá crear un nuevo ADR que reemplace a este, entendiendo perfectamente qué ha cambiado.
No toda decisión merece un ADR
No todas las decisiones necesitan un ADR. Elegir entre dos librerías de formateo de fechas no lo justifica. El umbral que yo uso: si la decisión es difícil de revertir, afecta a varias partes del sistema o será cuestionada por futuros miembros del equipo, escribe un ADR.
Algunos ejemplos de decisiones que siempre deberían tener uno:
Elegir una base de datos. "ADR-003: usar PostgreSQL para los datos transaccionales y Redis para el almacenamiento de sesiones." El contexto recoge por qué no MongoDB (la flexibilidad de esquema no compensaba los sacrificios en consistencia para este dominio), por qué no una única base de datos para todo (los datos de sesión tienen patrones de acceso radicalmente distintos) y cuáles son las implicaciones operativas.
Enfoque de autenticación. "ADR-007: implementar autenticación stateless basada en JWT con refresh tokens." El contexto explica por qué no autenticación por sesión (el sistema debe soportar varios tipos de cliente, incluido móvil), el compromiso de no poder revocar tokens de forma inmediata y la estrategia de mitigación (expiración corta + rotación de refresh tokens).
Patrón de comunicación entre servicios. "ADR-012: usar REST síncrono entre servicios para lecturas y eventos asíncronos para escrituras." El contexto recoge por qué no una arquitectura totalmente orientada a eventos (el equipo aún no tiene esa experiencia y el sistema no es lo bastante complejo para justificar la carga operativa) y cuándo conviene revisar esta decisión.
Selección de servicios de terceros. "ADR-015: usar Stripe para el procesamiento de pagos en lugar de construir una integración a medida con la API del banco." El contexto documenta la comparación de costes, el compromiso del vendor lock-in y las capacidades concretas que inclinaron la balanza.
Los ADRs viven en el repositorio, no en la wiki
Esto no es negociable: los ADRs viven en el repositorio de código. No en Confluence. No en Google Docs. No en Notion. En el repositorio, en un directorio como /docs/adr/ o /adr/, versionados junto al código que describen.
Las razones son prácticas: son fáciles de encontrar (están ahí mismo cuando un desarrollador trabaja en la base de código), están versionados (Git te regala el historial y el blame), viajan con el código (haz un fork del repositorio y las decisiones van incluidas) y se revisan como código (los ADRs pasan por pull requests, lo que añade aún más contexto).
Numéralos de forma secuencial: 0001-usar-postgresql-para-datos-transaccionales.md, 0002-adoptar-autenticacion-jwt.md. La numeración crea una línea temporal que cuenta la historia de cómo evolucionó la arquitectura.
El coste de no tener ADRs
La ausencia de ADRs genera tres problemas concretos y caros:
Conocimiento tribal. Las decisiones de arquitectura viven en la cabeza de quienes las tomaron. Cuando esas personas se van — y se irán —, el conocimiento se va con ellas. El equipo que queda hereda una arquitectura que no entiende del todo, y la trata como sagrada (negándose a cambiar lo que no entiende) o como desechable (refactorizando sin conocer las restricciones).
Debates que se repiten. Sin un registro de por qué se tomó una decisión, los equipos reabren las mismas discusiones cada pocos meses. "¿Deberíamos pasarnos a Kafka?" se debate tres veces al año porque nadie recuerda que el equipo ya lo evaluó y lo descartó por razones concretas y documentadas. Cada debate quema horas de ingeniería senior y genera frustración.
Fricción en el onboarding. Quien se incorpora a un equipo sin ADRs tiene que reconstruir por ingeniería inversa toda la lógica de la arquitectura: a partir del código, de mensajes sueltos de Slack y de lo que el equipo actual logre recordar en explicaciones improvisadas. He visto periodos de onboarding estirarse de semanas a meses solo por falta de contexto arquitectónico.
Empezar sin burocracia
El mayor error que cometen los equipos con los ADRs es tratarlos como un ejercicio burocrático. Crean plantillas elaboradas, comités de revisión y flujos de aprobación. Y al final nadie los escribe, porque el esfuerzo no compensa.
Empieza simple:
- La próxima vez que tu equipo tome una decisión de arquitectura significativa, pide a quien la impulsó que dedique 20 minutos a escribirla en el formato de cinco secciones.
- Súbela en un PR. Revísala como código. Fusiónala. Ese es tu primer ADR.
- Repite con las siguientes cuatro decisiones significativas.
Para el quinto ADR, el equipo empezará a citar los anteriores en sus discusiones. "Este es el mismo compromiso que documentamos en el ADR-003." Ese es el momento en que la práctica se vuelve autosostenible: cuando el equipo ve el valor en su propio flujo de trabajo, no porque lo diga un documento de procesos.
En Conectia hemos visto que los ADRs marcan una diferencia especialmente grande en equipos distribuidos. Cuando nuestros ingenieros senior se incorporan al equipo de un cliente, los ADRs existentes les permiten entender la lógica de la arquitectura en días, no en semanas. Y cuando aportan ADRs nuevos, están alimentando una memoria institucional que sobrevive a la permanencia de cualquier persona. Es una de esas prácticas pequeñas que, con el tiempo, se convierten en una ventaja competitiva seria para la organización de ingeniería.
El mejor momento para empezar a escribir ADRs fue cuando tomaste tu primera decisión de arquitectura. El segundo mejor momento es ahora.
¿Estás construyendo un equipo que toma decisiones de arquitectura sólidas y además las documenta? Habla con un CTO — nuestros ingenieros senior de LATAM llevan la disciplina de las decisiones estructuradas a tu base de código desde el primer día.
