Módulo 3: Comunicar la arquitectura

6. El ADR como comunicación: el porqué que viaja en el tiempo

Siguiente →

Descripción

Al terminar esta lección vas a usar el ADR (Architecture Decision Record) como lo que es en este módulo: una herramienta de comunicación, no un trámite. Los diagramas del C4 que dibujaste en las lecciones anteriores comunican muy bien el qué —qué piezas hay, cómo se conectan, cómo se ve el sistema hoy—, pero son completamente mudos sobre el por qué. Un diagrama de Container muestra que el checkout de Mercado es un servicio aparte; no dice por qué se separó, ni qué se consideró, ni qué se sacrificó para lograrlo. Y ese porqué es justo lo que necesita la persona que llega después: el dev que en dos años herede el checkout y piense "esto sería más simple junto con orders". El ADR es el porqué empaquetado para viajar en el tiempo hasta esa persona, que no estuvo en la sala cuando se decidió y no tiene a quién preguntarle.

Esto importa porque el conocimiento más caro de perder en un sistema no es cómo está construido —eso se lee del código y de los diagramas— sino por qué está construido así. El código te dice el estado final; no te dice qué alternativas se descartaron ni por qué motivo, ni qué restricción de negocio hoy olvidada forzó una decisión que parece rara. Sin ese porqué, cada decisión vieja se ve como un capricho o un error, y el equipo nuevo cae en dos trampas: o deshace decisiones buenas porque no entiende su motivo (y repite el dolor que resolvieron), o respeta decisiones malas por miedo a tocarlas ("debe haber una razón"). El ADR corta las dos: deja el porqué escrito donde alguien lo encuentre, de modo que las decisiones se puedan cuestionar con conocimiento en vez de por adivinanza.

Conexión con el módulo: en la lección 5 aprendiste a mostrar la foto del sistema al nivel correcto para cada audiencia. Aquí añades la pieza que la foto no captura: la historia de por qué la foto se ve así. Es la otra mitad de comunicar una arquitectura —el diagrama es el qué, el ADR es el porqué, y una comunicación completa necesita los dos—. Importa marcar la frontera desde ya: la mecánica del ADR —su estructura Context / Decision / Consequences / Status, cuándo escribirlo, cómo numerarlo, cuándo marcarlo superseded— se enseñó en la guía hermana architecture-decisions-and-tradeoffs. Aquí no re-explicamos esa mecánica: la usamos. La novedad de esta lección no es el formato del ADR (ya lo conoces), es su papel comunicativo: cómo un ADR bien escrito le habla a un lector futuro.

La nota que deja el dueño anterior

Imagina que te mudas a una casa vieja. Casi todo lo entiendes con solo mirar: dónde están las llaves de la luz, cómo se abre la ventana, para qué sirve cada cuarto —eso es el qué, y se lee de la casa misma, como el código se lee del repositorio—. Pero hay cosas que la casa, por más que la mires, no te explica. Por qué la puerta del garaje está tapiada. Por qué hay una tubería que da la vuelta larga en vez de ir derecho. Por qué el interruptor de la sala apaga también la luz del pasillo. Miras eso y piensa: "qué raro, el que vivió aquí no sabía lo que hacía; voy a arreglarlo".

Y entonces encuentras, pegada dentro de la caja de fusibles, una nota del dueño anterior: "La puerta del garaje la tapié porque daba a un terreno que se inunda; si la abres, se te mete el agua en cada tormenta. La tubería da la vuelta porque debajo del piso recto hay una viga estructural que no se puede perforar. El interruptor está unido a propósito: la instalación vieja no soportaba dos circuitos separados aquí." De golpe, lo que parecía incompetencia resulta ser decisiones informadas ante restricciones que tú no veías. La nota te ahorró tres errores caros: habrías destapiado el garaje y sufrido inundaciones, perforado la viga, y gastado en separar un circuito que no aguanta. El dueño anterior no está para explicártelo en persona —pero su porqué viajó en el tiempo hasta ti, en una nota.

