Módulo 8: Proyecto capstone — sé el arquitecto de Mercado ante un cambio

7. Planea la evolución y la documentación

Siguiente →

Descripción

Este es el paso 6, el último antes de ensamblar el entregable, y es el que separa lanzar una feature de cerrar el oficio. En los pasos anteriores derivaste los atributos, estructuraste los equipos, comunicaste la decisión y lideraste su adopción. Pero un cambio no termina cuando se lanza: sigue vivo, y el arquitecto tiene que planear cómo va a evolucionar —qué construir ahora y qué diferir— y dejar la documentación que sobrevive para que el cambio no dependa de una sola cabeza. Al terminar esta lección vas a tener los dos últimos artefactos del dossier: el plan de evolución (qué es ahora, qué es sacrificial, qué se difiere dejando la costura) y la medición de cómo la documentación sube el bus factor del surface nuevo. Este paso integra dos módulos —M6 (diseñar para el cambio) y M7 (documentación que sobrevive)— porque en la práctica van juntos: planear la evolución sin documentarla es dejar el plan en tu cabeza, y documentar sin planear la evolución es documentar una foto que ya empezó a cambiar.

Esto importa porque los dos errores opuestos —construir de más y construir de menos— son igual de caros, y el cambio de Mercado los invita a los dos. La tentación de over-engineering: como la meta dice "crecer 10x", construir hoy toda la maquinaria del 10x —sharding del catálogo, multi-región, una tubería de ingesta masiva— antes de que haya un solo vendedor externo generando ese volumen, gastando meses en escalar para un tráfico que aún no existe. La tentación opuesta, under-engineering: lanzar el surface sin dejar las costuras para el 10x, de modo que cuando el volumen llegue, agregarlas sea un refactor carísimo. El arquitecto que planea para el cambio evita las dos: construye hoy las costuras caras de agregar después, pone versiones sacrificiales de lo que depende de datos que aún no existen, y difiere lo que nadie necesita todavía —dejando la costura para no quedar atrapado—. Y luego lo documenta de forma que el equipo entero pueda mantenerlo, no solo quien lo construyó.

Conexión con el módulo: esta lección hace el paso 6 del hilo y aporta las piezas de M6 y M7 al capstone. Recibe su entrada del paso 5 (qué se adoptó de verdad y quién es dueño de qué: no se planea la evolución de lo imaginado, sino de lo que se construyó y adoptó) y del paso 2 (el conflicto rector scalability-vs-cost, que es justo lo que el plan de evolución resuelve difiriendo el 10x costoso). Su salida cierra el dossier que la lección 8 ensamblará y defenderá ante el VP. La frontera se respeta: la reversibilidad y el último momento responsable como técnica se enseñaron en architecture-decisions; aquí es la postura mental del oficio —cómo el arquitecto secuencia y documenta—. Y las herramientas específicas de documentación quedan fuera; aquí el principio (docs-as-code) y el criterio (el bus factor).

El que construye una casa para una familia que va a crecer

Piensa en una pareja que construye su primera casa, sabiendo que van a tener hijos pero sin saber cuántos ni cuándo. Tienen tres formas de encarar el futuro incierto.

La primera, over-engineering: construir hoy una mansión de ocho recámaras "por si acaso". Gastan todo su dinero y años de obra en cuartos vacíos que quizás nunca se llenen, con un préstamo que los ahoga mientras esperan una familia que tal vez sea de dos hijos, no de seis. Construyeron para un futuro imaginado que puede no llegar, y el costo de ese futuro los aplasta en el presente.

La segunda, under-engineering: construir una casa de dos recámaras con muros de carga colocados de tal forma que es imposible agregar un piso o un cuarto después. Cuando llegue el segundo hijo, descubren que ampliar significa demoler media casa. Ahorraron hoy y se amarraron: el futuro llegó y no cabían.

