ADRs que mantienen sano un sistema

Un ADR sirve cuando el equipo necesita recordar por qué eligió una dirección técnica y qué costos aceptó al hacerlo. No reemplaza README, onboarding ni docs de APIs. Su trabajo es capturar una decisión arquitectónica antes de que se vuelva folklore.

Si meses después alguien pregunta “¿por qué seguimos usando jobs asíncronos para este flujo?” o “¿por qué separamos billing de identity?”, un ADR bueno evita reabrir toda la discusión desde cero.

Los mejores ADRs son cortos y específicos. Describen contexto, decisión, alternativas consideradas y consecuencias. Eso basta para que otra persona entienda el problema original y evalúe si la decisión sigue siendo correcta.

Un ADR falla cuando intenta documentar todo el sistema o cuando declara una solución sin explicar qué dolor estaba resolviendo. Sin contexto, la decisión parece arbitraria. Sin consecuencias, parece gratis.

No todo merece un ADR. Un cambio menor de librería o una refactorización local rara vez lo necesita. En cambio, sí conviene escribir uno cuando la decisión afecta estructura, dependencias relevantes, límites entre módulos, persistencia, integración externa o forma de operar el sistema.

La regla simple es esta: si es una decisión que otra persona probablemente cuestionará en tres meses, o si revertirla será costoso, vale la pena dejarla registrada.

Bien usados, los ADRs aceleran. Reducen debates repetidos, hacen visibles los tradeoffs y ayudan a que el código no sea la única fuente de verdad sobre decisiones estructurales. También mejoran el onboarding: una persona nueva puede entender qué es intencional y qué solo es deuda heredada.

La meta no es escribir por escribir. La meta es darle memoria al sistema para que evolucionar no signifique discutir el mismo problema cada trimestre.