Eso es un ADR. No documenta cómo es la casa (eso lo ves solo); documenta por qué tomó las decisiones que parecen raras, para que quien llegue después no las deshaga por ignorancia ni las respete por superstición, sino que las entienda. Un ADR es la nota que el arquitecto de hoy le pega a la caja de fusibles para el dev de dentro de dos años. Y como toda buena nota, su valor no está en el momento de escribirla —cuando todos saben el porqué—, sino mucho después, cuando el que sabía ya se fue y llega alguien que necesita entender.

Qué hace que un ADR comunique (y no solo archive)

El ADR tiene la misma trampa que toda la documentación de este módulo: se puede escribir para archivar (cumplir el trámite de "hay que documentar las decisiones") o para comunicar (que un humano futuro entienda). La estructura es la misma —la aprendiste en la guía de decisiones—; lo que cambia es cómo la llenas. Tres cosas separan el ADR que comunica del que solo ocupa espacio:

El Context cuenta la tensión, no el resultado. El ADR que archiva escribe "El checkout estaba acoplado". El que comunica escribe "El checkout vivía en orders pero payments lo tocaba en cada cambio: dos squads coordinando el flujo más crítico del negocio, el más lento de cambiar justo donde entra el dinero". La diferencia es que el segundo le hace sentir al lector futuro la presión que había —el dolor real que justificó moverse—. Sin esa tensión, la decisión parece arbitraria; con ella, parece inevitable.

Las Consequences incluyen lo que duele. El ADR que archiva lista solo los beneficios ("cambios más rápidos, mejor separación"). El que comunica escribe también el precio: "una llamada de red más en el camino crítico; migrar en vivo requiere un periodo de doble escritura". Esto es lo que de verdad ayuda al lector futuro, porque le dice qué se sabía y se aceptó a propósito. Cuando ese dev futuro note la latencia extra, el ADR le dirá "sí, lo sabíamos, fue el precio consciente de la separación" —y no perderá una semana investigando un "problema" que en realidad fue una decisión—.

El Status dice si todavía aplica. Un ADR marcado Accepted le dice al lector "esto sigue vigente". Uno marcado Superseded by ADR-021 le dice "esto ya cambió, ve al 021". Ese metadato es lo que evita que alguien tome una decisión vieja y revertida como si fuera la actual. El status es la fecha de caducidad de la nota.

Fíjate que ninguna de las tres es sobre el formato —todas son sobre escribir pensando en el lector que no estuvo ahí. Ese es el giro de la lección: el mismo ADR, llenado para comunicar, se vuelve la nota que salva a alguien de un error dentro de dos años.

Ejemplo trabajado: un ADR de Mercado, generado como pieza de comunicación

Vamos a producir el ADR de una decisión real de Mercado —extraer el checkout a su propio servicio, la que vimos nacer en el módulo 2— tratándolo como una pieza de comunicación. El siguiente código toma la decisión como datos estructurados (contexto, decisión, consecuencias, status) y la renderiza como un ADR legible. La idea es doble: mostrar cómo se ve un ADR que comunica, y dejar claro que un ADR es tan estructurado que hasta se puede generar desde datos —lo que lo hace fácil de versionar junto al código, como veremos en la lección 7—.

# Un ADR no es burocracia: es el PORQUE de una decision, empaquetado para viajar
# en el tiempo hasta quien llegue despues. Aqui lo GENERAMOS como pieza de
# comunicacion a partir de datos estructurados (la mecanica del ADR se enseno en
# la guia de architecture-decisions; aqui lo usamos para comunicar).

