Architecture Decision Record (ADR)

Documento que captura una decisión de diseño arquitectónicamente significativa: el contexto, las opciones evaluadas, la decisión tomada y sus consecuencias.

El propósito

Un ADR responde a la pregunta “¿Por qué tomamos esta decisión?”, no solo el “qué”. Cuando todos los ADRs de un sistema están agrupados, describen el estado actual de ese sistema.

Cuándo usarlo

• Cuando hay más de una solución posible y la elección tiene consecuencias a largo plazo.
• Al integrar nuevas tecnologías o middleware.
• Al actualizar tácticas o patrones arquitectónicos.
• Antes de cambios que afecten múltiples equipos.

Estructura típica

1. Título — identificador corto.
2. Problem Statement — ¿Qué problema estamos resolviendo?
3. Contexto — ¿Qué factores rodean esta decisión?
4. Opciones consideradas — Alternativas evaluadas.
5. Decisión — Qué se eligió y por qué.
6. Consecuencias — Trade-offs, deudas técnicas que se introducen, qué se facilita.
7. Log de cambios — Historial de actualizaciones al ADR.

Dos usos principales

• Seed a conversation: crear un borrador para generar discusión antes de decidir.
• Document the decision: registrar la decisión ya tomada para que el contexto no se pierda.

Por qué importa

Sin ADRs, los equipos repetidamente preguntan “¿por qué está hecho así?” sin respuesta. El conocimiento institucional desaparece con la rotación de personas. Los ADRs son la memoria técnica del equipo.