La tercera, la que hace un buen arquitecto: construir hoy la casa que la familia necesita ahora —dos o tres recámaras—, pero dejando las costuras que hacen barato crecer después: cimientos que aguantan un segundo piso, tuberías con capacidad de sobra, un muro que se sabe que no es de carga para tirarlo cuando haga falta. No construyen los cuartos que no existen todavía (eso sería la mansión), pero sí dejan preparado el terreno para construirlos cuando el hijo llegue. Y algo más: dejan los planos donde el próximo dueño (o el albañil de la ampliación) los encuentre, para que sepa qué muro se puede tirar y cuál no —sin tener que adivinar—.

El arquitecto de Mercado ante "crecer 10x" es esa pareja. Over-engineering sería construir hoy toda la infraestructura del 10x antes de que haya vendedores externos generando ese volumen —la mansión vacía—. Under-engineering sería lanzar el surface sin dejar las costuras, de modo que escalar después exija demoler —la casa que no se puede ampliar—. El oficio es construir las costuras caras hoy, poner versiones simples y desechables de lo incierto, diferir lo que nadie necesita aún, y dejar los planos (la documentación) para que el equipo pueda crecer la casa sin adivinar. Esta lección ejecuta ese plan y mide cuánto suben los planos el bus factor.

Ejemplo trabajado: el plan de evolución y el bus factor

Vamos a ejecutar dos cosas. Primero, clasificar cada candidato del cambio en qué construir ahora, qué poner sacrificial, y qué diferir, según tres señales: si lo necesita el lanzamiento v1 (no el 10x futuro), si es una costura cara de agregar después, y si decidirlo bien exige datos que aún no tenemos. Segundo, medir el bus factor del surface nuevo antes y después de dejar la documentación que sobrevive.

# Capstone paso 6: planear la EVOLUCION (que primero, que se difiere, que costuras dejo)
# y dejar DOCUMENTACION que sobrevive. Ni over- ni under-engineering: construyo hoy las
# costuras caras de agregar despues, y difiero lo que depende de datos que aun no existen.

# Cada candidato del cambio, con tres senales:
#   goal_critical      -> lo necesita el LANZAMIENTO v1 (no el 10x futuro)?
#   expensive_later    -> es una costura cara de agregar despues (estructural)?
#   high_uncertainty   -> decidirlo bien exige datos que todavia no tenemos?
candidates = {
    "seller_api_contract_and_gateway": dict(goal_critical=True,  expensive_later=True,  high_uncertainty=False),
    "seller_platform_team_boundary":   dict(goal_critical=True,  expensive_later=True,  high_uncertainty=False),
    "platform_as_service_contracts":   dict(goal_critical=True,  expensive_later=True,  high_uncertainty=False),
    "seller_risk_scoring":             dict(goal_critical=True,  expensive_later=False, high_uncertainty=True),
    "listing_ingestion_pipeline":      dict(goal_critical=True,  expensive_later=False, high_uncertainty=True),
    "catalog_sharding_for_10x":        dict(goal_critical=False, expensive_later=True,  high_uncertainty=True),
    "multi_region_availability":       dict(goal_critical=False, expensive_later=True,  high_uncertainty=True),
    "seller_analytics_dashboard":      dict(goal_critical=False, expensive_later=False, high_uncertainty=False),
}


def classify(c):
    # Costura estructural cara y necesaria ya: construir AHORA (last responsible moment).
    if c["goal_critical"] and c["expensive_later"]:
        return "NOW"
    # La necesita el lanzamiento pero no sabemos aun como hacerla bien: version simple
    # y desechable AHORA, con una costura para reemplazarla (sacrificial architecture).
    if c["goal_critical"] and c["high_uncertainty"]:
        return "SACRIFICIAL_NOW"
    # No la necesita el lanzamiento: diferir. Si es cara de agregar, dejar la costura.
    if c["expensive_later"]:
        return "DEFER_WITH_SEAM"
    return "DEFER"


plan = {name: classify(sig) for name, sig in candidates.items()}
buckets = {"NOW": [], "SACRIFICIAL_NOW": [], "DEFER_WITH_SEAM": [], "DEFER": []}
for name, b in plan.items():
    buckets[b].append(name)