adr = {
    "id": "ADR-014",
    "title": "Extraer checkout a su propio servicio",
    "status": "Accepted",
    "date": "2026-03-10",
    "deciders": ["arquitecto", "lead de orders", "lead de payments"],
    "context": (
        "El modulo checkout vive en orders pero payments lo toca en cada cambio: "
        "es donde el pedido y el cobro se abrazan. Hoy dos squads deben coordinarse "
        "para cualquier ajuste, y el flujo mas critico del negocio (donde entra el "
        "dinero) es el mas lento de cambiar."
    ),
    "decision": (
        "Extraer checkout a un servicio propio, con un equipo stream-aligned dueno "
        "del flujo completo. Orders y payments le exponen APIs; checkout las orquesta."
    ),
    "consequences_pos": [
        "Un solo equipo decide sobre el flujo mas critico: cambios mas rapidos.",
        "La frontera pedido/pago queda explicita en un contrato, no en codigo enredado.",
    ],
    "consequences_neg": [
        "Una llamada de red mas en el camino critico: hay que cuidar latencia y fallos.",
        "Migrar el checkout en vivo es delicado; requiere un periodo de doble escritura.",
    ],
}

def render_adr(a):
    out = []
    out.append(f"# {a['id']}: {a['title']}")
    out.append("")
    out.append(f"**Status:** {a['status']}  |  **Fecha:** {a['date']}  |  "
               f"**Deciden:** {', '.join(a['deciders'])}")
    out.append("")
    out.append("## Contexto")
    out.append(a["context"])
    out.append("")
    out.append("## Decision")
    out.append(a["decision"])
    out.append("")
    out.append("## Consecuencias")
    out.append("A favor:")
    for c in a["consequences_pos"]:
        out.append(f"- {c}")
    out.append("En contra (el precio que aceptamos):")
    for c in a["consequences_neg"]:
        out.append(f"- {c}")
    return "\n".join(out)

print(render_adr(adr))
print()
print("-" * 66)
print("Esta pieza cabe en una pantalla. Dentro de dos anios, el dev que herede el")
print("checkout leera POR QUE existe el servicio sin tener que preguntarle a nadie.")
print("Eso es el ADR como comunicacion: el porque, viajando en el tiempo.")

Qué esperar. Al correrlo:

# ADR-014: Extraer checkout a su propio servicio

**Status:** Accepted  |  **Fecha:** 2026-03-10  |  **Deciden:** arquitecto, lead de orders, lead de payments

## Contexto
El modulo checkout vive en orders pero payments lo toca en cada cambio: es donde el pedido y el cobro se abrazan. Hoy dos squads deben coordinarse para cualquier ajuste, y el flujo mas critico del negocio (donde entra el dinero) es el mas lento de cambiar.

## Decision
Extraer checkout a un servicio propio, con un equipo stream-aligned dueno del flujo completo. Orders y payments le exponen APIs; checkout las orquesta.

## Consecuencias
A favor:
- Un solo equipo decide sobre el flujo mas critico: cambios mas rapidos.
- La frontera pedido/pago queda explicita en un contrato, no en codigo enredado.
En contra (el precio que aceptamos):
- Una llamada de red mas en el camino critico: hay que cuidar latencia y fallos.
- Migrar el checkout en vivo es delicado; requiere un periodo de doble escritura.

------------------------------------------------------------------
Esta pieza cabe en una pantalla. Dentro de dos anios, el dev que herede el
checkout leera POR QUE existe el servicio sin tener que preguntarle a nadie.
Eso es el ADR como comunicacion: el porque, viajando en el tiempo.

Lee el ADR generado con los ojos del dev del futuro, el del ejercicio 3 de la lección 1 —el que miró el diagrama y pensó "¿por qué checkout está separado de orders si están tan relacionados?"—. Ese dev abre este ADR y en treinta segundos tiene la respuesta que el diagrama no le daba: el Contexto le hace sentir la tensión (dos squads coordinando el flujo del dinero), la Decisión le explica la jugada (un equipo dueño del flujo completo), y las Consecuencias le dicen que la latencia extra que quizás está notando no es un bug, es el precio que se aceptó a conciencia. Con eso, el dev ya no propone deshacer la separación por ignorancia: si acaso la cuestiona, lo hace con conocimiento —sabiendo qué resolvió y qué costó—. El diagrama le mostró la foto; el ADR le contó la historia. La combinación es lo que comunica una arquitectura de verdad.

