ADR. Lo que el código no recuerda

Usar los ADR (Architecture Decision Record) en los proyectos no es nada nuevo. Dicho rápido y pronto, es anotar las decisiones de arquitectura: el contexto, los motivos que las rodean y el porqué de cada decisión.

Lo inventó Michael Nygard en 2011, y sus principios son pocos pero tercos: una decisión por documento, numeradas y versionadas junto al código, y lo más importante, no se editan. Cuando cambias de idea no reescribes la vieja: redactas una nueva que la reemplaza.

Pero el valor del ADR para mí está en su uso con la IA. Normalmente cuando interactuamos con la IA usamos ficheros de contexto, CLAUDE.md o AGENTS.md o documentación del proyecto directamente. Y por supuesto está el código. Pero todo eso captura el estado actual del proyecto, no el porqué de cómo llegó hasta él; y ese porqué es justo el hueco que un ADR llena y lo demás deja vacío.

Es decir, el fichero de contexto dice qué y cómo. Es una foto del presente: “usamos esto, las reglas son estas, los botones son naranjas”. Cuando cambio de opinión, lo sobrescribo. Y al sobrescribirlo, el porqué anterior desaparece. No tiene memoria del camino que no tomé. El código te enseña lo que es y el fichero de contexto, lo que es ahora.

En cambio el ADR dice por qué y contra qué. Registra qué alternativas pensé, cuáles descarté y a cambio de qué. No se sobrescribe: se acumula. Y esa acumulación le da a la IA (y a mí) mucho más contexto para cualquier decisión nueva.

Lo que hace que esto realmente escale en lugar de convertirse en un puñado de notas viejas es que un ADR nunca se borra; cambia de estado. Nace con un propuesto, pasa a aceptado, y más tarde o bien se reemplaza por otro, con un enlace explícito al que lo sustituye, o bien se cierra con su resolución escrita. La gracia es lo que pasa cuando la IA lee uno antiguo: el estado le dice al instante si sigue vivo o es historia, y el enlace “reemplazado por #024” le hace seguir la cadena hasta la decisión vigente.

En la práctica todo esto vive en un único fichero que ya pasa de los 70 ADR y las 2.000 líneas. El índice de estados del principio no lo mantengo a mano: lo genera un script a partir del estado que declara cada ADR, así nunca dice que algo sigue vigente cuando en realidad lo reemplacé hace meses.

¿Cómo lo uso?

Personalmente he relegado gran parte de la programación a una IA, y mi labor es más de toma de decisiones, de producto, arquitectura, infraestructura y herramientas, que el escribir código. Ahora reviso y audito los cambios y hago cambios puntuales.

Entonces mi proceso actualmente es en primer lugar, el ejercicio de pensar. Mi rutina es plantear la situación y abrir un debate: ¿de qué maneras se puede hacer?, ¿cuáles encajan mejor con lo que ya hay?, ¿se puede unificar?, ¿sigue buenas prácticas?, ¿qué hace la comunidad?, ¿lo que propongo ahora es compatible con los siguientes pasos? Es una conversación contra la IA y contra mí mismo, y eso solo ya enriquece la decisión. Lo que sale de ahí se plasma en un ADR, y sobre él trazo un Plan y lo ejecuto.

Y no todo nace de un debate sino también del uso. A veces el ADR llega después de un bug o una traza de Langfuse que me enseña algo. Lo que documento es la decisión que tomo a raíz de eso.

Un ejemplo

ADR-01 — Estrategia de modelos soberana

Contexto: Existe la tentación de usar modelos frontier externos (Gemini, GPT-4) para compensar las limitaciones de los modelos locales en los pasos cognitivos.

Decisión: Todos los modelos del pipeline corren en local. Sin API keys externas en el camino crítico.

Por qué no la alternativa obvia (la estrategia híbrida): el Generator maneja el historial conversacional completo, que es información personal por definición. Cuanta más capacidad necesita un paso, más contexto personal maneja —y menos seguro es externalizarlo—. La paradoja invalida el híbrido: justo en los pasos donde más útil sería el frontier, es donde más información personal se le entregaría.

Todos siguen el mismo molde: contexto, decisión, por qué no la alternativa obvia, y consecuencias.

¿Qué me aporta?

Como decía, lo más importante para mí es el ejercicio de pensar. Pero también noto que la IA tiene más contexto en sus respuestas y propone mejores soluciones. A medida que avanza el proyecto me ayuda a recordar decisiones pasadas y, sobre todo, a no caer en sesgos anteriores y soluciones que descarté.

Por otra parte, esto es un proyecto de ratos libres, no va en línea recta, no hay fases y objetivos a cumplir obligatoriamente. Acabo avanzando en lo que me apetece en ese momento y tengo muchos frentes abiertos. Por ejemplo un día trabajo en una característica del SPA, otro día juego con varios LLM, con síntesis y clonado de voz, con infraestructura propia, pruebo herramientas y además está Sama, que apunta a ser un RAG.

Ahí el ADR también me ayuda a volver al punto en el que estaba y a retomar lo pendiente, sin reconstruirlo de memoria. Y me ayuda a mantener la coherencia: cada pocas semanas hago una auditoría completa del proyecto, y uno de los pasos es revisar los ADR para asegurarme de que no se contradicen entre sí. Muchas veces ahí me toca volver al código, actualizar el estado de un ADR o enlazar otro, y así el proyecto crece de forma orgánica, sin perder el hilo de por qué es como es.