print("=== Plan de evolucion del cambio (que primero, que se difiere) ===")
labels = {
    "NOW": "AHORA (costura estructural cara y necesaria ya)",
    "SACRIFICIAL_NOW": "AHORA, SACRIFICIAL (simple hoy, se reemplaza con datos reales)",
    "DEFER_WITH_SEAM": "DIFERIR dejando la costura (no la pide el lanzamiento; cara de anadir)",
    "DEFER": "DIFERIR (YAGNI: nadie la necesita todavia)",
}
for b in ("NOW", "SACRIFICIAL_NOW", "DEFER_WITH_SEAM", "DEFER"):
    print(f"\n{labels[b]}:")
    for name in buckets[b]:
        print(f"  - {name}")

print()
print(f"AHORA: {len(buckets['NOW'])}   SACRIFICIAL: {len(buckets['SACRIFICIAL_NOW'])}   "
      f"DIFERIDAS: {len(buckets['DEFER_WITH_SEAM']) + len(buckets['DEFER'])}")
print("Construyo el 33% que es costura estructural, no el 100% del futuro imaginado.")

# --- Documentacion que sobrevive: el bus factor del surface nuevo, antes/despues ---
# Cuantas personas entienden cada modulo critico. El bus factor del sistema es el
# MINIMO (el eslabon mas debil): cuantas tendrian que irse para dejarlo sin mantener.
critical_modules = ["seller_api", "seller_onboarding", "listing_ingestion", "payout_processing"]

# ANTES de documentar: el conocimiento vive en la cabeza de quien lo construyo.
knowers_before = {
    "seller_api": 1, "seller_onboarding": 2,
    "listing_ingestion": 1, "payout_processing": 1,
}
# DESPUES de docs-as-code (README de onboarding + C4 + ADR versionados junto al codigo):
# el equipo entero puede mantener cualquier modulo; el onboarding deja de depender de una cabeza.
knowers_after = {
    "seller_api": 4, "seller_onboarding": 4,
    "listing_ingestion": 3, "payout_processing": 3,
}

bf_before = min(knowers_before[m] for m in critical_modules)
bf_after = min(knowers_after[m] for m in critical_modules)

print()
print("=== Bus factor del surface de vendedores ===")
print(f"{'modulo':<20}{'antes':>7}{'despues':>9}")
for m in critical_modules:
    print(f"{m:<20}{knowers_before[m]:>7}{knowers_after[m]:>9}")
print(f"\nBus factor del sistema (el minimo): {bf_before} -> {bf_after}")
print("Antes, si una persona se va, el surface del cambio queda sin mantener (bus factor 1).")
print("La documentacion que sobrevive (docs-as-code) sube el bus factor: el cambio deja")
print("de depender de una sola cabeza. Eso es cerrar el oficio, no solo lanzar la feature.")

Qué esperar. Al correrlo:

=== Plan de evolucion del cambio (que primero, que se difiere) ===

AHORA (costura estructural cara y necesaria ya):
  - seller_api_contract_and_gateway
  - seller_platform_team_boundary
  - platform_as_service_contracts

AHORA, SACRIFICIAL (simple hoy, se reemplaza con datos reales):
  - seller_risk_scoring
  - listing_ingestion_pipeline

DIFERIR dejando la costura (no la pide el lanzamiento; cara de anadir):
  - catalog_sharding_for_10x
  - multi_region_availability

DIFERIR (YAGNI: nadie la necesita todavia):
  - seller_analytics_dashboard

AHORA: 3   SACRIFICIAL: 2   DIFERIDAS: 3
Construyo el 33% que es costura estructural, no el 100% del futuro imaginado.

=== Bus factor del surface de vendedores ===
modulo                antes  despues
seller_api                1        4
seller_onboarding         2        4
listing_ingestion         1        3
payout_processing         1        3

Bus factor del sistema (el minimo): 1 -> 3
Antes, si una persona se va, el surface del cambio queda sin mantener (bus factor 1).
La documentacion que sobrevive (docs-as-code) sube el bus factor: el cambio deja
de depender de una sola cabeza. Eso es cerrar el oficio, no solo lanzar la feature.

