El Registro de Decisiones de Arquitectura: Por Qué Tu Equipo Necesita Uno
Todos los equipos de ingeniería han tenido esta conversación. Un desarrollador abre un módulo, mira una implementación que parece innecesariamente compleja y pregunta: "¿Por qué se construyó así?" El silencio se apodera de la sala. La persona que tomó la decisión se fue hace ocho meses. Alguien recuerda vagamente un hilo de Slack. Otro recuerda una sesión de pizarra que nunca fue fotografiada. Nadie puede explicar el razonamiento real.
El equipo hace una de dos cosas. O lo dejan como está por miedo ("probablemente había una razón"), creando deuda técnica permanente que nadie tocará. O lo refactorizan, reintroduciendo sin saberlo exactamente el problema que la implementación original fue diseñada para evitar.
Los Architecture Decision Records lo solucionan. Son una de las prácticas más simples y con mayor ROI que un equipo de ingeniería puede adoptar, y la mayoría de los equipos no las usan.
Qué es Realmente un ADR
Un ADR es un documento corto — normalmente menos de una página — que captura una única decisión arquitectónica. No un documento de diseño. No un RFC. No una especificación. Solo un registro de qué se decidió, por qué se decidió y cuáles son las consecuencias esperadas.
El formato es deliberadamente mínimo. La estructura más utilizada, basada en la propuesta original de Michael Nygard, tiene cinco secciones:
- Título. Una frase nominal corta. "Usar PostgreSQL para datos transaccionales." "Adoptar event sourcing para el procesamiento de pedidos."
- Estado. Propuesto, Aceptado, Obsoleto o Reemplazado. Si es reemplazado, enlaza al nuevo ADR.
- Contexto. ¿Cuál es la situación? ¿Qué fuerzas están en juego? ¿Qué restricciones existen?
- Decisión. ¿Qué decidimos? Exprésalo de forma clara y directa.
- Consecuencias. ¿Qué se deriva de esta decisión? Tanto positivas como negativas.
Por Qué la Sección de Contexto lo Es Todo
La decisión en sí suele ser obvia al mirar el código. Lo que no puedes ver es el porqué. Y el porqué es donde reside todo el valor.
Una buena sección de contexto captura el panorama de la decisión en ese momento: las alternativas que existían, las restricciones bajo las que operaba el equipo, los trade-offs que sopesaron. Podría leerse algo así:
"Necesitamos una cola de mensajes para el procesamiento asíncrono de eventos de pedidos. El volumen actual es de 500 mensajes/segundo con un crecimiento proyectado a 5.000/segundo en 12 meses. El equipo tiene experiencia con RabbitMQ pero no con Kafka. Somos un equipo de cuatro y no podemos asumir la carga operativa de gestionar un cluster de Kafka."
Seis meses después, cuando un nuevo ingeniero pregunta "¿por qué no usamos Kafka?", la respuesta está ahí mismo.
Ejemplos de Buenos Temas para ADRs
El umbral que uso: si la decisión es difícil de revertir, afecta a múltiples partes del sistema, o será cuestionada por futuros miembros del equipo, escribe un ADR.
Ejemplos de decisiones que siempre deben tener uno:
Elegir una base de datos. "ADR-003: Usar PostgreSQL para datos transaccionales y Redis para almacenamiento de sesiones."
Enfoque de autenticación. "ADR-007: Implementar autenticación stateless basada en JWT con tokens de actualización."
Patrón de comunicación entre servicios. "ADR-012: Usar REST síncrono entre servicios para lecturas, eventos asíncronos para escrituras."
Selección de servicio de terceros. "ADR-015: Usar Stripe para el procesamiento de pagos en lugar de construir una integración personalizada."
Dónde Viven los ADRs
Esto es no 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.
Númeralos secuencialmente: 0001-usar-postgresql-para-datos-transaccionales.md, 0002-adoptar-autenticacion-jwt.md.
El Coste de No Tener ADRs
La ausencia de ADRs crea tres problemas específicos y medibles:
Conocimiento tribal. Las decisiones arquitectónicas viven en las cabezas de quienes las tomaron. Cuando esas personas se van — y se irán — el conocimiento se va con ellas.
Debates rehechos. Sin un registro de por qué se tomó una decisión, los equipos revisan las mismas discusiones cada pocos meses.
Fricción en el onboarding. Un nuevo miembro del equipo que se une sin ADRs tiene que realizar ingeniería inversa de toda la lógica arquitectónica.
Empezar Sin Burocracia
El mayor error que cometen los equipos con los ADRs es tratarlos como un ejercicio burocrático. Empiecen de forma simple. La próxima vez que tu equipo tome una decisión arquitectónica significativa, haz que quien la impulsó dedique 20 minutos a escribirla en formato de cinco secciones. Ponla en un PR. Revisala. Fusiónala. Ese es tu primer ADR.
En Conectia, hemos visto que los ADRs marcan una diferencia particularmente grande en equipos distribuidos. Cuando nuestros ingenieros senior se unen al equipo de un cliente, los ADRs existentes les permiten entender la lógica arquitectónica en días en lugar de semanas.
¿Construyendo un equipo que toma decisiones arquitectónicas sólidas y las documenta? Habla con un CTO — nuestros ingenieros senior de LATAM traen la disciplina de la toma de decisiones estructurada a tu base de código desde el primer día.
