Definición corta

Documento breve que deja constancia de una decisión de arquitectura de software: el contexto que la hizo necesaria, las opciones consideradas, la opción elegida y las consecuencias aceptadas. Abreviado como ADR.

Definición detallada

La práctica viene de los equipos de desarrollo y allí está ampliamente establecida. Su razón de ser es temporal: varios meses o varios años después, alguien que no estaba debe poder entender por qué se tomó una decisión técnica — por qué se introdujo una cola para procesar ciertos mensajes de forma asíncrona, qué opciones se descartaron, qué permite esa elección y qué restringe.

En los artículos de este blog, el término se emplea como referencia de origen más que por sí mismo: sirve para situar el Product Decision Record, que retoma su estructura desplazando el objeto del componente técnico a la regla de producto. La diferencia de naturaleza es la de aquello que se registra — un ADR fija una decisión sobre cómo se construye el sistema, un PDR una regla aplicable a situaciones futuras.

El ADR tiene una propiedad que el vocabulario de producto retoma mal: documenta con frecuencia trabajos sin valor de negocio visible. Un mes de trabajo sobre una tecnología de colas no entrega nada al usuario final y, aun así, puede eliminar un cuello de botella, absorber de diez a treinta veces la carga con solo añadir servidores y liberar la venta de nuevos accesos a clientes.

Uso en el ámbito

El término aparece en las discusiones sobre la memoria técnica de un equipo, sobre la justificación de trabajos sin entrega funcional, y como punto de comparación en cuanto se propone un dispositivo equivalente del lado del producto.

Sinónimos y variantes

"Decisión de arquitectura", "ADR", "registro de arquitectura". El plural "los ADR" designa habitualmente tanto el registro entero como sus entradas.

No confundir con

• Product Decision Record — Product Decision Record — la misma forma documental aplicada a una regla de decisión de producto transversal; no compromete ninguna decisión de construcción.
• Documentación de arquitectura — descripción del estado del sistema tal como es; el ADR describe un momento de elección y no se actualiza cuando el sistema evoluciona.
• Especificación técnica — descripción de lo que hay que construir y cómo; se deriva de una decisión de arquitectura, no la justifica.

Ejemplos

"Una aplicación sufre un aumento de carga. […] El equipo decide entonces implantar una tecnología de colas para procesar ciertos mensajes de forma asíncrona." — la situación tipo que el ADR consigna.

"¿Por qué se tomó? ¿Qué opciones se descartaron? ¿Qué consecuencias se aceptan? ¿Qué permite? ¿Qué restringe?" — las preguntas a las que responde la entrada.

Ambigüedades / debates

El uso corriente duda sobre la inmutabilidad: algunos equipos mantienen sus ADR como documentos congelados y marcan los reemplazos, otros los actualizan como documentación viva. El sentido elegido aquí sigue la primera práctica, que es también la que retoma el PDR.