Lee primero el plan de evolución, que es la postura mental del oficio hecha lista. De los ocho candidatos, solo tres son AHORA —el contrato de la Seller API y su gateway, la frontera del equipo seller_platform, y los contratos de plataforma-como-servicio—. ¿Por qué esos tres y no más? Porque son las costuras estructurales caras de agregar después: si no defines el contrato de la Seller API desde el día uno, cambiarlo cuando ya hay terceros integrados es carísimo; si no creas el equipo dueño ahora, la maniobra de Conway no ocurre; si no defines los contratos de plataforma-como-servicio, el surface nace acoplado. Estas tres son las tuberías y los cimientos de la casa: se ponen al construir, o demoler para agregarlas después. Fíjate en la última línea del plan: el arquitecto construye el 33% que es costura estructural, no el 100% del futuro imaginado. Ahí está la defensa contra el over-engineering: la mayoría de lo que "podría" construirse no se construye ahora.

Ahora las dos SACRIFICIALES, que son el matiz más fino del oficio. seller_risk_scoring (evaluar el riesgo de un vendedor externo) y listing_ingestion_pipeline (la tubería que importa los productos) las necesita el lanzamiento —no puedes abrir a terceros sin evaluar su riesgo ni sin importar sus productos—, pero decidirlas bien exige datos que aún no tienes: no sabes qué patrones de fraude tendrán los vendedores reales ni qué volumen de listings llegará. La respuesta no es esperar (el lanzamiento las necesita) ni construir la versión definitiva a ciegas (sería adivinar): es poner una versión simple y desechable hoy —un scoring básico con reglas manuales, una ingesta síncrona sencilla— sabiendo que se reemplazará cuando los datos reales lleguen, y dejando la costura para reemplazarla sin dolor. Esto es la sacrificial architecture del módulo 6: construir algo a sabiendas de que se tirará, no por descuido sino por estrategia —es más barato construir simple hoy y reemplazar con datos que construir complejo hoy con suposiciones—.

Y las tres DIFERIDAS, donde vive el conflicto rector del paso 2. catalog_sharding_for_10x y multi_region_availability son la maquinaria del 10x: caras, estructurales, pero el lanzamiento no las necesita —al abrir, no hay 10x de tráfico todavía—. Aquí es donde el arquitecto resuelve el conflicto scalability-vs-cost (57, el que gobernaba el cambio): no construye la infraestructura cara del 10x hoy (protege el cost), pero deja la costura para agregarla cuando el volumen la justifique (protege el scalability futuro). Es "diferir con costura", no "abandonar": abstrae el acceso a datos para que meter sharding después no sea demoler. Y seller_analytics_dashboard es YAGNI puro —nadie lo necesita todavía, ni es caro de agregar después—, así que se difiere sin más. El plan completo es la postura del oficio: construye las costuras (3 ahora), pon versiones sacrificiales de lo incierto (2), y difiere el futuro caro dejándole la costura (3) —ni la mansión vacía ni la casa que no se puede ampliar—.

La segunda mitad de la salida es la documentación. El bus factor mide cuántas personas tendrían que irse para que un módulo crítico quede sin mantener —es el eslabón más débil: el mínimo sobre los módulos—. Antes de documentar, el surface nuevo tiene bus factor 1: seller_api, listing_ingestion y payout_processing los entiende una sola persona (quien los construyó), así que si esa persona se va, el cambio más importante del año queda huérfano. Tras dejar la documentación que sobrevive —docs-as-code: el README que onboarda, el C4 del paso 4 y el ADR-021 versionados junto al código— el bus factor sube a 3: el equipo entero puede mantener cualquier módulo porque el conocimiento dejó de vivir en una cabeza y pasó a estar donde cualquiera lo encuentra. Fíjate que el ADR del paso 4 no era solo comunicación en el momento: era una inversión en el bus factor —el porqué documentado es lo que permite que alguien que no estuvo en la sala mantenga el surface sin adivinar—. Subir el bus factor de 1 a 3 es la diferencia entre un cambio que depende de una persona y uno que la organización posee. Eso es cerrar el oficio.

