ADRs: Mejores prácticas para documentar decisiones arquitectónicas

Sergio Vergara -

Ya sea elegir entre usar CQRS o Event Sourcing, adoptar GitFlow o decidir cómo estructurar las capas de una API, estas decisiones influyen directamente en la evolución, mantenibilidad y escalabilidad del producto.

Ahí es donde entran los ADR (Architecture Decision Records): un mecanismo ligero pero poderoso para documentar, justificar y comunicar decisiones técnicas clave.

¿Qué es un ADR?

Un ADR es un documento que registra una decisión importante relacionada con la arquitectura de un sistema. Describe qué se decidió, por qué se tomó esa decisión, qué alternativas se consideraron y qué implicaciones conlleva.

Este enfoque promueve la transparencia, evita debates repetidos y actúa como una fuente de verdad compartida para todo el equipo.

¿Por qué usar ADRs?

Durante un proyecto, es común enfrentarse a decisiones críticas que requieren tiempo, análisis y consenso. Sin una buena documentación de esas decisiones:

  • Se pierde el contexto histórico de por qué se eligió una opción.
  • Se repiten discusiones ya cerradas.
  • Nuevos miembros del equipo carecen de información clave.

Además, sin una estructura adecuada, aparecen tres anti-patrones comunes:

  1. No se toma ninguna decisión, por miedo a equivocarse.
  2. Se decide sin justificar, lo que lleva a confusión.
  3. No se documenta la decisión, haciendo que el conocimiento se pierda.

Mejores prácticas para implementar ADRs en tu organización

1. Mantén reuniones cortas y efectivas

Limita las reuniones de ADR a 30–45 minutos para mantener la atención y evitar desvíos. Usa formatos como readout meetings para comenzar con 10–15 minutos de lectura silenciosa antes de discutir.

2. Invita al equipo justo

Incluye perfiles clave de cada área afectada, pero evita reuniones con más de 10 personas. Lo ideal es un grupo ágil y diverso.

3. Una decisión por ADR

Cada ADR debe enfocarse en una única decisión. Si surgen varios temas, divídelos en documentos separados para mantener la claridad.

4. Separa diseño de decisión

Usa documentos de diseño para explorar opciones y alternativas. El ADR debe centrarse en la conclusión, enlazando con esos documentos como referencia.

5. Haz seguimiento y cierra el ciclo

Revisa los comentarios, responde dudas y busca consensos. El autor del ADR debe integrar el feedback del equipo, fomentando la colaboración y la responsabilidad compartida.

6. Decide en tiempo

No eternices el proceso: la mayoría de decisiones puede cerrarse en 1–3 sesiones. Muchas son reversibles y se pueden revisar más adelante.

7. Almacena los ADRs en un lugar común

Mantén los ADRs en un repositorio accesible para todo el equipo, como un directorio dentro del repo de código o una wiki técnica compartida.

8. Prioriza lo importante

Céntrate en decisiones de alto impacto arquitectónico, coste o riesgo. Usa un problema claro y contextualizado para marcar la urgencia de la decisión.

9. Evita retrasar lo crítico

Las decisiones que afectan el rumbo técnico no deben postergarse más allá de dos o tres sprints. Actuar con decisión evita bloqueos futuros.

10. Sé adaptable, no especulativo

Evita tomar decisiones basadas en un futuro incierto. Prioriza cualidades como observabilidad, escalabilidad progresiva y resiliencia, en lugar de suposiciones a largo plazo.

11. Decide con base real

Usa requisitos tangibles y experiencia directa. Deja de lado el sesgo de proveedor o sarcasmos, y reconoce tus propias limitaciones.

12. Cuida la redacción

Un ADR debe ser claro, conciso y bien escrito. Las decisiones simples pueden resumirse en pocas líneas; las complejas merecen una explicación detallada.

13. Divide decisiones complejas en etapas

A veces no es posible decidir todo de una vez. Divide el proceso en decisiones de corto, medio y largo plazo, y revísalas conforme el sistema evoluciona.

14. Indica el nivel de confianza

Sé transparente sobre el nivel de certeza de cada decisión. Algunos ADR pueden revisarse más adelante, otros se cierran como acuerdos finales entre stakeholders.

¿Dónde guardar los ADRs?

Te recomiendo seguir el estándar de adr.github.io o el enfoque sugerido por AWS Prescriptive Guidance.

Una estructura común en el repositorio podría ser:

/docs/adr/
├── 0001-uso-de-CQRS.md
├── 0002-alternativa-a-monolito.md
├── 0003-autenticacion-jwt-vs-sessions.md

Conclusión

Implementar ADRs no es una carga, es una inversión a largo plazo. Permite alinear al equipo, evitar errores repetidos y construir una base sólida para las decisiones que guiarán la evolución del producto.

Poder aplicar este enfoque como parte de nuestra cultura de desarrollo ágil, busca mejorar tu proceso técnico, revisar tu arquitectura o estructurar mejor las decisiones que afectan tu negocio digital.

Referencias:
· AWS Prescriptive Guidance – Architectural Decision Records
· ADR GitHub – Architecture Decision Records