Architecture Decision Record (ADR)

Definición de Architecture Decision Record

Un Architecture Decision Record es un archivo corto, concreto y estructurado donde se describe una decisión técnica clave tomada sobre la arquitectura de un sistema. El valor real está en que no solo se anota qué se decidió, sino por qué y en qué contexto.

En la práctica, un ADR se convierte en una especie de “bitácora arquitectónica” del proyecto. Cada decisión se guarda en un documento independiente, versionado junto con el código. De esta forma, cualquier persona nueva en el equipo puede reconstruir el razonamiento técnico seguido a lo largo del tiempo.

Origen del concepto ADR en ingeniería de software

El concepto de Architecture Decision Record se popularizó gracias a Michael Nygard, autor de “Release It!”. Él propuso una forma ligera de registrar decisiones que evitara la documentación pesada y poco consultada que solía usarse en proyectos tradicionales.

La idea encajó muy bien con los métodos ágiles y con la modernización de la ingeniería de software. En lugar de grandes documentos iniciales, se propone ir generando pequeños registros a medida que surgen decisiones importantes, manteniendo el conocimiento siempre actualizado.

Diferencia entre ADR y documentación técnica tradicional

La documentación técnica tradicional solía centrarse en describir el sistema como se supone que debería ser, con muchos diagramas y especificaciones extensas. Un ADR, en cambio, se orienta a capturar decisiones puntuales, con su razonamiento y efectos.

A continuación se muestra una comparación resumida entre ambos enfoques.

Aspecto	Architecture Decision Record (ADR)	Documentación técnica tradicional
Enfoque principal	Registrar decisiones y su justificación.	Describir el sistema completo y sus componentes.
Granularidad	Documentos pequeños, uno por decisión.	Documentos extensos que agrupan muchos temas.
Momento de creación	Cuando surge una decisión relevante.	Normalmente, al inicio del proyecto o en hitos grandes.
Mantenimiento	Se actualizan o suceden con nuevos ADR.	A menudo se quedan desactualizados con el tiempo.
Uso diario	Consulta rápida para entender el porqué de cambios.	Consulta ocasional, suele ser más pesada.
Integración con el repositorio	Se almacenan junto al código, versionados.	Pueden vivir fuera del repositorio, en herramientas separadas.

Estructura y formato de un ADR

Aunque cada organización puede adaptar el formato, la mayoría de Architecture Decision Records comparten un conjunto de secciones fundamentales. Estas secciones permiten que cualquier persona entienda rápidamente qué se decidió, en qué fecha, bajo qué contexto y qué alternativas se rechazaron.

Un punto clave es que un ADR debe ser lo bastante corto como para leerse en pocos minutos, pero lo bastante completo como para permitir entender el razonamiento. El equilibrio entre brevedad y profundidad es lo que hace útil a este tipo de documento en proyectos reales.

Título y contexto de la decisión

El título de un Architecture Decision Record no es un simple nombre decorativo. Idealmente, expresa de manera clara qué se decidió, por ejemplo: “ADR-005: Uso de base de datos relacional para el módulo de pagos”. Este enfoque ayuda a localizar decisiones más adelante.

El contexto describe la situación que existía antes de la decisión. Es clave explicar qué problema se quería resolver, qué restricciones había y qué información se tenía disponible. Sin ese contexto, la decisión puede parecer arbitraria cuando cambian las condiciones del proyecto.

Estado del registro de decisión arquitectónica

Además del título y el contexto, cada ADR debe dejar claro en qué estado se encuentra la decisión. Esto evita confusiones cuando una decisión se reemplaza o queda obsoleta por cambios de requisitos o tecnología.

A continuación se muestran estados típicos que se utilizan en un registro de decisión arquitectónica.

Estado	Descripción
Propuesto	La decisión está planteada, pero aún no se aprueba.
Aprobado	La decisión ha sido aceptada y se implementará.
En revisión	Se está analizando si sigue siendo válida.
Rechazado	La decisión se analizó, pero no se adoptó.
Obsoleto	La decisión fue válida, pero otra la reemplazó.
Supersedido por	Indica el identificador del ADR que sustituye este.

Opciones evaluadas antes de decidir