Profundización: por qué la evolución y la documentación cierran el hilo juntas

Vale la pena entender por qué este paso junta dos módulos que parecen distintos —diseñar para el cambio (M6) y documentar (M7)— y por qué es el cierre natural del hilo.

La evolución y la documentación son la misma pregunta vista en dos tiempos. Planear la evolución es preguntarse "¿cómo va a cambiar esto en el futuro?". Documentar de forma que sobreviva es preguntarse "¿quién va a entender esto en el futuro para poder cambiarlo?". Las dos apuntan al mismo horizonte —el sistema después de hoy— y una sin la otra queda coja. Un plan de evolución brillante que solo vive en la cabeza del arquitecto no sobrevive a que el arquitecto se vaya: cuando el volumen del 10x llegue y toque meter el sharding diferido, nadie sabrá que la costura estaba prevista ni dónde. Y una documentación impecable de un sistema que no se diseñó para cambiar documenta una jaula. Por eso van juntas: el arquitecto diseña las costuras para el cambio y documenta dónde están y por qué, para que quien llegue después pueda usarlas.

Este paso es donde los artefactos anteriores demuestran su segundo valor. El C4 y el ADR del paso 4 se produjeron para comunicar en el momento, pero aquí revelan su valor duradero: son exactamente la documentación que sube el bus factor. El ADR-021, que en el paso 4 le explicaba el porqué al VP y al dev, en el paso 6 es lo que permite que un ingeniero nuevo entienda por qué el gateway existe y por qué el sharding se difirió —sin ese ADR, el bus factor no subiría, porque el porqué seguiría en una cabeza—. Esta es la belleza del hilo: cada artefacto sirve dos veces. El ranking del paso 2 justificó la estructura y luego alimentó el rollout; el C4 y el ADR del paso 4 comunicaron y luego documentaron. El capstone no produce artefactos desechables; produce piezas que trabajan a lo largo de todo el ciclo de vida.

Y aquí el hilo se conecta consigo mismo, porque diseñar para el cambio es aceptar que el hilo se recorrerá otra vez. El plan de evolución reconoce que las metas del negocio cambiarán —Mercado abrió a vendedores externos hoy; mañana querrá otra cosa—, y que cuando lo hagan, el arquitecto volverá a recorrer el hilo completo: derivar los nuevos atributos, reestructurar si hace falta, comunicar, liderar, evolucionar. La documentación que dejas hoy (el C4, los ADRs) es el punto de partida de ese próximo recorrido: el próximo arquitecto no empezará de cero, empezará leyendo lo que dejaste. Por eso documentar de forma que sobreviva no es el final del oficio; es preparar el siguiente ciclo. El arquitecto que planea para el cambio y documenta no está cerrando un proyecto: está dejando el sistema listo para que el oficio se ejerza sobre él otra vez, por alguien más, con menos dolor.

Un matiz honesto sobre los modelos. La clasificación de los ocho candidatos usa un juicio (¿es goal-critical?, ¿es cara de agregar después?, ¿hay incertidumbre de datos?) que es discutible caso por caso —alguien podría argumentar que el risk_scoring es tan crítico que merece más que una versión sacrificial—, y esa discusión es sana: el modelo hace el juicio explícito para poder debatirlo. Los números del bus factor (1 knower antes, 3-4 después) son ilustrativos; lo robusto es la forma —el conocimiento concentrado en una cabeza es bus factor 1, y la documentación que onboarda lo sube—. El modelo captura el criterio del oficio, no una medición exacta.

Errores comunes

Construir la maquinaria del 10x antes de que haya 10x (de over-engineering). Qué pasa: como la meta dice "crecer 10x", el equipo construye hoy el sharding del catálogo, el multi-región y la tubería de ingesta masiva —meses de trabajo— antes de que exista un solo vendedor externo generando ese volumen. El lanzamiento se retrasa, el costo se dispara (violando el atributo cost), y la mitad de esa infraestructura resulta mal dimensionada porque se construyó con suposiciones, no con datos reales. Por qué pasa: "crecer 10x" suena a "hay que construir para 10x ya". Cómo detectarlo: si estás construyendo capacidad para un volumen que aún no existe, estás llenando la mansión de cuartos vacíos. Cómo corregirlo: difiere la maquinaria del 10x dejando la costura (abstrae el acceso a datos para meter sharding después sin demoler); constrúyela cuando el volumen real la justifique, no cuando la meta la menciona.

Lanzar sin dejar las costuras (de under-engineering). Qué pasa: el equipo, evitando el over-engineering, lanza el surface lo más simple posible pero sin dejar preparado el terreno —el acceso a datos hardcodeado de forma que meter sharding después exija reescribir medio servicio, la ingesta acoplada de forma que escalarla sea demoler—. Cuando el volumen llega, agregar lo diferido es un refactor carísimo. Por qué pasa: se confunde "no construir el futuro" con "no dejar espacio para el futuro". Cómo detectarlo: si diferiste algo caro pero no puedes agregarlo después sin reescribir, no dejaste la costura. Cómo corregirlo: "diferir con costura" no es "diferir a secas" —la casa de tres recámaras se construye con cimientos que aguantan un segundo piso—; difiere la implementación, pero deja la abstracción (el contrato, el punto de extensión) que hace barato agregarla.

Dejar el conocimiento en una cabeza y llamarlo "lo documentaré después" (de bus factor 1). Qué pasa: el surface de vendedores se construye y se lanza, pero la documentación —el README, el C4 actualizado, los ADRs— queda "para cuando haya tiempo", y el conocimiento vive solo en quien lo construyó (bus factor 1). Cuando esa persona se va o se enferma, el cambio más importante del año queda huérfano y nadie sabe por qué el gateway existe o dónde está la costura del sharding. Por qué pasa: documentar se siente como trabajo que no entrega valor visible, siempre postergable. Cómo detectarlo: si un solo módulo crítico lo entiende una sola persona, tu bus factor es 1, sin importar cuánto código haya. Cómo corregirlo: docs-as-code —el README, el C4 y el ADR versionados junto al código, actualizados en el mismo PR que cambia el sistema—; el ADR ya lo tienes del paso 4, solo falta que viva en el repo. Documentar no es un extra al final; es lo que convierte un cambio de una persona en un cambio de la organización.

Ejercicios

Ejercicio 1 — Clasifica un candidato nuevo. El liderazgo propone agregar "notificaciones push a los vendedores externos cuando se vende uno de sus productos". Aplica las tres señales (¿lo necesita el lanzamiento v1?, ¿es una costura cara de agregar después?, ¿decidirlo bien exige datos que no tenemos?) y clasifícalo (NOW / SACRIFICIAL_NOW / DEFER_WITH_SEAM / DEFER). Justifica.

Ver solución

Aplicando las tres señales:

  • ¿Lo necesita el lanzamiento v1? Probablemente no. Un vendedor externo puede empezar a vender sin recibir un push instantáneo por cada venta —puede consultar su panel—. Es una mejora de experiencia, no un requisito para que el surface funcione. (goal_critical = False.)
  • ¿Es una costura cara de agregar después? No. Agregar notificaciones push más adelante es aditivo: se consume el evento de "venta" (que ya existe) y se envía por notifications (que ya es un servicio de plataforma). No moldea la estructura ni exige demoler nada. (expensive_later = False.)
  • ¿Exige datos que no tenemos? No especialmente. (high_uncertainty = False.)

Clasificación: DEFER (YAGNI). Con goal_critical = False y expensive_later = False, cae en el mismo cubo que el seller_analytics_dashboard: diferir sin más, porque nadie lo necesita todavía y agregarlo después es barato. No hace falta ni dejar una costura especial, porque el evento de venta y el servicio de notificaciones ya existen —la costura ya está—.

