A quien no le ha pasado que alguna persona pregunta por qué se descartó hace un tiempo una opción que ahora, sobre el papel, parecía la más razonable. O quién tomó esa decisión. Nadie en la sala lo suele saber. Seguramente alguien se ponga a buscar en correos y chats y se llegue a algún mensaje con pistas pero no se sabe a ciencia cierta. Media hora de discusión después, se deja por imposible saber qué paso. Ese tipo de situaciones, que se repiten en casi todas las organizaciones, es exactamente el problema que los Architecture Decision Records (ADR) ayudan a resolver.
Qué es un ADR
Un ADR es un documento breve que recoge una decisión significativa, el contexto en el que se tomó, las alternativas que se consideraron, y las consecuencias (positivas y negativas) que se aceptan al tomar dicha decisión. No es un documento de diseño extenso ni una especificación técnica; es, más bien, una fotografía del razonamiento en un momento concreto, pensada para que cualquiera que la lea meses o años después entienda no solo qué se decidió, sino todo el contexto, incluyento el por qué, quién estuvo implicado, y otros datos que se consideren relevantes para la decisión.
La estructura suele ser sencilla: un título, un estado (propuesta, aceptada, rechazada, sustituida), el contexto que motivó la decisión, la decisión en sí, y las consecuencias que se derivan de ella. Esa sencillez es precisamente su punto fuerte: un ADR se puede escribir en media hora y se puede leer en cinco minutos, lo que hace que realmente se use, a diferencia de otra documentación más pesada que casi nadie mantiene actualizada.
Dependiendo del tipo de decisión e impacto de la misma, se pueden añadir campos adicionales como opciones descartadas, personas implicadas, o riesgos.
Para qué sirven
El beneficio más evidente es la trazabilidad: cuando alguien se pregunta por qué el sistema es como es, o por qué se hace el proceso de esa manera, hay un lugar donde buscar la respuesta en lugar de reconstruirla de memoria o, peor, repetir un debate que ya se tuvo. Pero hay más beneficios, quizás menos obvios:
- Onboarding. Una persona que se incorpora a un equipo puede leer los ADR relevantes y entender en poco tiempo el porqué de decisiones que, de otro modo, parecerían arbitrarias o incluso discutibles.
- Coherencia en el tiempo. Las organizaciones cambian de personas, y con ellas se va el conocimiento tácito. Los ADR son una forma de conservar ese conocimiento más allá de quién esté presente en la sala.
- Mejor calidad de decisión. El simple hecho de tener que escribir el contexto y las alternativas obliga a pensar con más rigor antes de decidir, algo parecido a lo que comentábamos hace tiempo sobre la importancia de documentar.
- Evitar discutir lo ya decidido. Cuando una decisión está documentada, con su contexto y sus razones, es mucho más difícil que alguien la cuestione sin aportar información nueva. Y si aparece información nueva, el ADR es precisamente el lugar donde registrar que la decisión ha evolucionado.
No son solo para decisiones técnicas
Aquí quiero detenerme, porque es la idea central de este post. Cuando se habla de ADR, la asociación casi automática es con decisiones de arquitectura de software: qué base de datos usar, qué patrón de mensajería, si adoptar microservicios o no. Y es cierto que ese fue el origen del concepto. Pero reducir los ADR a lo puramente técnico es desaprovechar buena parte de su potencial.
Cualquier decisión relevante, difícil de revertir y con impacto significativo en la organización es candidata a tener su propio ADR, independientemente del dominio al que pertenezca. Decidir centralizar una función que hasta ahora estaba distribuida por unidades de negocio, elegir un modelo de gobierno de datos, definir qué información se comparte con terceros, establecer una política de proveedores, o incluso decisiones organizativas como cambiar la estructura de reporting de un área: todas ellas tienen el mismo patrón que una decisión técnica. Hay un contexto, hay alternativas, hay una elección, y hay consecuencias que alguien tendrá que vivir después.
Este enfoque encaja de forma natural con cómo entendemos la arquitectura empresarial. Si recordamos los cuatro dominios que suelen describirse en marcos como TOGAF —negocio, información, aplicaciones y tecnología—, veremos que los ADR tienen sentido y aportan valor en cada uno de ellos, no solo en el último.
Dominio de negocio
En este dominio, un ADR puede recoger decisiones sobre el modelo operativo, la estructura organizativa, la definición de procesos clave o el reparto de responsabilidades entre unidades. Por ejemplo, la decisión de centralizar la atención al cliente en lugar de mantenerla distribuida por regiones tiene implicaciones profundas y duraderas. Documentar por qué se tomó esa decisión, qué alternativas se descartaron (por ejemplo, un modelo híbrido) y qué consecuencias se aceptaron (por ejemplo, menor cercanía local a cambio de mayor consistencia) evita que, dentro de tres años, alguien proponga deshacer el cambio sin conocer los motivos reales que lo justificaron.
Dominio de información
Aquí los ADR resultan especialmente valiosos porque las decisiones sobre datos suelen tener consecuencias que tardan años en manifestarse del todo. Elegir un modelo de gobierno de datos centralizado o federado, decidir qué se considera un dato maestro y quién es su propietario, o establecer una política de retención y privacidad, son decisiones que condicionan silenciosamente todo lo que se construye después. Un ADR bien escrito en este dominio ayuda a que, cuando aparezca un problema de calidad o de duplicidad de datos, se pueda entender si es una consecuencia asumida de una decisión anterior o un efecto no previsto que merece revisión.
Dominio de aplicaciones
Este es el terreno más habitual para los ADR y probablemente donde el lector ya los conoce mejor: decisiones sobre patrones de integración, elección de un producto frente a un desarrollo a medida, adopción de una arquitectura de microservicios o de eventos, criterios de desacoplamiento entre sistemas. Lo interesante es que, cuando estas decisiones se documentan siguiendo el mismo formato que las de negocio o información, se hace mucho más fácil ver cómo se relacionan entre sí: una decisión de aplicaciones casi siempre es consecuencia de una decisión de negocio, y tener ambas trazadas con el mismo lenguaje ayuda a mantener esa coherencia de la que hablábamos en su momento al referirnos al pensamiento sistémico.
Dominio de tecnología
Por último, en el dominio tecnológico encontramos decisiones sobre infraestructura, proveedores de nube, estándares de seguridad o herramientas de plataforma. Son decisiones que suelen tener un componente de coste y de dependencia a largo plazo especialmente alto, muy relacionado con lo que comentábamos al hablar del lock-in. Un ADR que documente por qué se eligió un proveedor concreto, qué alternativas se evaluaron y qué riesgos de dependencia se aceptaron conscientemente, es una herramienta muy útil para revisar esa decisión con criterio cuando las condiciones del mercado cambien.
Cuándo usarlos y quién debería usarlos
No todas las decisiones merecen un ADR. Escribir uno por cada elección menor generaría más ruido que valor y acabaría, como tantas otras iniciativas de documentación, cayendo en desuso. La regla práctica que mejor funciona es preguntarse si la decisión es significativa, si es costosa de revertir, y si es probable que alguien, en el futuro, se pregunte por qué se tomó. Si la respuesta a esas preguntas es sí, merece un ADR.
En cuanto a quién debería usarlos, la respuesta honesta es: cualquier rol que tome decisiones estructurales, no solo el arquitecto de software. Un responsable de procesos de negocio, un director de datos, un responsable de seguridad, un product manager que decide el alcance de una plataforma: todos ellos toman decisiones del mismo tipo, aunque en dominios distintos, y todos se beneficiarían de dejar ese mismo rastro de razonamiento.
El beneficio de fondo para la organización
Más allá del beneficio individual de cada ADR, lo que realmente aporta valor es la acumulación de muchos de ellos a lo largo del tiempo: un histórico coherente de por qué la organización es como es hoy. Ese histórico reduce la dependencia de la memoria de unas pocas personas, facilita la incorporación de nuevos perfiles, evita reabrir debates ya cerrados sin motivo, y quizás lo más importante, obliga a explicitar el razonamiento detrás de decisiones que, de otra forma, quedarían como simples afirmaciones de autoridad («se hace así porque lo digo yo»).
En el fondo, un ADR es un ejercicio de humildad: reconocer que ninguna decisión es evidente por sí misma, que siempre hay alternativas descartadas y consecuencias que alguien deberá gestionar, y que merece la pena dejar constancia de todo ello para quien venga después. No hace falta que sea largo, ni perfecto, ni definitivo. Basta con que sea honesto.
La próxima vez que alguien en una reunión pregunte «¿por qué hicimos esto así?», lo ideal no es tener que reconstruir la respuesta de memoria, entre varias versiones contradictorias. Lo ideal es poder decir: «está en el ADR», y abrirlo.