Un Architecture Decision Record no está completo si solo indica la solución elegida. Es esencial detallar qué alternativas se analizaron. A continuación se muestra una forma práctica de organizar estas opciones:

• Opción 1: Mantener el estado actual. Explica qué implica no cambiar nada y cuáles serían las consecuencias si se continúa con la situación existente.
• Opción 2: Solución A propuesta. Resume la arquitectura o tecnología alternativa, con sus ventajas técnicas y riesgos más evidentes.
• Opción 3: Solución B alternativa. Presenta una segunda opción viable, aunque finalmente no se elija, dejando claro por qué no resultó adecuada.
• Opción 4: Otras posibilidades descartadas rápidamente. Señala brevemente ideas consideradas pero rechazadas sin análisis profundo, para evitar que se reabran en el futuro.

Al describir cada opción, resulta útil indicar datos cuantitativos cuando existan, como costes aproximados, tiempos estimados o impacto en rendimiento. De esta forma, el ADR se convierte en una evidencia del análisis realizado, no solo en una declaración de intenciones.

Decisión tomada y justificación técnica

En la sección de decisión se explica claramente qué alternativa se ha elegido. No debería haber ambigüedades: una persona que lea este punto debe comprender sin dudas cuál es el camino seleccionado y cómo afectará al sistema.

La justificación técnica describe las razones que inclinaron la balanza hacia esa opción. Puede incluir criterios como rendimiento, simplicidad, experiencia previa del equipo, compatibilidad con sistemas existentes o alineación con la estrategia de negocio. Lo importante es conectar la decisión con objetivos concretos del proyecto.

Consecuencias positivas y negativas

Todo Architecture Decision Record debe dejar claro qué efectos se esperan tras aplicar la decisión. No solo los beneficios, también las limitaciones y riesgos que se asumen. Esto ayuda a evitar sorpresas más adelante.

A continuación se muestra un ejemplo de cómo organizar estas consecuencias.

Tipo de consecuencia	Descripción
Positiva	Mejora de rendimiento en la respuesta de las APIs.
Positiva	Reducción de complejidad en el despliegue y monitoreo.
Positiva	Mayor alineación con estándares internos de la organización.
Negativa	Aumento del coste de licencias o infraestructura.
Negativa	Curva de aprendizaje para el equipo de desarrollo.
Negativa	Dependencia de un proveedor o tecnología concreta.

¿Cuándo escribir un Architecture Decision Record?

No todas las decisiones técnicas merecen su propio ADR. El objetivo es centrarse en aquellas que tienen impacto duradero en la arquitectura, el coste, la calidad o la mantenibilidad del sistema. Tomar decisiones menores no justifica el esfuerzo de documentar cada detalle.

Un criterio útil es preguntarse: Si otra persona llegara al proyecto en seis meses, necesitaría entender esta decisión para trabajar con el sistema sin cometer errores graves. Si la respuesta es sí, probablemente convenga escribir un Architecture Decision Record.

Tipos de decisiones que requieren un ADR

Hay ciertas categorías de decisiones que casi siempre vale la pena documentar. A continuación se muestran algunos ejemplos claros que ayudan a identificar cuándo crear un Architecture Decision Record:

• Elección de estilos arquitectónicos. Por ejemplo, decidir entre arquitectura monolítica, microservicios o modular hexagonal.
• Selección de tecnologías clave. Elegir el motor de base de datos, el framework web principal o la plataforma de mensajería.
• Definición de patrones críticos. Como la adopción de un saga pattern para coordinar transacciones distribuidas o el uso de un circuit breaker pattern para mejorar la resiliencia.
• Decisiones de seguridad. Estrategias de autenticación, autorización, cifrado de datos o manejo de secretos.
• Infraestructura y despliegue. Uso de contenedores, orquestadores, proveedor de nube o estrategia on-premise.
• Integraciones externas relevantes. Cómo se conectará el sistema con proveedores, pasarelas de pago o sistemas de terceros.

Señales de que necesitas documentar una decisión

Además de los tipos de decisiones, hay señales claras en el día a día del equipo que indican que un Architecture Decision Record sería muy útil. A continuación se muestran algunas de las más frecuentes:

• Debates recurrentes en el equipo. Cuando un mismo tema se discute muchas veces sin llegar a una conclusión estable, suele faltar un ADR que cierre el asunto.
• Cambios con impacto transversal. Si una decisión afecta a varios equipos o a muchos módulos, documentarla ayuda a coordinar esfuerzos.
• Dependencias con largo plazo. Cuando se elige una tecnología o proveedor difícil de cambiar más adelante, conviene dejar constancia formal.
• Dudas frecuentes de personas nuevas. Si la misma pregunta arquitectónica aparece en cada incorporación, probablemente falta un Architecture Decision Record que la responda.
• Riesgos de seguridad o cumplimiento. En decisiones relacionadas con datos sensibles o regulaciones, un ADR aporta trazabilidad ante auditorías.

Beneficios de usar ADR en proyectos de software

Adoptar Architecture Decision Records aporta ventajas tanto a nivel técnico como organizativo. No se trata solo de “documentar por documentar”, sino de generar un repositorio vivo de decisiones que facilita la evolución del sistema.

• Memoria técnica a largo plazo. Los ADR evitan que el conocimiento se pierda cuando cambian las personas del equipo, reduciendo la dependencia de individuos concretos.
• Transparencia y alineación. Todos pueden ver qué se decidió y por qué, lo que disminuye malentendidos y discusiones repetidas.
• Mejor incorporación de nuevas personas. Quien se suma al proyecto puede ponerse al día leyendo los ADR clave, sin depender solo de conversaciones informales.
• Trazabilidad de cambios arquitectónicos. Ante auditorías, problemas en producción o rediseños, se puede rastrear el origen de cada decisión.
• Soporte para decisiones futuras. Revisar ADR antiguos ayuda a no repetir errores pasados y a entender qué supuestos han dejado de ser válidos.
• Fomento del pensamiento crítico. Saber que habrá que escribir un ADR impulsa a analizar mejor cada decisión, en lugar de elegir alternativas por inercia.

Plantilla ADR: formatos más utilizados

Existen varias plantillas para redactar Architecture Decision Records. Todas comparten la misma idea base, pero difieren en detalle, estructura y nivel de formalidad. Elegir una u otra depende del estilo del equipo y del tipo de proyecto.

A continuación se presentan formatos extendidos en la comunidad, que sirven como punto de partida. Lo importante no es seguirlos al pie de la letra, sino adaptarlos a las necesidades reales de cada organización.

Plantilla original de Michael Nygard

La propuesta de Michael Nygard es una de las más conocidas por su sencillez. Se basa en pocos apartados, muy directos, que ayudan a capturar la esencia de la decisión sin burocracia innecesaria.

A continuación se muestra un resumen de su estructura habitual.

Sección	Descripción
Título	Nombre de la decisión, con identificador numérico opcional.
Estado	Indica si la decisión está propuesta, aceptada, obsoleta, etc.
Contexto	Situación actual, problema a resolver y restricciones relevantes.
Decisión	Descripción clara de la elección realizada.
Consecuencias	Efectos positivos y negativos esperados, a corto y largo plazo.

MADR: Markdown Any Decision Records

MADR es una evolución más estructurada pensada para escribirse en archivos Markdown, ideal para repositorios Git. Aporta una plantilla algo más detallada, con secciones adicionales que facilitan la estandarización entre equipos.

A continuación se resumen los elementos más característicos de MADR.

Sección	Descripción
Título y estado	Nombre de la decisión y estado actual (propuesto, aceptado, etc.).
Fecha	Día en que se tomó o se registró la decisión.
Contexto y problema	Descripción más detallada del problema a resolver.
Opciones consideradas	Lista de alternativas analizadas, con breve explicación.
Decisión tomada	Opción elegida e indicación explícita de por qué.
Consecuencias	Impacto, ventajas, desventajas y riesgos identificados.
Vínculos relacionados	Enlaces a tickets, documentación adicional o código relevante.

Lightweight ADR para equipos ágiles

En entornos muy ágiles, algunos equipos prefieren versiones aún más ligeras. La idea es que un Architecture Decision Record se pueda escribir en pocos minutos, incluso durante una reunión corta, sin perder información esencial.

A continuación se presenta una estructura simplificada adecuada para este tipo de contexto.