El matiz que enseña el ejercicio: no todo lo diferido necesita "dejar la costura" explícitamente. catalog_sharding_for_10x se difiere con costura porque agregarlo después es caro y estructural (hay que preparar el acceso a datos). Las notificaciones push se difieren sin costura especial porque agregarlas después es barato y aditivo. La regla: deja la costura cuando lo diferido sea caro de agregar; si es barato, difiérelo a secas. Confundirlo lleva al over-engineering (preparar costuras elaboradas para cosas que se agregarán fácil de todos modos).

Ejercicio 2 — El conflicto rector, resuelto en el tiempo. El paso 2 detectó que scalability vs cost (57) era el conflicto que gobernaba el cambio. Explica cómo el plan de evolución de esta lección resuelve ese conflicto sin que el arquitecto tenga que elegir un ganador absoluto —y por qué eso es distinto de "resolver el trade-off" en el sentido de la guía hermana—.

Ver solución

El plan de evolución resuelve el conflicto scalability-vs-cost distribuyéndolo en el tiempo, no eligiendo un ganador. El conflicto era: "crecer 10x" (scalability) contra "no triplicar la factura" (cost). En un solo momento, esos dos tiran de frente —construir para 10x hoy cuesta mucho—. Pero el plan de evolución los reconcilia con el eje del tiempo:

  • Hoy protege el cost: difiere catalog_sharding_for_10x y multi_region_availability (la maquinaria cara del 10x), porque el lanzamiento no tiene ese volumen todavía. No se gasta en escalar para un tráfico que no existe. Cost gana en el presente.
  • Mañana protege el scalability: deja la costura para agregar esa maquinaria cuando el volumen real la justifique. No se pinta el arquitecto en una esquina; el 10x sigue siendo posible sin demoler. Scalability gana en el futuro, cuando de verdad importa.

Así, el arquitecto no tuvo que decir "scalability sí, cost no" (que habría enojado al CFO) ni "cost sí, scalability no" (que habría matado la meta insignia): dijo "cost ahora, scalability cuando el volumen lo pida", y las dos metas se cumplen en su momento correcto.

Por qué es distinto de "resolver el trade-off" de la guía hermana. architecture-decisions-and-tradeoffs resuelve un trade-off decidiendo el punto de balance con una matriz —cuánto de cada atributo, con qué opción técnica—. Eso sigue siendo necesario cuando llegue el momento de meter el sharding (¿qué estrategia de sharding?, ¿qué costo acepta?). Lo que el paso 6 hace es distinto y complementario: secuencia el conflicto en el tiempo (qué ahora, qué después) para no tener que resolverlo todo hoy. La postura del oficio (M6) dice "difiere la decisión hasta el último momento responsable, cuando tengas datos"; el método de decidir (guía hermana) dice "cuando llegue ese momento, así eliges el balance". El capstone hace lo primero; remite a la guía hermana para lo segundo.

Ejercicio 3 — El bus factor y el ADR. El bus factor del surface subió de 1 a 3 gracias a la documentación que sobrevive. Explica específicamente qué papel juega el ADR-021 (del paso 4) en subir ese bus factor —qué conocimiento captura que el código y el C4 no capturan— y qué pasaría con el bus factor si solo se dejara el código y el diagrama, sin el ADR.

Ver solución

El ADR-021 sube el bus factor porque captura el por qué, que ni el código ni el C4 contienen. El código dice cómo está construido el surface (se lee del repositorio). El C4 dice qué piezas hay y cómo se conectan (la foto actual). Pero ninguno de los dos dice por qué: por qué existe el gateway (security de terceros), por qué se creó un equipo dueño (scalability, la fricción 21→7), por qué catalog_sharding se difirió (el conflicto cost-vs-scalability), qué costuras son intencionales y cuáles no. Ese porqué es exactamente el conocimiento que vive en la cabeza de quien decidió —y que, sin el ADR, se va con esa persona—.

Qué pasaría con solo código y diagrama, sin el ADR. El bus factor aparente subiría un poco (más gente puede leer el código y el C4), pero el bus factor real seguiría frágil, porque quien herede el surface entendería el qué y el cómo pero no el por qué —y sin el porqué, cae en las dos trampas del módulo 3: o deshace decisiones buenas por no entenderlas (quita el gateway "porque es complejidad innecesaria", sin saber que protege a terceros), o respeta decisiones por superstición ("no toco el sharding diferido, debe haber una razón", sin saber cuál). Un ingeniero que puede leer el código pero no sabe por qué está así no puede evolucionar el sistema con seguridad —solo puede mantenerlo a ciegas—, y eso es un bus factor engañoso: parece que hay quien lo mantenga, pero nadie puede cambiarlo bien.

La lección de integración: el ADR que produjiste en el paso 4 para comunicar es, en el paso 6, la pieza que de verdad sube el bus factor —más que el código o el diagrama—, porque es la única que preserva el razonamiento. Por eso el capstone insiste en el ADR: no es burocracia del momento, es la inversión que hace que el cambio sobreviva a las personas. Documentar el por qué (docs-as-code, el ADR versionado) es lo que convierte "el equipo puede leer el código" en "el equipo puede evolucionar el sistema" —que es el bus factor que importa—.

Resumen y siguiente paso

En esta lección hiciste el paso 6 del entregable: planear la evolución y dejar la documentación que sobrevive. Con la familia que construye una casa para crecer —ni la mansión vacía (over-engineering) ni la casa que no se puede ampliar (under-engineering), sino la casa de hoy con las costuras para mañana— entendiste la postura mental del arquitecto que diseña para el cambio. Lo ejecutaste: de ocho candidatos, tres se construyen ahora (las costuras estructurales caras), dos son sacrificiales (versiones simples de lo que depende de datos que no existen), y tres se difieren (la maquinaria del 10x, con costura, resolviendo el conflicto cost-vs-scalability en el tiempo). Y mediste que la documentación que sobrevive —docs-as-code: el README, el C4 y el ADR versionados— sube el bus factor del surface de 1 a 3, convirtiendo un cambio que depende de una cabeza en uno que la organización posee. Entendiste que la evolución y la documentación son la misma pregunta en dos tiempos, que los artefactos del paso 4 sirven dos veces (comunicar y documentar), y que documentar de forma que sobreviva es preparar el próximo recorrido del hilo.

Antes de avanzar deberías poder: clasificar los candidatos de un cambio en ahora / sacrificial / diferido-con-costura / diferido, con las tres señales; explicar cómo el plan de evolución resuelve el conflicto rector en el tiempo; distinguir over- de under-engineering y el "diferir con costura" que evita los dos; y explicar por qué el ADR sube el bus factor más que el código o el diagrama.

Lo que sigue es el paso final: ensamblar y defender. Ya construiste las seis piezas del entregable —el encargo enmarcado, los atributos, la estructura, el C4 y el ADR, el rollout, la evolución y la documentación—. La lección 8 es el proyecto: vas a ensamblar todo en el dossier integrado del arquitecto, medirlo contra una rúbrica, escribir el guion de la conversación con el VP que cose el oficio de vuelta al negocio, y —con eso— cerrar toda la guía, apuntando hacia dónde seguir en el ecosistema. Es donde compruebas que las seis piezas no eran seis proyectos, sino un solo movimiento.

Recursos

  • Martin Fowler — "Sacrificial Architecture" — el ensayo que nombra la estrategia de construir algo a sabiendas de que se reemplazará; el respaldo directo de las dos piezas sacrificiales del plan (risk scoring e ingesta).
  • Martin Fowler — "Yagni" — "You Aren't Gonna Need It", el principio que sostiene diferir la maquinaria del 10x hasta que el volumen la justifique, y la defensa contra el over-engineering de este paso.
  • arc42.org — la plantilla de documentación de arquitectura que integra el C4 y los ADRs en un documento vivo; el marco de la documentación que sobrevive y sube el bus factor.
  • Simon Brown — "Software architecture as code / docs-as-code" — el principio de versionar los diagramas y las decisiones junto al código (no en una wiki que se pudre), que es lo que hace que la documentación del cambio sobreviva al tiempo y a las personas.
← Anterior6. Lidera el rollout sin autoridadSiguiente →8. Proyecto: sé el arquitecto de Mercado ante el cambio