Un ADR (Architecture Decision Record) es un archivo de texto que responde una sola pregunta: por qué tomamos esta decisión y no otra. Llevo usándolos en todos mis proyectos y cambio la forma en que trabajo.
Cada proyecto tiene decisiones que parecen obvias en el momento y meses después no recorda por qué se tomaron. Un ADR resuelve exactamente ese problema.
Un Architecture Decision Record es un documento corto — típicamente entre 20 y 50 líneas — que captura una decisión arquitectónica importante: qué se decidió, por qué, cuáles eran las alternativas y cuáles son las consecuencias esperadas.
La regla que uso: si la decisión afecta la arquitectura del sistema, va un ADR antes de escribir código. Esto incluye: elección de stack, estructura de base de datos, método de autenticación, estrategia de deployment y cualquier librería de terceros que sea difícil de reemplazar.
El ADR no bloquea el trabajo — lo clarifica. En 20 minutos de escritura ahorras horas de confusion futura.
En el repositorio del proyecto, dentro de una carpeta /docs/ADRs/. Están versionados junto al código, entonces cualquier persona que entre al proyecto entiende las decisiones solo con git log.