Sección	Descripción
Identificador y título	Código corto y frase clara de la decisión.
Fecha y autores	Cuándo se decidió y quién participó.
Contexto breve	Dos o tres frases con el problema principal.
Decisión	Resumen concreto de la solución elegida.
Motivos clave	Lista corta de razones que justifican la elección.
Efectos esperados	Consecuencias más importantes, positivas y negativas.

Ejemplo práctico de ADR

Para entender mejor cómo se ve un Architecture Decision Record ya terminado, resulta útil revisar un ejemplo. Aunque cada proyecto tendrá sus propios detalles, la estructura general suele ser muy parecida a lo que se muestra a continuación.

Este ejemplo representa la decisión de usar un determinado tipo de base de datos para un módulo de pedidos.

Sección	Contenido de ejemplo
Título	ADR-007: Uso de base de datos relacional para el módulo de pedidos.
Estado	Aprobado.
Fecha	15/01/2026.
Contexto	El sistema necesita almacenar pedidos con consistencia fuerte y relaciones claras entre clientes, productos y facturas.
Opciones consideradas	Base de datos relacional, base de datos NoSQL de documentos, base de datos en memoria.
Decisión	Adoptar PostgreSQL como base de datos relacional principal para el módulo de pedidos.
Justificación	Soporta transacciones ACID, experiencia previa del equipo y buena integración con la infraestructura actual.
Consecuencias	Mayor seguridad en la integridad de datos, pero menos flexibilidad para escalar horizontalmente algunas operaciones.

Herramientas para gestionar Architecture Decision Records

La forma más sencilla de gestionar Architecture Decision Records es almacenarlos como archivos de texto plano, normalmente en formato Markdown, dentro del propio repositorio de código. Esto ya aporta versionado, trazabilidad y facilidad de búsqueda.

• Repositorios Git. Permiten guardar ADR junto al código, con control de versiones y revisiones mediante pull requests.
• Wikis corporativas. Herramientas como Confluence facilitan enlaces cruzados, etiquetas y búsquedas avanzadas de decisiones.
• Gestores de documentación estática. Generadores como MkDocs o Docusaurus permiten publicar ADR como sitios web navegables.
• Plantillas en IDE o extensiones. Algunos editores ofrecen snippets o extensiones que crean automáticamente nuevos ADR con la estructura definida.
• Integración con herramientas de tickets. Enlazar ADR desde sistemas como Jira ayuda a relacionar decisiones con historias de usuario y épicas.

Buenas prácticas para escribir ADR efectivos

La utilidad de un Architecture Decision Record no depende solo de la plantilla, sino de cómo se redacta. Un ADR claro, conciso y honesto vale mucho más que uno muy largo pero confuso o incompleto.

• Ser concreto y evitar ambigüedades. Indicar con precisión qué se decidió, en qué alcance aplica y qué queda fuera.
• Documentar mientras la decisión está fresca. No esperar semanas para no olvidar detalles importantes del contexto.
• Incluir participantes y responsables. Anotar quién participó en la decisión ayuda a resolver dudas futuras.
• Enlazar a diagramas y artefactos. Vincular, por ejemplo, al diagrama C4 correspondiente facilita entender el impacto visualmente.
• No ocultar riesgos ni desventajas. Reconocer de forma explícita los puntos débiles de la decisión fortalece la credibilidad del ADR.
• Revisar periódicamente las decisiones. Establecer momentos para comprobar si un ADR sigue siendo válido o debe actualizarse o quedar obsoleto.

Preguntas frecuentes

¿Qué es exactamente un Architecture Decision Record en un entorno real?

Un Architecture Decision Record en un entorno real es un documento sencillo donde se escribe una decisión técnica que va a tener impacto duradero en el sistema. Incluye el problema que se quería resolver, las alternativas analizadas, la opción elegida y las consecuencias que se esperan. Suele guardarse en el repositorio de código para consultarlo fácilmente.

¿Quién es responsable de escribir un ADR?

Normalmente, la responsabilidad recae en la persona o grupo que lidera la decisión arquitectónica, como un arquitecto de software o el equipo de diseño técnico. Sin embargo, es sano que todo el equipo participe dando información y revisando el contenido. Lo importante es que alguien asuma el cierre del documento para evitar que quede incompleto.

