Architecture Decision Records: documentar no solo el qué, sino el porqué

En todo proyecto de software se toman cientos de decisiones. Algunas son pequeñas: cómo nombrar una variable, qué librería usar para formatear fechas. Otras son estructurales: qué framework adoptar, cómo modelar el dominio, qué estilo arquitectónico seguir, cómo integrar servicios, dónde poner la lógica de negocio.

Las decisiones pequeñas se olvidan sin mayor consecuencia. Las grandes, si no se documentan, generan algo peor: se convierten en supuestos implícitos que nadie cuestionó ni puede explicar.

¿Por qué el sistema usa un bus de eventos en lugar de llamadas directas? ¿Por qué hay una capa de anticorrupción entre estos dos módulos? ¿Por qué la autenticación no usa la librería estándar del framework? Si nadie escribió la respuesta, el equipo eventualmente revisita la decisión desde cero, sin contexto, y muchas veces llega a la misma conclusión… solo que tardó tres sprints más en hacerlo.

Los Architecture Decision Records (ADRs) son una respuesta práctica a ese problema.

Qué es un Architecture Decision Record

Un ADR es un documento breve que captura una decisión arquitectónica significativa: el contexto que llevó a tomarla, la decisión en sí y las consecuencias que implica.

No es documentación pesada. No es un documento de diseño de 30 páginas. Es una nota estructurada que responde a preguntas simples:

¿Qué estábamos evaluando?
¿Qué decidimos?
¿Por qué?
¿Qué descartamos y por qué?
¿Qué implicaciones tiene esta decisión?

El formato más conocido, propuesto por Michael Nygard, incluye:

Campo	Contenido
Título	Nombre descriptivo de la decisión
Estado	Propuesto, Aceptado, Reemplazado, Deprecado
Contexto	El problema o situación que generó la decisión
Decisión	Qué se decidió hacer
Consecuencias	Qué implica esta decisión (beneficios y compromisos)
Alternativas	Qué se consideró y descartó

Un buen ADR puede caber en una página. Si necesitas veinte páginas, probablemente es un documento de diseño, no un ADR.

Por qué son importantes

La arquitectura de un sistema no solo vive en sus diagramas ni en su código. Vive también en las decisiones que lo formaron.

Cuando alguien nuevo llega al equipo y lee el código, puede ver qué hace el sistema. Pero no puede ver por qué está estructurado así. ¿Por qué hay tres módulos separados cuando podrían ser uno? ¿Por qué este servicio no llama directamente al otro? ¿Por qué la base de datos principal es PostgreSQL y no MongoDB, si el modelo de datos parece más documental?

Sin ADRs, esas respuestas están dispersas en tickets de Jira, mensajes de Slack, pull requests antiguos o en la cabeza de quien tomó la decisión hace dos años y ya no está en el equipo.

Los ADRs ayudan a:

Preservar el contexto: No solo la decisión, sino el razonamiento detrás de ella.
Evitar discusiones repetidas: Si algo ya fue evaluado y descartado, el ADR lo registra.
Mejorar el onboarding: Una persona nueva puede leer los ADRs y entender por qué el sistema es como es.
Soportar decisiones de evolución: Cuando quieres cambiar algo, entender la decisión original te ayuda a evaluar si las condiciones siguen siendo las mismas.
Gobierno arquitectónico: En organizaciones con múltiples equipos, los ADRs pueden funcionar como una forma de alinear criterios y evitar fragmentación tecnológica.

Una arquitectura sin historial de decisiones es una arquitectura que eventualmente alguien va a desmantelar sin entender lo que está rompiendo.

Ejemplos de uso en la industria

Los ADRs son más útiles cuando las decisiones tienen impacto a largo plazo y no son obvias por sí solas. Algunos ejemplos realistas:

Adoptar arquitectura hexagonal

Contexto: El dominio de negocio estaba acoplado directamente a la capa HTTP y a la base de datos. Decisión: Separar el modelo de dominio de los adaptadores de entrada y salida usando arquitectura hexagonal. Consecuencias: Mayor claridad del modelo, más facilidad para testear, pero mayor complejidad inicial de estructura.

Usar PostgreSQL como base de datos principal

Se evaluó PostgreSQL vs. MongoDB para un sistema de órdenes con reportes complejos. Se eligió PostgreSQL por soporte transaccional maduro y capacidades de consulta avanzadas. El modelo documental de MongoDB no justificaba perder las garantías ACID.

Integrar bounded contexts por eventos

Se decidió no usar llamadas síncronas entre contextos de dominio. Los contextos se comunican exclusivamente por eventos publicados en un broker. Esto desacopla los ciclos de vida de los servicios pero requiere diseño cuidadoso de consistencia eventual.

Estrategia de versionado de APIs

Se decide versionar APIs con prefijo de versión en el path (/api/v1/...). Las versiones anteriores se soportan durante 6 meses tras publicar una nueva. Se descarta versionado por header por complejidad operacional.

Incorporar pruebas de arquitectura con ArchUnit

El equipo decidió escribir tests con ArchUnit para validar que el código respeta las restricciones de la arquitectura hexagonal: que el dominio no importa infraestructura, que los adaptadores no acceden directamente entre sí, etc.

Equipos en fintechs, plataformas SaaS, sistemas distribuidos, productos B2B con ciclos largos de vida y organizaciones que tienen más de un equipo trabajando en el mismo sistema suelen beneficiarse especialmente de esta práctica.

