Qué es un ADR y por qué lo uso en proyectos pequeños

La primera vez que oí hablar de un ADR pensé que era otro proceso pensado para equipos grandes con reuniones de arquitectura y aprobaciones formales. Nada más lejos de lo que necesito en mis proyectos, que casi siempre desarrollo yo solo o con una persona más. Meses después, un ADR es de las pocas prácticas de "proceso" que mantengo incluso cuando voy con prisa, porque el coste de escribirlo es mínimo y el ahorro cuando vuelvo al código tres meses después es real.

Qué es exactamente un ADR

ADR son las siglas de Architecture Decision Record, un registro de decisión de arquitectura. En la práctica es un archivo de texto corto, normalmente Markdown, que responde a cuatro preguntas sobre una decisión técnica concreta:

Qué problema o contexto motivó la decisión.
Qué opciones se consideraron.
Qué se decidió finalmente.
Qué consecuencias, buenas y malas, trae esa decisión.

No es un documento de diseño completo ni un diagrama de arquitectura. Es más parecido a una nota de por qué, escrita en el momento en que la decisión todavía está fresca en tu cabeza, para que dentro de seis meses no tengas que reconstruir el razonamiento desde cero mirando solo el código.

Por qué me sirve incluso trabajando solo

Se podría pensar que un ADR tiene sentido cuando hay que convencer a otras personas del equipo o dejar constancia para una auditoría. Trabajando solo en un proyecto, mi "yo del futuro" es exactamente ese público. He vuelto a código que escribí yo mismo hace pocos meses y me he preguntado por qué elegí una solución que a primera vista parece más complicada de lo necesario. Sin un ADR, la respuesta honesta muchas veces es "no me acuerdo", y entonces existe el riesgo real de deshacer una decisión que en su momento evitaba un problema concreto.

Un ejemplo real: en el proyecto de la app de pesca (Caladero, que sigo desarrollando) tuve que decidir si los puntos guardados por un usuario se almacenaban con coordenadas exactas o con una coordenada redondeada a menos precisión por defecto. Escribí un ADR corto explicando que la decisión era guardar la coordenada exacta localmente, pero mostrar por defecto una versión con precisión reducida en cualquier vista compartida, para evitar exponer la ubicación exacta de un punto de pesca privado sin que el usuario lo decidiera explícitamente. Sin ese documento, cualquier cambio futuro en la lógica de guardado correría el riesgo de romper esa garantía de privacidad sin que nadie se diera cuenta de que existía.

Cómo escribo un ADR en la práctica

Uso una plantilla muy simple, casi siempre el mismo esqueleto:

# ADR 003: Precisión de coordenadas en puntos guardados

## Contexto
Los usuarios guardan puntos de pesca que consideran privados.
Necesitamos decidir qué precisión de coordenada se almacena y
qué precisión se expone en cualquier funcionalidad futura de
compartir o exportar.

## Opciones consideradas
1. Guardar y mostrar siempre la coordenada exacta.
2. Redondear la coordenada al guardar (pérdida de precisión permanente).
3. Guardar exacta, pero reducir precisión en cualquier vista o
   exportación que no sea el propio dispositivo del usuario.

## Decisión
Opción 3: se guarda la coordenada exacta localmente. Cualquier
funcionalidad de exportación o compartición debe aplicar un
redondeo explícito antes de mostrar el dato fuera del dispositivo.

## Consecuencias
- El usuario mantiene el valor exacto para su propio uso.
- Cualquier nueva funcionalidad de compartir debe implementar el
  redondeo; se documenta aquí para que no se olvide en el futuro.
- Si se necesita compartir con precisión exacta, requiere una
  decisión explícita del usuario, no un comportamiento por defecto.

Guardo estos archivos en una carpeta docs/adr/ dentro del propio repositorio, numerados en orden. No uso ninguna herramienta especial, ni plantillas complejas de doce secciones. Cuanto más ligero es el proceso, más probable es que lo mantenga cuando tengo prisa, que es precisamente cuando más falta hace.

Cuándo escribo uno y cuándo no

No documento cada decisión que tomo, porque eso convertiría el proceso en una carga en vez de una ayuda. Escribo un ADR cuando se cumple al menos una de estas condiciones:

La decisión afecta a privacidad o seguridad de datos de usuarios.
Descarté una opción que "parece" más obvia y alguien (incluido yo mismo) podría preguntarse por qué no la usé.
La decisión es cara de revertir más adelante, como elegir un formato de almacenamiento o una librería de mapas.
Tuve que investigar bastante para llegar a la conclusión, y no quiero repetir esa investigación si vuelvo a dudarlo.

Cosas que no necesitan un ADR: el nombre de una variable, el color de un botón, o decisiones que son triviales de cambiar sin coste, como el tamaño de una caché en memoria.

Errores y límites de esta práctica

El error más común que cometí al principio fue escribir ADRs demasiado largos, casi como ensayos, lo que hacía que los pospusiera para "cuando tuviera tiempo" y al final no se escribían nunca. Reducir la plantilla a cuatro secciones cortas resolvió ese problema.

Otro límite real: un ADR no sustituye a las pruebas ni a la documentación de código. Explica el "por qué" de una decisión, no el "cómo" funciona el código en detalle; para eso siguen haciendo falta comentarios puntuales y tests. Tampoco es un contrato inmutable. Si el contexto cambia, se escribe un nuevo ADR que referencia y sustituye al anterior, en vez de borrar el historial de decisiones pasadas. Esa trazabilidad es precisamente lo que da valor al conjunto de documentos con el tiempo, no cada archivo aislado.

También he aprendido a no usarlo como excusa para posponer una decisión. Un ADR se escribe después de decidir, con la decisión ya tomada, no como sustituto de pensar el problema.

Conclusión