ADRs en equipos que usan IA: documentar decisiones para que el contexto no se pierda

Cuando un equipo usa IA para generar código, tomar decisiones de arquitectura o explorar alternativas, parte del razonamiento que llevó a una decisión ocurre en una conversación que desaparece. El código resultante existe; la discusión que lo justificó, no. Semanas después, nadie recuerda por qué se eligió esa estructura, ese proveedor o ese patrón.

Ese problema existía antes de la IA, pero se amplifica. Las decisiones que antes tomaba una persona en una reunión y quedaban registradas en una nota o en un Slack ahora ocurren en sesiones de chat con el modelo. Si no hay un proceso para capturar esas decisiones, el conocimiento se pierde más rápido.

El formato estándar de ADR (contexto, decisión, alternativas, consecuencias) sigue siendo válido. Lo que cambia es que vale la pena agregar dos campos adicionales: el rol que tuvo la IA en la decisión (exploración de alternativas, generación de código inicial, validación de enfoque) y las restricciones o instrucciones que se le dieron al modelo (qué estaba fuera de scope, qué tradeoffs se priorizaron).

Esos dos campos no son ceremoniales. Cuando alguien revise la decisión en tres meses, saber que "el modelo propuso cinco alternativas y se eligió esta por X y Y" es diferente a saber que "el equipo eligió esto". El proceso importa para juzgar si la decisión sigue siendo correcta o si fue resultado de las limitaciones del contexto del momento.

La regla de cuándo escribir un ADR no cambia con IA: cuando la decisión tiene impacto duradero, cuando revertirla sería costoso o cuando otro desarrollador la cuestionaría en tres meses. Lo que sí cambia es la frecuencia con la que esas decisiones se toman. Con IA como copiloto, el equipo puede explorar y comprometerse con un enfoque en minutos en lugar de horas. Eso aumenta la cantidad de decisiones por sprint, no la reduce.

Una heurística práctica: si la sesión con el modelo produjo código que va a producción, vale la pena preguntarse si la dirección que tomó esa sesión merece un ADR. No todo lo generado requiere documentación, pero las decisiones estructurales sí.

Un beneficio adicional de los ADRs en equipos con IA es que se pueden incluir como contexto en futuros prompts. Si el ADR documenta que "se eligió Medusa porque necesitamos control total del checkout y no podemos depender de un SaaS", ese contexto en un prompt evita que el modelo proponga Shopify como alternativa en sesiones futuras.

Los ADRs bien escritos funcionan como memoria compartida entre el equipo y el modelo. Le dan al modelo el contexto que de otra forma tendría que reconstruir desde el código, y al equipo le dan un registro de por qué el código tiene la forma que tiene.