ADRs: memoria para humanos y contexto para agentes

Hace ya unos años, durante mi etapa en Santander Bank, empezamos a utilizar los Architecture Decision Records (ADR) para dejar constancia de determinadas decisiones arquitectónicas: qué se había decidido, qué alternativas se habían considerado y, sobre todo, en qué contexto se había tomado aquella decisión.

Al principio reconozco que me parecía algo bastante tedioso. Cuando estás metido en el día a día de un proyecto, muchas de esas razones parecen obvias y documentarlas se siente como trabajo adicional, sobre todo si los squads no son excesivamente grandes. Hay cierta sensación de estar explicándole al futuro algo que hoy conoce todo el mundo.

Con el tiempo, sin embargo, empecé a apreciar mucho más su utilidad.

Los equipos cambian, las personas se van y el contexto se diluye bastante más rápido de lo que pensamos. Decisiones que meses o años después parecen extrañas, innecesariamente complejas o directamente malas tenían bastante sentido con las restricciones, la información y los plazos que existían en aquel momento.

Y obviamente la historia de git no es siempre la mejor fuente para reconstruir todo eso :P

El código permite ver qué cambió y, con algo de suerte, quién lo cambió. Pero rara vez cuenta bien por qué se descartó otra tecnología, por qué se decidió separar dos dominios o qué problema había detrás de una solución que ahora parece sobredimensionada.

Lo que me empezó a gustar más es que los ADR eran especialmente útiles también con las malas decisiones. No para justificarlas ni para decir aquello de «en aquel momento era lo correcto», sino para entenderlas. Hay una diferencia importante entre heredar una decisión absurda y descubrir que fue una apuesta razonable que salió mal o que dejó de tener sentido cuando cambió el contexto.

Últimamente he vuelto a pensar bastante en aquello a raíz del spec-driven development (SDD) y de toda esta locura de desarrollar software con cada vez más agentes involucrados.

Las specs pueden recoger mucha más información que simplemente qué queremos construir. Pueden describir comportamientos, restricciones, casos límite, criterios de aceptación e incluso parte de la intención del cambio. Pero me parece que sigue existiendo un riesgo: a medida que delegamos más parte de la implementación, podemos perder parte de la historia de por qué el sistema ha ido tomando una determinada forma.

Porque detrás de una arquitectura hay decisiones que sobreviven a muchas specs. Tecnologías que se evaluaron y se descartaron. Fronteras que se establecieron deliberadamente. Deuda técnica que se aceptó sabiendo que era deuda. Soluciones que ya se probaron y no funcionaron. Incluso decisiones que nacieron de una conversación difícil, de una incidencia importante o de una noche en la que algo se rompió y alguien tuvo que arreglarlo.

Todo eso forma parte del sistema aunque no aparezca en el código.

Por eso creo que los ADR pueden adquirir una nueva utilidad en estos flujos. No solo como registro histórico para las personas, sino como parte del contexto que utilizan también los agentes. Una especie de memoria arquitectónica compartida que explique no únicamente cómo es el sistema, sino por qué hemos querido que sea así.

Una posible forma de hacerlo sería que, antes de implementar un cambio, el agente identificase los ADR relevantes para esa parte del sistema. Si la nueva implementación entra en conflicto con alguno de ellos, el proceso debería obligarnos a parar y revisar si aquella decisión sigue teniendo sentido. Y si las condiciones han cambiado, registrar una nueva decisión que sustituya a la anterior, en vez de ir erosionándola silenciosamente cambio tras cambio.

Pero el ADR por sí solo tampoco debería convertirse en una falsa garantía. Puede dar contexto y marcar los límites, mientras que los tests, las políticas y la integración continua son quienes realmente los hacen cumplir. La spec define la intención, el ADR conserva el razonamiento y las herramientas de validación evitan que nos salgamos de esos guardrails sin darnos cuenta.

De esa forma, el ADR deja de ser solamente memoria sobre por qué tomamos una decisión. Se convierte también en un puente entre esa decisión y los límites dentro de los cuales queremos que humanos y agentes sigan evolucionando el sistema.

Supongo que hay algo bastante humano en todo esto. Construimos sistemas durante años y, casi sin darnos cuenta, vamos dejando en ellos una parte de nuestras dudas, nuestros aciertos y también nuestros errores. Cuando desaparece el contexto, solo queda el resultado, y a veces juzgar el resultado sin conocer el camino es demasiado fácil.

Cuanto más sencillo sea generar y modificar software, más importante me parece que será conservar no solo el código y las especificaciones, sino también el razonamiento que ha llevado al sistema hasta donde está.

Quizá los ADR siempre fueron memoria. La diferencia es que ahora no solo necesitamos que puedan leerla las personas.