¿Dónde se almacenan los Architecture Decision Records?

La práctica más extendida es guardar los Architecture Decision Records dentro del propio repositorio del proyecto, en una carpeta específica como “/docs/adr” o similar. De esta forma, viajan junto con el código, se versionan con Git y se revisan como cualquier cambio técnico. También pueden publicarse en una wiki interna para facilitar su consulta diaria.

¿Se puede modificar un ADR después de aprobado?

Sí se puede, pero conviene hacerlo con cuidado. Lo habitual es que, si la decisión cambia de forma importante, se cree un nuevo ADR que indique que reemplaza al anterior. De este modo se conserva el historial. Para correcciones menores, como errores tipográficos o aclaraciones, se puede actualizar el documento manteniendo la esencia de la decisión original.

¿Cuántos ADR debería tener un proyecto promedio?

No existe un número fijo válido para todos los proyectos. Un sistema pequeño puede funcionar bien con solo unos pocos Architecture Decision Records, centrados en decisiones clave de tecnología y seguridad. Proyectos grandes, con muchos equipos y módulos, suelen acumular decenas de ADR a lo largo de los años. Lo importante es crear uno cada vez que haya una decisión con impacto arquitectónico sostenido.

¿Cómo numerar y organizar los ADR del proyecto?

Una forma sencilla es asignar un identificador incremental, como ADR-001, ADR-002, etcétera, en el orden en que se van creando. Estos archivos se guardan en una carpeta común y, a menudo, se mantiene un índice en forma de tabla en un README. También se pueden agrupar por dominios funcionales, pero siempre es clave que la numeración permita referirse a cada ADR sin ambigüedad.

¿Un Architecture Decision Record reemplaza otros documentos de arquitectura?

No, un Architecture Decision Record no reemplaza por completo otros documentos de arquitectura, sino que los complementa. Los ADR se enfocan en decisiones concretas, mientras que otros artefactos, como diagramas o descripciones de componentes, muestran la visión general del sistema. Juntos proporcionan una imagen más completa, tanto del diseño actual como de la lógica que llevó a ese diseño.

¿Cuánto tiempo lleva redactar un ADR útil?

Redactar un ADR útil no debería ser un proceso largo ni pesado. En muchos casos, con treinta o cuarenta minutos es suficiente para escribir el contexto, las opciones principales, la decisión y las consecuencias. Lo que más tiempo suele consumir no es escribir, sino discutir y acordar la decisión, algo que se haría igualmente aunque no existiera el Architecture Decision Record.

¿Es obligatorio seguir siempre la misma plantilla de ADR?

No es obligatorio, aunque resulta recomendable mantener cierta consistencia para facilitar la lectura. Un equipo puede comenzar con una plantilla simple e ir adaptándola según sus necesidades. Lo crucial es que cada Architecture Decision Record responda a unas preguntas básicas: cuál era el problema, qué se decidió, por qué se eligió esa opción y qué efectos se esperan.

¿Cómo saber si un ADR está bien redactado?

Una buena forma de comprobarlo es pedir a alguien que no haya participado en la decisión que lea el documento y explique con sus palabras qué se decidió y por qué. Si lo entiende sin necesidad de aclaraciones adicionales, el ADR está bien redactado. Además, debe poder leerse en poco tiempo y dejar clara la relación entre contexto, decisión y consecuencias futuras.

Conclusión

Un Architecture Decision Record permite que tú tengas siempre a mano el mapa de decisiones que han dado forma al sistema. No se trata de generar más burocracia, sino de capturar la lógica detrás de cambios que marcarán el futuro del proyecto.

Si empiezas a documentar las decisiones clave con ADR, pronto notarás menos discusiones repetidas, más claridad al incorporar gente nueva y una arquitectura más coherente. Cada registro se convierte en una pieza de contexto que te ahorra tiempo y frustraciones.

A partir de ahora, cada vez que tomes una decisión importante, puedes plantearte si merece un Architecture Decision Record. Si la respuesta es afirmativa, tendrás una herramienta sencilla para dejar constancia de tu razonamiento y seguir explorando otros contenidos del sitio que refuercen tus habilidades técnicas.

Sigue aprendiendo: