El arquitecto sigue cerca del código

Descripción

La lección 2 dejó una consecuencia colgando: si el arquitecto tiene que estar en la obra para corregir el plano, tiene que poder bajar a la obra. En el software, la obra es el código. Esta lección ataca la segunda imagen falsa del rol: el arquitecto que se cree demasiado senior para tocar código, que vive en las reuniones, las slides y los diagramas, y que decide sobre el sistema que recuerda en vez del que existe. Es una imagen especialmente dañina porque suena a madurez —"ascendí, ya no me toca programar"— cuando en realidad es el principio de la irrelevancia técnica.

La metáfora que organiza esta lección es de Gregor Hohpe: el elevador del arquitecto. Un edificio tiene un penthouse —el piso de arriba, donde está el negocio: los stakeholders, la estrategia, el presupuesto— y una sala de máquinas —el sótano, donde está el código: los servicios, las bases de datos, los bugs, lo que de verdad corre—. El arquitecto no vive en ninguno de los dos pisos; su trabajo es montar el elevador que los conecta: subir a traducir el negocio en atributos técnicos, y bajar a ver cómo la sala de máquinas puede (o no puede) cumplirlos. El arquitecto que se queda arriba, en el penthouse, pierde contacto con la máquina y empieza a decidir sobre un modelo mental viejo. Esta lección mide qué le pasa a la calidad de sus decisiones —concretamente, a sus estimaciones— a medida que se despega del código.

Conexión con el módulo. Es la corrección directa de la torre de marfil (lección 2): estar presente en la obra requiere bajar al código, y esta lección explica cómo y por qué. También prepara todo lo que sigue: un arquitecto pegado al código hace decisiones más reversibles porque conoce el costo real de deshacerlas (lección 4), habilita mejor porque entiende el trabajo de las squads (lección 5), y evita el BDUF porque siente cuándo la información aún no está madura (lección 7). Cuidado con el matiz, porque es fácil malinterpretar: "cerca del código" no significa que el arquitecto sea el que más código escribe —eso lo convertiría en un cuello de botella distinto, el de la lección 6—. Significa que mantiene un contacto suficiente y regular para que su modelo mental corresponda a la realidad. Codea distinto, no necesariamente menos.

Una analogía: el chef que dejó de entrar a la cocina

Piensa en un chef que abrió un restaurante y tuvo éxito. Al principio cocinaba cada plato. Con el crecimiento, contrató cocineros, y su rol cambió: ahora diseña el menú, decide los proveedores, entrena al equipo, habla con los clientes importantes. Hasta aquí, sano —es exactamente el arquitecto que sube al penthouse—.

Pero hay dos chefs posibles a partir de ese punto.

El chef que dejó de entrar a la cocina. Se instaló en el comedor y la oficina. Diseña el menú desde su escritorio, basándose en cómo recuerda que funcionaba la cocina hace tres años. Promete a un cliente importante un plato nuevo "para el viernes" sin haber pisado la cocina en meses: no sabe que el horno viejo tarda el doble, que el proveedor de mariscos cambió, que dos cocineros nuevos aún no dominan la técnica que ese plato exige. Su promesa es irreal, y la cocina se rompe intentando cumplirla. Sus decisiones son cada vez más bonitas en el papel y más imposibles en la práctica, porque las toma sobre una cocina que ya no existe.

El chef que sigue bajando a la cocina. También diseña el menú y habla con los clientes —también vive en el comedor—, pero baja a la cocina con regularidad. Prueba los platos, ve el horno viejo, conoce a los cocineros nuevos, sabe qué proveedor está fallando esta semana. Cuando promete un plato "para el viernes", la promesa es real, porque su modelo de la cocina está actualizado. No cocina cada plato —eso lo volvería un cuello de botella—; baja lo suficiente para que su cabeza corresponda a la realidad del fuego.

El primer chef vive en el penthouse. El segundo monta el elevador. Y la diferencia se ve, sobre todo, en sus promesas y estimaciones: el que no baja promete cosas que la cocina no puede dar, y lo descubre tarde y caro; el que baja promete lo que la cocina puede, y acierta. El arquitecto de software es el chef. La cocina es el código. Y esta lección mide, en Mercado, cuánto se despega la estimación de un arquitecto de la realidad a medida que deja de bajar a la sala de máquinas.

Ejemplo trabajado: cómo crece el error de estimación con la distancia al código

Cuando una squad de Mercado propone un cambio, alguien tiene que estimar cuánto esfuerzo cuesta —para priorizar, para prometerle al negocio, para planear—. El arquitecto a menudo es quien da o valida esa estimación. La pregunta de esta lección es: ¿qué tan buena es su estimación según qué tan cerca está del código?

Tomamos cuatro cambios reales de Mercado con su esfuerzo real en días (medido después, ya hechos). Luego modelamos la estimación de un arquitecto a distintas distancias del código: 0 = programa en el repo esta misma semana, 5 = solo ve slides y nunca abre el código. La idea, bien documentada en la práctica, es que mientras más lejos del código, más optimista (irrealmente) se vuelve la estimación —desde el penthouse todo "se ve más fácil" de lo que es abajo—:

# El "elevador del arquitecto" (Hohpe): sube al penthouse (negocio) y baja a la
# sala de maquinas (codigo). Aqui medimos que pasa cuando un arquitecto se queda
# ARRIBA: su estimacion de esfuerzo se despega de la realidad del codigo.
# code_distance: 0 = programa en el repo esta semana; 5 = solo ve slides.
# Para 4 cambios reales de Mercado tenemos el esfuerzo REAL (dias) y estimamos
# el error de un arquitecto a cada distancia (mas lejos = mas subestima).
CHANGES = [
    # (change, actual_days)
    ("add_idempotency_to_payments", 8),
    ("split_catalog_read_model",    13),
    ("async_orders_to_shipping",    21),
    ("cache_catalog_hot_path",      5),
]


def estimate(actual_days, code_distance):
    # Cada nivel de distancia al codigo infla el optimismo ~18%: desde el
    # penthouse todo "se ve mas facil" de lo que es en la sala de maquinas.
    optimism = 1 - 0.18 * code_distance
    return max(1, round(actual_days * optimism))


avg_actual = sum(a for _, a in CHANGES) / len(CHANGES)
print(f"{'code_distance':>13}{'avg_error_days':>16}{'avg_error_pct':>15}")
print("-" * 44)
for distance in range(0, 6):
    errors = [abs(estimate(actual, distance) - actual) for _, actual in CHANGES]
    avg_err = sum(errors) / len(errors)
    pct = round(100 * avg_err / avg_actual)
    print(f"{distance:>13}{avg_err:>16.1f}{pct:>14}%")

print()
print("A distancia 0 (pega el codigo esta semana) el arquitecto acierta; a")
print("distancia 5 (solo slides) se equivoca por mas de la mitad del esfuerzo.")
print("Por eso el arquitecto real baja el elevador a la sala de maquinas.")

Qué esperar. Al correr el archivo, la salida es exactamente esta:

code_distance  avg_error_days  avg_error_pct
--------------------------------------------
            0             0.0             0%
            1             2.0            17%
            2             4.5            38%
            3             6.2            53%
            4             8.5            72%
            5            10.5            89%

A distancia 0 (pega el codigo esta semana) el arquitecto acierta; a
distancia 5 (solo slides) se equivoca por mas de la mitad del esfuerzo.
Por eso el arquitecto real baja el elevador a la sala de maquinas.

Lee la columna de la derecha de arriba abajo, porque es el precio de vivir en el penthouse.

A distancia 0 —el arquitecto pega el código esta misma semana, conoce el estado real de la base de pagos, sabe cómo está el catálogo— su error es 0%. Estima bien porque su modelo mental es la realidad. No hay magia: cuando conoces la cocina, sabes cuánto tarda el plato.

A medida que sube la distancia, el error crece, y no despacio. A distancia 2 —el arquitecto que revisa PRs de vez en cuando pero no toca el código— ya se equivoca en un 38%: un cambio que toma 13 días lo estima en 8, y la squad hereda una promesa imposible. A distancia 5 —el arquitecto que solo ve slides, que no ha abierto el repositorio en meses, que decide sobre el Mercado que recuerda— el error es del 89%: estima que async_orders_to_shipping toma 2 días cuando toma 21. No es que sea tonto; es que su cocina es imaginaria. Desde el penthouse, mover orders a comunicación asíncrona "se ve" como un cambio de configuración; en la sala de máquinas es reescribir cómo dos servicios se hablan, con todo lo que eso arrastra.

Fíjate en la naturaleza del error: siempre es subestimación optimista. El arquitecto despegado del código no se equivoca al azar —a veces de más, a veces de menos—; se equivoca sistemáticamente hacia abajo, prometiendo que las cosas son más fáciles de lo que son. Esto tiene una consecuencia organizacional grave: sus promesas al negocio son irreales, las squads quedan atrapadas entre una fecha imposible y un arquitecto que "ya lo estimó", y cuando el cambio tarda lo que de verdad tarda, la culpa cae sobre quien construye, no sobre quien estimó mal desde arriba. El penthouse promete; la sala de máquinas paga.

Y aquí está la lectura que da nombre a la lección: la calidad de las decisiones del arquitecto es función de su distancia al código. No de su seniority, no de su título, no de lo bonitas que sean sus slides. De si baja el elevador. Un arquitecto brillante a distancia 5 toma peores decisiones que uno promedio a distancia 1, porque el brillante decide sobre un sistema que ya no existe. El contacto con el código no es un lujo nostálgico del arquitecto que "extraña programar"; es la fuente de datos sin la cual sus decisiones flotan.

Como barras, el despegue se ve claro:

Error de estimacion segun distancia al codigo (89% = casi 9x de error)
 dist 0 |                          0%   (pega el codigo: acierta)
 dist 1 |####                     17%
 dist 2 |#########                38%
 dist 3 |#############            53%
 dist 4 |##################       72%
 dist 5 |######################   89%   (solo slides: casi todo error)

Profundización: qué significa "cerca del código" sin volverse cuello de botella

Aquí hay una tensión real que hay que resolver con cuidado, porque este módulo enseña dos cosas que parecen contradecirse: la lección 3 dice "quédate cerca del código" y la lección 6 dirá "no seas el cuello de botella por quien todo pasa". ¿Cómo se sostienen las dos a la vez? La respuesta está en qué tipo de contacto con el código mantiene el arquitecto.

Cerca del código NO significa ser quien más código escribe. Si el arquitecto es el autor de la mitad de los commits, o si toda decisión técnica espera a que él implemente la parte difícil, se volvió el cuello de botella —codea tanto que las squads dependen de él para avanzar—. Eso es tan dañino como el penthouse, solo que por el otro extremo. El arquitecto que escribe todo el código crítico concentra el conocimiento en su cabeza (el bus factor que veremos en el módulo 7) y bloquea a todos.

Cerca del código SÍ significa mantener el modelo mental actualizado. Hay muchas formas de bajar el elevador sin volverse el embudo:

• Leer código con regularidad. No escribir todo, pero sí leer las partes que importan: cómo quedó el nuevo servicio de catalog, cómo orders maneja los reintentos, dónde están los puntos frágiles. Leer mantiene el modelo fresco sin bloquear a nadie.
• Revisar PRs selectivamente. No cada PR (eso es el cuello de botella de la lección 1), sino los que tocan las decisiones de nivel arquitecto: el contrato entre orders y shipping, un cambio en la autenticación compartida. Revisar los pocos que importan da contacto real con el código sin frenar a las squads.
• Hacer un spike de vez en cuando. Cuando hay una decisión grande con incertidumbre técnica —"¿cuánto cuesta de verdad mover orders a asíncrono?"—, el arquitecto puede bajar a construir un prototipo pequeño, con sus propias manos, para sentir el costo real. Es la mejor cura contra la estimación optimista: no adivinas cuánto tarda el plato; lo cocinas una vez.
• Sentarse con las squads en su terreno. Pair programming ocasional, estar en las sesiones de diseño técnico, ver los problemas donde ocurren. El arquitecto que se sienta media hora con la squad de payments a ver el código real de la integración aprende más de lo que diez reuniones de status le dirían.

La prueba práctica: ¿tu estimación le suena creíble a la squad? Una forma rápida de saber a qué distancia estás: cuando das una estimación o describes cómo está el sistema, ¿la squad asiente o intercambia miradas? Si los ingenieros que tocan el código a diario sienten que tu modelo del sistema es real, estás bajando el elevador lo suficiente. Si sienten que hablas de un Mercado que ya no existe —"eso lo cambiamos hace seis meses"—, estás viviendo en el penthouse. Las squads son tu sensor de distancia, y suelen ser honestas si les das permiso de serlo.

Hay una segunda razón, más sutil, para bajar el elevador: la credibilidad. Un arquitecto que conoce el código de verdad se gana el respeto de las squads de una forma que ningún título otorga. Cuando propone una decisión y demuestra que entiende el estado real del sistema —"sé que payments todavía arrastra ese acoplamiento con orders, por eso sugiero esto"—, las squads lo escuchan, porque su palabra corresponde a la realidad que ellas viven a diario. Cuando propone desde el penthouse, con un modelo mental de hace seis meses, las squads lo detectan al instante —"eso ya no es así"— y, aunque no lo digan en voz alta, descuentan todo lo que dice. La autoridad del arquitecto para influir sin mandar (que es el módulo 4) descansa en buena parte sobre esto: el contacto con el código no solo mejora sus estimaciones, sostiene su credibilidad. Un arquitecto en el que las squads confían técnicamente no necesita imponer; uno despegado del código pierde la única moneda que le quedaba —la razón—.

Una nota para no sobre-corregir: la respuesta a "vive muy lejos del código" no es "que vuelva a ser un desarrollador de tiempo completo". El arquitecto tiene trabajo en el penthouse que nadie más hace —traducir el negocio, alinear las squads, sostener los atributos de calidad— y renunciar a él para codear a tiempo completo también rompe el rol. El objetivo es el elevador: moverse entre pisos, no instalarse en uno. Un arquitecto que solo codea es un ingeniero senior con un título raro; uno que solo hace slides es un consultor sin contacto con la realidad. El oficio es el viaje entre los dos.

Errores comunes

Creer que ser senior significa estar por encima del código. Qué pasa: el arquitecto trata programar como una tarea de junior de la que "ya se graduó", y llena su semana de reuniones y documentos sin abrir el repositorio. Por qué pasa: muchas culturas organizacionales premian el alejamiento del trabajo técnico como señal de estatus —"ya no ensucia las manos"—, confundiendo altura con distancia. Cómo detectarlo: si el arquitecto no ha leído código ni revisado un PR en semanas, y sus descripciones del sistema chocan con lo que las squads saben ("eso ya no es así"), está por encima del código, no al mando de él. Cómo corregirlo: reservar tiempo recurrente y protegido para bajar el elevador —leer código, revisar los PRs de nivel arquitecto, hacer un spike— y tratarlo como parte central del rol, no como una regresión. El contacto con el código es lo que mantiene reales las decisiones; sin él, la seniority solo agranda el error.

Estimar desde el penthouse y hacer que la sala de máquinas pague. Qué pasa: el arquitecto promete al negocio una fecha basada en cómo "se ve" el cambio desde arriba, la squad hereda una promesa imposible, y cuando el trabajo tarda lo que de verdad tarda, la squad carga con el incumplimiento. Por qué pasa: la distancia al código produce subestimación optimista sistemática (el 89% del ejemplo), y como la estimación viene "del arquitecto", nadie la cuestiona. Cómo detectarlo: si las estimaciones del arquitecto son consistentemente menores que el esfuerzo real, y las squads viven apagando el fuego de fechas que no pusieron, el arquitecto estima desde el penthouse. Cómo corregirlo: no estimar cambios técnicos sin contacto reciente con el código —o mejor, no estimar solo: pedir la estimación a quien toca el código y usar el rol de arquitecto para validarla y comunicarla, no para inventarla desde arriba—. Cuando el arquitecto sí quiere una lectura propia, un spike de medio día vale más que una intuición de penthouse.

Sobre-corregir y volverse el que escribe todo el código crítico. Qué pasa: al oír "el arquitecto debe estar cerca del código", el arquitecto se lanza a implementar personalmente cada parte difícil, y ahora toda decisión técnica espera a que él escriba la solución. Por qué pasa: confunde "cerca del código" con "autor del código", el error opuesto a la torre de marfil. Cómo detectarlo: si el arquitecto es el autor de una fracción enorme de los commits críticos, o si las squads se bloquean esperando que él implemente lo difícil, se volvió un cuello de botella técnico. Cómo corregirlo: cambiar el tipo de contacto —leer, revisar los pocos PRs que importan, hacer spikes acotados, pair ocasional— en vez del volumen. El objetivo es el modelo mental actualizado, no la autoría. Un arquitecto que escribe todo el código crítico conoce el sistema perfectamente y, aun así, hace daño: concentra el conocimiento y bloquea al equipo (justo la trampa de la lección 6).

Ejercicios

Ejercicio 1 — ¿A qué distancia estás? Para cada uno de estos arquitectos de Mercado, ubica su code_distance aproximada (0 a 5) y predice si sus estimaciones serán realistas u optimistas irreales: (a) revisa los PRs del contrato orders/shipping cada semana y hizo un spike del cache de catálogo el mes pasado; (b) no abre el repositorio desde hace ocho meses, pero está en todas las reuniones de estrategia; (c) escribe personalmente la mitad de los commits del servicio de payments; (d) lee código nuevo cuando puede y se sienta con las squads en sus sesiones de diseño, sin escribir mucho él mismo.

Ver solución

• (a) Distancia ~1. Contacto regular y selectivo (revisa los PRs que importan) más un spike reciente: su modelo mental está fresco. Estimaciones realistas (error ~17% o menos). Es un buen uso del elevador: baja a lo que importa sin bloquear.
• (b) Distancia ~5. Ocho meses sin código, viviendo en el penthouse de la estrategia. Estimaciones optimistas irreales (error ~89%): decide sobre un Mercado que ya no existe. Es el caso puro de la lección —brillante en la reunión, equivocado en el número—.
• (c) Distancia ~0 en conocimiento, pero es el error opuesto. Su modelo mental es perfecto (escribe el código), así que estimaría bien; el problema es que se volvió el cuello de botella de payments —la squad depende de sus commits—. "Cerca del código" no era esto: era mantener el modelo actualizado sin ser el autor de todo. Distancia baja, pero patología de la lección 6.
• (d) Distancia ~1-2, y es el ideal. Lee, se sienta con las squads, no escribe mucho: modelo mental fresco sin bloquear a nadie. Es exactamente el elevador bien montado —cerca del código sin ser cuello de botella—. Estimaciones realistas.

Ejercicio 2 — El spike como cura del optimismo. El negocio le pide al arquitecto una fecha para async_orders_to_shipping. El arquitecto lleva meses sin tocar ese código y su instinto le dice "unos 3 días". Sabiendo lo que muestra el ejemplo, ¿qué debería hacer antes de dar la fecha, y por qué eso vale más que "estimar mejor desde el escritorio"?

Ver solución

Debería hacer un spike: bajar a la sala de máquinas y construir, con sus propias manos, un prototipo pequeño del cambio —conectar orders a shipping de forma asíncrona en una rama de prueba, solo para el camino feliz—. En medio día de spike va a chocar con lo que desde el escritorio no se ve: cómo orders maneja hoy la respuesta síncrona de shipping, qué pasa con los pedidos en vuelo, cuántos lugares del código asumen la respuesta inmediata. Ese contacto convierte su "3 días" optimista en una estimación anclada a la realidad (que el ejemplo sugiere cerca de 21).

Por qué el spike vale más que "estimar mejor desde el escritorio": el error de la estimación de penthouse no es de cálculo —no es que sume mal— es de información. Su modelo mental está desactualizado, así que ningún esfuerzo de "pensarlo más" desde el escritorio lo va a arreglar; solo puede refinar una imagen equivocada. El spike no mejora el cálculo; reemplaza la imagen imaginaria por la real. Cocinas el plato una vez y dejas de adivinar cuánto tarda. Es la aplicación directa de "baja el elevador": ante una decisión grande con incertidumbre técnica, el arquitecto no adivina desde arriba, baja y toca. (Cómo estructurar ese spike como experimento formal es la guía hermana; que hay que bajar a hacerlo es esta lección.)

Ejercicio 3 — Resolver la tensión con la lección 6. Un colega te dice: "no entiendo, la lección 3 dice que el arquitecto esté cerca del código y la lección 6 dirá que no sea el cuello de botella; parecen contradecirse". Explica por qué no se contradicen, usando la distinción entre tipo y volumen de contacto con el código.

Ver solución

No se contradicen porque hablan de dos cosas distintas: la lección 3 es sobre el tipo de contacto (mantener el modelo mental actualizado) y la lección 6 es sobre el volumen de trabajo que pasa por el arquitecto (no ser el embudo).

"Cerca del código" bien entendido es contacto de lectura y muestreo: leer el código que importa, revisar los pocos PRs de nivel arquitecto, hacer un spike ocasional, sentarse con las squads. Nada de eso bloquea a nadie —las squads siguen decidiendo y construyendo lo suyo—; solo mantiene la cabeza del arquitecto pegada a la realidad. Es de bajo volumen y alto valor informativo.

El cuello de botella de la lección 6 es otra cosa: es cuando el arquitecto se vuelve quien produce o aprueba el trabajo —escribe todo el código crítico, revisa cada PR, decide cada cosa—, y entonces las squads esperan por él y la cola crece. Es de alto volumen y bloqueante.

La distinción práctica: puedes estar a code_distance 1 (modelo mental fresco) sin ser el cuello de botella, si tu contacto es leer y muestrear en vez de producir y aprobar todo. De hecho, ese es exactamente el arquitecto ideal —el caso (d) del ejercicio 1—: cerca del código, lejos del embudo. Los dos errores opuestos son vivir en el penthouse (distancia 5, mala información) y escribir todo el código crítico (distancia 0, pero cuello de botella). El oficio está en el punto medio: bajar lo suficiente para saber, sin producir tanto que todos dependan de ti.

Resumen y siguiente paso

En esta lección desarmaste la segunda imagen falsa del rol: el arquitecto despegado del código que decide desde el penthouse sobre un sistema que ya no existe. Viste, con el chef que dejó de entrar a la cocina, que las promesas y estimaciones del que no baja se vuelven irreales, y con el elevador de Hohpe entendiste que el trabajo del arquitecto es moverse entre pisos, no instalarse arriba. Y lo mediste: el error de estimación crece con la distancia al código —de 0% pegado al repo a 89% a punta de slides— y es siempre optimismo sistemático, así que el penthouse promete y la sala de máquinas paga. La calidad de las decisiones del arquitecto es función de su distancia al código, no de su título.

Antes de avanzar deberías poder: explicar la metáfora del elevador y por qué el arquitecto vive en el viaje, no en un piso; distinguir "cerca del código" (mantener el modelo mental fresco por lectura y muestreo) de "escribir todo el código" (el cuello de botella); y proponer un spike como cura del optimismo de penthouse ante una estimación incierta.

La lección 4 da el siguiente paso: ya que el arquitecto está presente (lección 2) y cerca del código (lección 3), ¿cuál es exactamente su producto? La respuesta va a sorprender: no es "la decisión correcta". Es una decisión cuya equivocación sea barata —reversible— más el porqué comunicado. Vamos a ejecutar por qué, bajo incertidumbre alta, abaratar el error le gana a intentar acertar, y por qué el arquitecto no vende certezas: vende opciones que se pueden deshacer.

Recursos

• Gregor Hohpe, The Software Architect Elevator (O'Reilly, 2020) — la fuente de la metáfora central de esta lección. El arquitecto conecta el penthouse del negocio con la sala de máquinas del código; el que se queda arriba pierde el contacto que hace reales sus decisiones. En inglés.
• Gregor Hohpe, "The Architect Elevator" — architectelevator.com. El sitio del autor con ensayos que amplían el libro, incluido por qué el arquitecto no debe "vivir en el penthouse". En inglés.
• Mark Richards y Neal Ford, Fundamentals of Software Architecture, 2ª ed. (O'Reilly, 2020), cap. 2 — sobre mantener la profundidad técnica ("technical breadth" y el contacto con el código) como parte del rol, no como un lujo. En inglés.
• Martin Fowler, "Who Needs an Architect?" (IEEE Software, 2003) — martinfowler.com/ieeeSoftware/whoNeedsArchitect.pdf. Fowler insiste en que el arquitecto valioso está inmerso en el proyecto y programa con el equipo, no lo dirige desde afuera. En inglés.