Ventajas de usar ADRs

Documentación viva cerca del código: Si los ADRs viven en el repositorio, se versionan junto con el código y se pueden revisar con git log.
Claridad y trazabilidad: Se puede reconstruir cómo llegó el sistema a su estado actual.
Reducción de ambigüedad: Cuando hay dudas sobre una decisión, hay un lugar donde buscar.
Mejor comunicación entre equipos: Un ADR puede compartirse con otros equipos antes de tomar una decisión, facilitando la revisión distribuida.
Soporte para auditorías técnicas: Cuando hay que justificar decisiones a stakeholders técnicos o de negocio, los ADRs son evidencia documentada.
Onboarding más rápido: Las personas nuevas entienden no solo el qué, sino el por qué.
Base para evolución consciente: Cuando cambia el contexto, es más fácil evaluar si la decisión original sigue siendo válida.

Desventajas y riesgos

Los ADRs no son una solución mágica. Pueden fallar de varias formas:

Burocracia disfrazada: Si el equipo los adopta como checklist obligatorio sin criterio, se convierten en una tarea más sin valor real.
Escritos demasiado tarde: Un ADR escrito seis meses después de la decisión es una reconstrucción, no un registro. Pierde el contexto real.
Desactualización silenciosa: Un ADR que ya no refleja la realidad del sistema confunde más que ayuda.
Documentar lo trivial: No toda decisión merece un ADR. Elegir el nombre de una variable no es una decisión arquitectónica.
Sustituto de conversaciones reales: Un ADR no reemplaza la discusión. La complementa. Si el equipo empieza a escribir ADRs en lugar de conversar, algo está mal.
Sin criterio de cuándo aplica: Sin acuerdo sobre qué tipo de decisiones merecen un ADR, el resultado es inconsistente.

El problema, cuando los ADRs no funcionan, casi nunca es la práctica en sí. Es la falta de disciplina o de criterio en su aplicación.

Buenas prácticas

Algunas recomendaciones para que los ADRs sean útiles de verdad:

Escríbelos cerca del momento de la decisión, no meses después.
Guárdalos en el repositorio, en una carpeta /docs/adr/ o /architecture/decisions/.
Usa un formato simple y consistente. No necesitas reinventar el formato de Nygard, pero sí aplicarlo de manera coherente en todo el proyecto.
Nombra los archivos con un número secuencial: 0001-usar-arquitectura-hexagonal.md, 0002-base-de-datos-postgresql.md.
Usa estados explícitos: Propuesto, Aceptado, Reemplazado por ADR-0005, Deprecado.
Enlázalos desde el README o la guía de arquitectura del proyecto.
No busques perfección, busca claridad. Un ADR incompleto que captura el contexto real es mejor que un documento perfectamente formateado que nadie lee.
Establece un umbral claro: Documenta solo decisiones que sean difíciles de revertir, que afecten a varios equipos o módulos, o que alguien podría cuestionar en el futuro.

ADRs en una biblioteca de programación funcional

Recientemente incorporé ADRs en dmx-fun, mi biblioteca de programación funcional para Java. Fue una decisión natural: conforme la biblioteca fue creciendo, los cambios dejaron de ser obvios.

Las decisiones sobre por qué ciertos módulos están separados del core, por qué se diseñó Result<T> de una forma específica, cómo se maneja la compatibilidad con versiones modernas de Java, o qué dependencias externas se admiten y cuáles no, empezaron a necesitar registro. Publicar código es una parte del trabajo. La otra es dejar rastro de las decisiones que definen el diseño de ese código.

Los ADRs de dmx-fun están disponibles en https://domix.github.io/dmx-fun/adr/. Si estás explorando la biblioteca o quieres entender por qué ciertos tipos y módulos existen de la forma en que existen, ese es el lugar indicado.

ADRs y arquitectura moderna

Este es precisamente uno de los temas que me gusta trabajar en el curso de Arquitectura Moderna con Java. Los ADRs no son un tema aislado: forman parte de una mentalidad más amplia sobre cómo construir software de manera deliberada y sostenible.

En ese contexto, los ADRs se conectan con prácticas como arquitectura hexagonal (cuyas restricciones merecen un ADR), diseño modular (cuyas fronteras requieren justificación), calidad arquitectónica (que incluye trazabilidad de decisiones) y evolución sostenible del software (que depende de entender por qué el sistema llegó a donde está).

Documentar bien no es documentar mucho. Es documentar lo que importa, cuando importa.

Conclusión

La arquitectura de software no se reduce a diagramas, patrones o tecnologías. También es el conjunto de decisiones que llevaron al sistema a ser lo que es.

Los ADRs son una herramienta simple para capturar esas decisiones. No requieren herramientas especiales, no generan overhead significativo si se usan con criterio, y su impacto positivo se nota especialmente cuando el equipo crece, el sistema evoluciona o llega alguien nuevo que necesita entender el contexto.

He visto cómo los proyectos sin historial de decisiones generan deuda técnica de conocimiento: alguien refactoriza algo que existía por una razón, se vuelve a debatir lo que ya fue debatido, se rompe algo que parecía arbitrario pero era una restricción deliberada.

Documentar decisiones no es burocracia. Es respeto por las personas que van a mantener ese sistema mañana, incluyendo tu yo del futuro.

El código muestra qué hicimos. Un ADR explica por qué decidimos hacerlo así.