Fíjate también en un detalle práctico que la lección 7 va a explotar: como el ADR salió de datos estructurados y cabe en una pantalla, es un archivo de texto chico que puede vivir en el repositorio, versionado junto al código, cambiando cuando la decisión cambia. Nada de eso pasa con un documento de 500 páginas en una wiki. El ADR es pequeño a propósito: pequeño se mantiene, pequeño se lee, pequeño viaja.

El ADR frente al diagrama: qué comunica cada uno

Conviene fijar la división de trabajo, porque es la razón de que esta lección exista al lado de las de C4.

Comunica el...Envejece...Responde la pregunta de...
Diagrama (C4)qué — la forma del sistema hoycuando la estructura cambiaquien necesita orientarse en el sistema actual
ADRpor qué — el razonamiento detráscasi nunca (la decisión y su contexto son históricos)quien necesita entender por qué el sistema es así

Hay una asimetría interesante en la columna del medio. El diagrama describe el presente, así que envejece cada vez que el sistema cambia —hay que mantenerlo—. El ADR describe un momento histórico —"en marzo de 2026, dadas estas condiciones, decidimos esto"—, y ese momento no cambia nunca: aunque la decisión luego se revierta, el registro de que se tomó, por qué, y qué se sabía entonces sigue siendo verdad para siempre. Por eso un ADR no se "actualiza": se supersede (se escribe uno nuevo que dice "esto reemplaza al ADR-014") y el viejo se conserva como parte de la historia. La historia no se edita; se le añade. Esa permanencia es justo lo que le permite al ADR viajar en el tiempo: es un registro fechado, no una foto que hay que retocar.

La conclusión para el arquitecto: no elijas entre diagrama y ADR —usa los dos, porque comunican cosas distintas—. El paquete de comunicación completo de una decisión importante es el diagrama que muestra la nueva forma más el ADR que explica por qué. En el proyecto (lección 8) vas a entregar exactamente esa combinación.

Errores comunes

Escribir el ADR después, "para el archivo" (de trámite). Qué pasa: la decisión se tomó hace meses, alguien recuerda que "hay que documentarla", y escribe un ADR seco y retroactivo que solo dice el resultado ("checkout es un servicio aparte") sin la tensión ni el precio. Nadie que lo lea después entiende el porqué, porque el porqué no está. Por qué pasa: se trata el ADR como un requisito de cumplimiento, no como una carta a un lector futuro. Cómo detectarlo: si tu ADR se puede resumir en "decidimos X" sin un "porque Y estaba pasando y Z era el riesgo", es archivo, no comunicación. Cómo corregirlo: escríbelo cerca de la decisión, cuando la tensión está fresca, y llena el Contexto con el dolor real y las Consecuencias con el precio aceptado —eso es lo que el lector futuro necesita—.

Omitir las consecuencias negativas (de vender la decisión). Qué pasa: el ADR lista solo los beneficios, como un folleto de la decisión, y calla el precio. El lector futuro topa con ese precio en la práctica (la latencia extra, la complejidad de la migración) y no encuentra rastro de que se hubiera previsto —así que asume que fue un descuido y quizás intenta "arreglarlo"—. Por qué pasa: uno quiere que su decisión se vea bien. Cómo detectarlo: si tu sección de Consecuencias no tiene nada que duela, o mentiste o no pensaste bien la decisión. Cómo corregirlo: la parte más útil de un ADR para el futuro es qué se sacrificó a conciencia; escribe el precio con la misma honestidad que el beneficio, porque eso es lo que evita que alguien reabra un debate ya cerrado.

Confundir el ADR con documentación de cómo funciona (de nivel equivocado). Qué pasa: el "ADR" se llena de detalles de implementación —endpoints, esquemas de tablas, nombres de clases— en vez del razonamiento de la decisión. Se vuelve un documento técnico que envejece rápido y no comunica el porqué. Por qué pasa: se mezcla el por qué (ADR) con el cómo (que es código y diagramas). Cómo detectarlo: si tu ADR tiene que actualizarse cada vez que cambia el código, no es un ADR —es documentación técnica mal ubicada—. Cómo corregirlo: el ADR captura la decisión y su razón, que son históricas y estables; el cómo vive en el código y en los diagramas C4. Un ADR bien hecho casi no cambia después de escrito, porque describe un momento, no un estado.

Ejercicios

Ejercicio 1 — Rescata el porqué. Un ADR de Mercado dice, completo: "Decisión: Usamos PostgreSQL para el catálogo. Consecuencias: Es una base de datos relacional confiable." Un dev del futuro lo lee y no aprende nada útil. Reescríbelo para que comunique, inventando un contexto y unas consecuencias razonables. ¿Qué le faltaba?

Ver solución

Le faltaban las dos cosas que hacen que un ADR comunique: la tensión en el contexto y el precio en las consecuencias. Tal como está, no dice por qué PostgreSQL y no otra cosa, ni qué se descartó, ni qué se sacrificó —así que al dev futuro no le sirve para nada: no puede cuestionar la decisión con conocimiento ni entender sus límites—.

Una versión que comunica:

ADR-006: PostgreSQL para el catálogo Status: Accepted — 2025-11 Contexto: El catálogo necesita consultas relacionales complejas (filtros por categoría, precio, vendedor, stock) y garantías de consistencia en el inventario —no puede vender lo que no hay—. Evaluamos una base documental (MongoDB), pero nuestras consultas son intrínsecamente relacionales y necesitamos transacciones para el stock. El equipo ya conoce PostgreSQL a fondo. Decisión: PostgreSQL como base del catálogo, con la búsqueda por texto delegada a un índice aparte (Elasticsearch) donde lo relacional no ayuda. Consecuencias:

  • A favor: consultas relacionales y transacciones sólidas; el equipo es productivo desde el día uno.
  • El precio: la búsqueda por texto libre requiere un segundo sistema (Elasticsearch) y mantener ambos sincronizados; PostgreSQL solo no habría bastado para eso.

Ahora el dev futuro entiende por qué PostgreSQL (consultas relacionales + transacciones + expertise), por qué no una documental (se consideró, no encajaba), y por qué hay un Elasticsearch al lado (el precio de que PostgreSQL no hace bien la búsqueda de texto). Con eso puede tomar decisiones informadas; con el ADR original, no.

Ejercicio 2 — Diagrama o ADR. Para cada pregunta que se hace un dev nuevo en Mercado, di si la responde mejor un diagrama C4 o un ADR, y por qué: (a) "¿qué piezas componen el sistema y cómo se conectan?"; (b) "¿por qué el checkout es un servicio aparte y no parte de orders?"; (c) "¿con qué tecnología está hecha la API?"; (d) "¿por qué no usamos microservicios para todo desde el principio?".

Ver solución
  • (a) "¿Qué piezas y cómo se conectan?" → Diagrama (Container). Es una pregunta sobre la forma actual del sistema —el qué—. El Container la responde de un vistazo. Un ADR aquí sería el nivel equivocado.
  • (b) "¿Por qué checkout es un servicio aparte?" → ADR. Es una pregunta sobre el porqué de una decisión —justo lo que el diagrama no captura—. El ADR-014 le cuenta la tensión (dos squads coordinando el flujo del dinero) y la razón. El diagrama solo le mostraría que está separado, no por qué.
  • (c) "¿Con qué tecnología está hecha la API?" → Diagrama (Container). El qué otra vez; la tecnología de cada pieza está en el Container ("API — FastAPI"). No necesita ADR.
  • (d) "¿Por qué no microservicios desde el principio?" → ADR. Pregunta por el razonamiento detrás de una decisión estructural (empezar con monolito, extraer servicios solo cuando duele). Eso es un porqué histórico —quizás un ADR temprano que explique "empezamos monolito porque éramos un equipo y no teníamos los límites claros; extraemos servicios cuando la organización lo justifica"—. El diagrama de hoy no lo explica.

El patrón: preguntas de qué/cómo se ve/con qué → diagrama; preguntas de por qué es así/por qué no de otra forma → ADR. Los dos juntos responden todo.

Ejercicio 3 — La decisión que se revirtió. Hace un año, Mercado escribió el ADR-014 (extraer checkout). Hoy, tras aprender que la latencia extra causaba abandono de carritos, el equipo decide revertir y volver a integrar checkout en orders. Un dev propone: "borremos el ADR-014, ya no aplica, para no confundir". ¿Es correcto borrarlo? ¿Qué se debe hacer, y por qué importa para la comunicación en el tiempo?

Ver solución

No se debe borrar. Borrar el ADR-014 destruye justo lo que hace valioso al registro: la historia de por qué se tomó y por qué se revirtió. Si lo borras, dentro de un año alguien podría proponer otra vez extraer el checkout —sin saber que ya se intentó, que la latencia causó abandono de carritos, y que por eso se volvió atrás—. Repetiría el experimento y el dolor. El conocimiento más caro (qué ya probamos y no funcionó) se perdería.

Lo correcto, según la mecánica que aprendiste en la guía de decisiones: marcar el ADR-014 como Superseded y escribir un ADR nuevo —digamos ADR-027, "Reintegrar checkout en orders"— que explique el nuevo contexto (la latencia extra causaba abandono medible de carritos), la nueva decisión (volver a integrar) y su relación con el viejo ("supersedes ADR-014"). El ADR-014 se conserva, ahora con un status que dice "esto ya no aplica, ve al ADR-027".

Por qué importa para la comunicación en el tiempo: la cadena ADR-014 → ADR-027 le cuenta al lector futuro la historia completa —se separó por estas razones, se revirtió por estas otras—, que es infinitamente más útil que cualquiera de las dos decisiones sola. Un futuro arquitecto que considere separar el checkout leerá los dos y sabrá exactamente qué vigilar (la latencia) si vuelve a intentarlo. La historia no se edita ni se borra: se le añade. Un ADR revertido no es basura; es la lección más cara que el equipo aprendió, guardada para que no se repita.

Resumen y siguiente paso

En esta lección usaste el ADR como herramienta de comunicación: el porqué de una decisión, empaquetado para viajar en el tiempo hasta quien llegue después. Con la nota del dueño anterior de la casa viste que lo que la casa (el código, los diagramas) no puede explicar por sí sola —por qué las decisiones raras fueron en realidad informadas— es exactamente lo que el ADR conserva, evitando que el que llega deshaga lo bueno por ignorancia o respete lo malo por superstición. Generaste, ejecutado, el ADR-014 de Mercado como una pieza que comunica: con la tensión en el contexto, el precio en las consecuencias, y el status que dice si aún aplica. Y fijaste la división de trabajo: el diagrama comunica el qué (y envejece con el sistema), el ADR comunica el por qué (y es un registro histórico que no se edita, se supersede).

Antes de avanzar deberías poder: escribir un ADR que comunique (tensión en el contexto, precio en las consecuencias, status vigente) y no solo archive; decidir si una pregunta se responde con diagrama o con ADR; y manejar una decisión revertida sin borrar la historia (superseded + ADR nuevo).

Lo que sigue es la vacuna. Ya sabes producir buena comunicación —los diagramas al nivel correcto, el ADR con el porqué—; falta aprender a no producir la mala. En la lección 7 vas a atacar los dos grandes fracasos de la comunicación de arquitectura: el documento de 500 páginas que nadie lee (documentar de más, comunicar de menos) y el diagrama-espagueti que muestra todo y no comunica nada. Vas a correr dos validadores sobre Mercado —uno que detecta un diagrama que mezcla niveles de abstracción, otro que cuenta elementos y marca el espagueti cuando pasa el límite legible— y a entender por qué un diagrama se pudre si no vive versionado junto al código. Es el paso de "sé comunicar bien" a "sé reconocer y evitar los dos modos de comunicar mal".

Recursos

← Anterior5. El diagrama correcto para la audienciaSiguiente →7. Evitar el documento de 500 páginas y el diagrama-espagueti