La mayoría de los handoffs de arquitectura que vemos terminan así: una presentación con diagramas, una página de Notion con bullets, y una junta donde alguien explica el “por qué” de viva voz. Tres meses después, el equipo está reconstruyendo la mitad porque nadie se acuerda de por qué se tomó una decisión clave.
Esto es lo que los Architecture Decision Records — ADRs — existen para evitar.
Qué es realmente un ADR
Un ADR es un documento corto, normalmente de una página, que captura una sola decisión arquitectónica. El formato varía, pero la versión útil siempre incluye cuatro partes:
- Contexto. ¿Qué problema estamos resolviendo? ¿Qué restricciones son reales?
- Decisión. ¿Qué decidimos?
- Consecuencias. ¿A qué nos compromete esto? ¿Qué cedimos?
- Estado. Propuesto, aceptado, deprecado, reemplazado por ADR-XXX.
Eso es todo. Rara vez el documento completo pasa de una página. La disciplina no está en el formato — está en escribirlo antes de que todos olviden los trade-offs.
Por qué las consultoras los omiten
Tres razones, más o menos en este orden:
Toma tiempo escribirlos. Un ADR de verdad — uno que capture el razonamiento real, no una versión sanitizada — toma 30 a 60 minutos por decisión. En un engagement de 12 semanas con 8 a 12 decisiones relevantes, eso es un día de trabajo. La mayoría de las consultoras no incluye ese día en sus estimaciones.
Hacen que el consultor sea reemplazable. Esta es la incómoda. Una arquitectura bien documentada es una que otro equipo puede tomar y extender. Si tu ventaja competitiva es ser la única persona que sabe por qué las cosas funcionan como funcionan, los ADRs amenazan eso.
Muestran tu razonamiento. Algunas decisiones se ven obvias en retrospectiva pero eran inciertas en su momento. Los ADRs preservan esa incertidumbre — las alternativas consideradas, los trade-offs aceptados. Esa transparencia incomoda a algunas consultoras.
Qué le cuesta al cliente
Un cliente que no recibe ADRs de su engagement de arquitectura está comprando un sistema que puede operar pero no evolucionar. De tres a seis meses después, cuando el equipo enfrenta su primera bifurcación real — una nueva integración, un problema de escala, un cambio regulatorio — está volando a ciegas en cada decisión que el arquitecto original tomó.
Lo que termina pasando:
- Alguien “descubre” por qué se tomó una decisión rompiendo algo.
- El equipo empieza desde cero partes de la arquitectura porque no puede verificar si la lógica original sigue aplicando.
- Se contrata a una segunda consultora para re-documentar lo que la primera entregó.
Cada una de estas cosas es cara. Ninguna aparece en el line item del engagement original.
Cómo usamos ADRs en Kor-E
Cada engagement de arquitectura que entregamos viene con un log de ADRs. El formato es el de cuatro partes de arriba. Los escribimos sobre la marcha — normalmente en la misma sesión donde se tomó la decisión, mientras el razonamiento sigue fresco.
Los committeamos al repo del cliente, no al nuestro. Son del cliente. Hemos tenido engagements donde el siguiente ingeniero del cliente llegó seis meses después de que nosotros nos fuimos y construyó un feature correctamente al primer intento porque leyó el ADR de la decisión que estaba extendiendo.
Ese es el punto entero.