Curso completo · No. 03

Un curso para el ingeniero que ya sabe escribir código pero quiere aprender a tomar decisiones arquitectónicas, explicárselas al equipo y al negocio, y ver el sistema entero.

24 módulos · trade-offs en lugar de dogmas · vocabulario profesional en lenguaje claro

Módulos detallados
§ 01

Un arquitecto no se distingue de un senior engineer porque sepa más tecnologías. Se hace cargo de las consecuencias de las decisiones a lo largo del tiempo.

El arquitecto piensa con un horizonte de años

El ingeniero construye un puente por el que mañana pasará un coche. El arquitecto pregunta qué pasa cuando empiecen a cruzar camiones, cuando levanten un barrio nuevo al lado y cuando la reparación cueste más que el propio puente.

Un ingeniero suele resolver la tarea tal como está planteada. El arquitecto primero verifica si la tarea está bien planteada. No es esnobismo ni ganas de "hablar de cosas elevadas". Es que una decisión arquitectónica suele ser más cara de cambiar que una línea de código.

El cambio principal en la cabeza: dejas de preguntar sólo "cómo hago X" y empiezas a preguntar "para qué hace falta X, qué alternativas hay, qué vamos a perder y cómo se va a ver esta decisión dentro de tres años".

La responsabilidad del arquitecto no es el código, es la forma del sistema

Si el carpintero se equivoca al colgar un estante, se puede mover. Si el proyectista se equivoca con un muro de carga, la casa va a convivir con ese error durante décadas.

El arquitecto no está obligado a tomar personalmente cada decisión técnica. Pero sí está obligado a ser dueño de las decisiones que fijan la forma del sistema: boundaries entre servicios, modelo de datos, protocolos de integración, estrategia de escalado, seguridad, observability, camino de migración.

Aquí conviene distinguir entre reversible decisions e irreversible decisions. Una decisión reversible se puede cambiar en un día o una semana: una librería de logging, el color de un botón, la estructura interna pequeña de un módulo. Una decisión irreversible o cara de revertir cambia la trayectoria del sistema: la base de datos, el modelo de tenancy, un contrato de API, la forma de almacenar eventos, los boundaries de los servicios.

Las preguntas del arquitecto
  • ¿Qué problema estamos resolviendo en realidad? - ¿Qué cambia si la carga crece 10x? - ¿Qué decisiones aquí son reversibles y cuáles casi no? - ¿Quién va a mantener esto dentro de un año?

El arquitecto no construye "el sistema más correcto" — construye un sistema que aguanta la realidad.

§ 02

En arquitectura no hay decisiones gratis. Toda elección compra una propiedad al precio de otra.

Una best practice sin contexto es un mal consejo

Una camioneta 4x4 le gana al sedán en un camino de barro. El sedán le gana a la camioneta en la ciudad. La bicicleta le gana a ambos si tienes que recorrer tres cuadras y no hay dónde aparcar.

Una decisión arquitectónica no se puede evaluar fuera de contexto. REST, GraphQL, Kafka, PostgreSQL, Kubernetes, microservicios, monolito — todo eso son herramientas con un precio. Un trade-off es un intercambio consciente: latency contra throughput, consistency contra availability, time-to-market contra maintainability, simplicidad contra flexibilidad.

El arquitecto no dice "Kafka es mejor que RabbitMQ". Dice: "necesitamos orden de eventos por clave, throughput alto, replay y un log durable; a cambio pagamos la complejidad operativa de Kafka". Así suena el lenguaje profesional.

La complejidad es un impuesto

Cada nueva abstracción es como una habitación más en la casa. La habitación puede ser útil, pero hay que limpiarla, calentarla, repararla y explicarle a las visitas para qué existe.

La complejidad es útil cuando compra una propiedad importante: aislamiento de fallos, release independiente, seguridad, escalado, testability. Pero la complejidad "por si acaso, para el futuro" suele convertirse en un impuesto permanente.

Los términos over-engineering y under-engineering sólo sirven juntos. Over-engineering: la complejidad apareció antes del dolor real. Under-engineering: el sistema ya se chocó con sus límites y la arquitectura no dejó margen para crecer. El trabajo del arquitecto no es elegir un extremo — es sostener el medio.

Lecturas recomendadas
  • Architecture: The Hard Parts — Ford, Richards, Sadalage, Dehghani
  • Software Architecture in Practice — Bass, Clements, Kazman
  • Martin Fowler: Is Design Dead?
§ 03

La deuda técnica no siempre es mala. Lo malo es la deuda que se toma por accidente, no se anota y nadie piensa devolver.

La deuda es un préstamo, no basura

Un préstamo para equipamiento puede acelerar al negocio. Un préstamo para una fiesta sólo deja resaca e intereses.

La technical debt es una decisión que nos acelera ahora pero crea un costo futuro de cambio. A veces eso es lo correcto: hay que probar el mercado, llegar a la deadline, no perder al cliente. El problema empieza cuando el equipo etiqueta como deuda cualquier cosa: código feo, falta de tests, dependencias caóticas, librerías viejas.

Un modelo útil es el cuadrante de Martin Fowler: deliberate / inadvertent y prudent / reckless. Deuda consciente y razonable: "no hacemos multi-region por ahora porque tenemos 200 usuarios y un solo mercado". Deuda inconsciente e imprudente: "no sabíamos que necesitábamos transacciones".

La deuda cobra intereses

Si la calle está rota, cada viaje te lleva cinco minutos más. Al mes ya no es un bache: es un impuesto a toda la ciudad.

Los intereses de la deuda técnica son la ralentización de cada cambio siguiente. Cuanto más toca el equipo una zona, más cara sale la deuda. Por eso la deuda en el dominio caliente es más peligrosa que la deuda en un admin panel que nadie toca.

El arquitecto negocia una estrategia de pago: qué consideramos deuda exactamente, qué riesgo crea, cuándo revisamos la decisión, qué señal nos dice "es momento de pagar". Sin eso, la "deuda técnica" se vuelve un argumento emocional, no un instrumento gestionable.

Preguntas para una revisión de deuda
  • ¿Dónde quedó anotado por qué aceptamos este compromiso?
  • ¿Qué interés estamos pagando cada sprint?
  • ¿Qué tendría que pasar para que esta deuda se convierta en un blocker?
  • ¿Hay un plan de pago, o al menos un trigger para revisarlo?
§ 04

Un sistema que nadie puede sostener en la cabeza se va a romper incluso con buenos ingenieros.

La arquitectura tiene que entrar en una cabeza humana

El mapa del metro es útil no porque muestre cada tornillo del túnel. Muestra las líneas, los trasbordos y la dirección del viaje. Con eso alcanza para tomar una decisión.

El cognitive load es la carga mental que el sistema le exige al ingeniero. Está el intrinsic load: la complejidad del propio dominio. Está el extraneous load: complejidad extra que viene de una mala arquitectura, conexiones no obvias, excepciones accidentales y magia. El arquitecto no puede eliminar la complejidad del negocio, pero está obligado a reducir la complejidad accidental.

Un buen módulo se entiende por separado. Un buen bounded context tiene su propio lenguaje y sus propios invariantes. Un buen equipo es dueño de un área que le entra en la cabeza.

La Conway's Law no es un chiste

Si tres áreas no se hablan entre sí, su producto casi siempre se ve como tres productos pegados en un mismo menú.

La Conway's Law dice: la organización diseña sistemas parecidos a la estructura de comunicación interna de la organización. Si los boundaries arquitectónicos no coinciden con los boundaries de los equipos, el equipo va a estar todo el tiempo cruzando territorio ajeno.

Team Topologies introduce etiquetas útiles: stream-aligned team, platform team, enabling team, complicated-subsystem team. No es moda de HR — es una herramienta arquitectónica. A veces la descomposición correcta del sistema empieza por la descomposición correcta de la responsabilidad.

§ 05

Un sistema grande se vuelve manejable sólo cuando lo puedes cortar por los boundaries correctos.

Se puede cortar por capas, por dominios o por flujo de datos

El carnicero no corta la res a lo loco — corta por las articulaciones. Una buena descomposición también busca puntos naturales de ruptura.

Descomponer no es "ordenar en carpetas". Es elegir dónde termina la responsabilidad. High cohesion significa que todo lo que hay dentro de un componente trata de una misma cosa. Low coupling significa que el componente sabe poco sobre otros componentes.

Un corte horizontal te da capas: UI, application, domain, infrastructure. Un corte vertical te da features o bounded contexts: billing, identity, catalog, comments. Los sistemas reales necesitan ambos, pero mezclar uno con el otro es peligroso.

Un mal boundary se delata con los cambios

Si para cambiar el grifo de la cocina tienes que desarmar el dormitorio, el problema no es el grifo.

Una señal de mala descomposición: un cambio chico se desparrama por cinco módulos. Otra señal: un mismo módulo cambia por razones distintas — hoy por producto, mañana por la base, pasado por una integración.

El término DDD bounded context sirve justo aquí. Es un boundary dentro del cual las palabras tienen un único significado. "Customer" en billing y "Customer" en support pueden ser modelos distintos. Forzarlos a ser uno suele producir un modelo "universal" frágil.

§ 06

La lógica de negocio debe depender de reglas de negocio, no del framework, la base de datos o HTTP.

Las dependencias deben fluir hacia el centro

Los cimientos no deberían depender del color de las cortinas. Si dependen, la casa se diseñó al revés.

Clean Architecture, Hexagonal Architecture y Onion Architecture dicen lo mismo: la lógica importante va en el centro, los detalles afuera. HTTP, SQLAlchemy, Next.js, Kafka, Redis, Stripe — eso son detalles. Importan, pero no deben definir las reglas de negocio.

El Dependency Inversion Principle dice: la lógica de alto nivel depende de abstracciones, y las implementaciones se enchufan desde afuera. En código se ve como ports and adapters: el service recibe un PaymentGatewayProtocol, no construye un StripeClient por dentro.

La abstracción no existe para verse linda, existe para absorber el cambio

El adaptador va donde los enchufes son realmente distintos. Si pones un adaptador en cada toma sólo porque te gustan los adaptadores, la casa se vuelve menos segura.

No toda clase necesita una interfaz. Pero todo lo que toca el mundo exterior, el tiempo, la aleatoriedad, la red, el file system o la base de datos tiene que ser reemplazable en tests. Si no, no estás testeando lógica de negocio — estás levantando un mini production system dentro de un unit test.

El precio de una capa son más archivos y más palabras. El pago es testability, infraestructura intercambiable, boundaries claros. Si no hay pago, la capa sobra.

§ 07

Una API es una promesa. Romper una promesa es fácil; recuperar la confianza del cliente es difícil.

El contrato importa más que el transporte

Migraciones no le presta atención a la marca de la puerta. Lo que importa es qué documentos se aceptan, qué reglas aplican y qué pasa cuando algo está mal.

REST, GraphQL, gRPC y WebSocket son distintas formas de hablar. REST encaja con APIs resource-oriented y caching simple. GraphQL ayuda cuando distintos clientes necesitan distintas formas de lectura. gRPC sirve para comunicación typed service-to-service. WebSocket es para eventos en tiempo real en dos direcciones.

La elección del transporte es secundaria. Lo principal es el contrato: schema, errores, idempotency, versionado, backward compatibility, deprecation policy.

Idempotency te salva del mundo real

Si pulsas diez veces el botón del ascensor, no debería venir y volver diez veces. Debería entender que la intención es una sola.

Idempotency significa que repetir una operación da el mismo efecto final. En sistemas en red los reintentos son inevitables: timeouts, retries, webhooks duplicados, worker restarts. Si crear un pago, un pedido o un mensaje no es idempotente, el sistema tarde o temprano va a hacer algo de más.

El arquitecto diseña la idempotency a nivel del contrato: idempotency key, unique constraints, retries seguros, estados claros.

§ 08

El código se reescribe. Los datos migran durante años. Por eso el modelo de datos es una de las decisiones arquitectónicas más caras.

Los datos viven más que las aplicaciones

La fachada del edificio se puede repintar en una semana. Unos cimientos mal vertidos te van a estar recordando su error durante toda la vida del edificio.

El lenguaje, el framework y la UI pueden cambiar varias veces. Pero las tablas, los eventos, las keys, las relaciones y los registros históricos se quedan. Un error en el modelo de datos suele convertirse en un error de todas las versiones futuras del producto.

La normalización reduce duplicación y el riesgo de drift. La desnormalización acelera las lecturas y simplifica el read model. Los sistemas OLTP están optimizados para transacciones, los OLAP para analítica. No se puede diseñar un único modelo como si fuera a resolver perfectamente las dos clases de carga.

Event sourcing es una herramienta potente, no una religión

El extracto bancario no guarda sólo el saldo actual — guarda el historial de operaciones. Por eso puedes explicar de dónde salió el saldo.

Event sourcing guarda los cambios como una secuencia de eventos y reconstruye el estado actual a partir de ellos. Sirve cuando importan la historia, el audit, recuperar estado o el replay. El precio es alto: schema evolution de los eventos, complejidad de queries, eventual consistency, tooling exigente.

CQRS separa el write model y el read model. Puede simplificar muchísimo sistemas de lectura complejos, pero suma sincronización y lag. Meter CQRS sólo porque "suena arquitectónico" es una forma cara de convertir un problema en dos.

§ 09

El estado es complejidad que vive en algún lado. Cuantas más copias de la verdad, más formas hay de equivocarse.

Single source of truth no significa una sola base de datos

En una empresa puede haber muchos reportes, pero tiene que haber un único registro oficial de sueldos. Si no, el día de pago se vuelve teatro.

Single source of truth significa que, para cada hecho importante, sabes dónde vive la versión autoritativa. Un cache, un search index, una read replica, una materialized view — son copias derivadas. Pueden ser útiles, pero no deberían hacerse pasar por la verdad primaria.

Los componentes stateful sostienen estado y exigen cuidado: transacciones, locking, recovery, backup. Los componentes stateless son más fáciles de escalar y reemplazar, pero siguen dependiendo de un estado que vive en otro lado.

Un cache es una segunda verdad que a veces miente

El horario pegado en la nevera es cómodo, hasta que alguien mueve la reunión en el calendario del teléfono.

Un cache compra velocidad al precio de la frescura. La pregunta más difícil del cache no es "cómo meter cosas", es "cuándo invalidar". TTL, explicit invalidation, write-through, write-behind, cache-aside — son compromisos distintos entre complejidad, frescura y carga.

Una race condition aparece cuando dos operaciones compiten por un estado. El optimistic locking dice: "los conflictos son raros, verificamos la versión al escribir". El pessimistic locking dice: "los conflictos son peligrosos, bloqueamos por adelantado". Los dos son correctos bajo condiciones distintas.

§ 10

La distribución resuelve problemas de escala, pero crea problemas de tiempo, orden y confianza en la red.

La red no es un cable, es una fuente de incertidumbre

El monolito es una conversación en una sola habitación. Un sistema distribuido es correspondencia entre personas en distintos husos horarios — las cartas a veces se pierden, llegan dos veces o llegan tarde.

En un sistema distribuido no puedes "llamar a una función" y ya. Entre los servicios hay red, timeouts, retries, partial failure, distintos relojes, distintas versiones de código. Lo que en el monolito era una transacción local, se convierte en un protocolo de coordinación.

El CAP theorem se resume mal con frecuencia. La versión útil en la práctica: durante un network partition eliges entre consistency y availability. PACELC añade: incluso sin partition, sigues eligiendo entre latency y consistency.

La consistency tiene sabores

Dos personas mirando el mismo Google Doc ven lo mismo casi al instante. Dos personas mirando una transferencia bancaria no pueden conformarse con "casi".

La strong consistency te da verdad fresca, pero cuesta latency y availability. La eventual consistency tolera un desfase temporal, pero suele escalar mejor. La causal consistency conserva la causalidad: si el evento B depende de A, B no debe ser visible antes que A.

El saga pattern descompone una transacción de negocio larga en pasos con compensating actions. El two-phase commit te da atomicidad entre recursos, pero es caro y frágil en sistemas distribuidos reales. El arquitecto no elige el modelo "más estricto", elige el suficiente para el riesgo.

§ 11

Los microservicios no curan un mal diseño. Convierten problemas locales en problemas distribuidos.

El monolito modular está casi siempre subestimado

Un depósito bien organizado es más rápido que diez depósitos chicos si el mismo repartidor va y viene entre ellos.

Monolito no es un insulto. Un mal monolito es una bola de dependencias sucias. Un buen modular monolith tiene boundaries internos estrictos, dominios separados, interfaces explícitas y una sola deployment unit. Para un equipo chico suele ser el mejor punto de partida.

Los microservicios ayudan cuando necesitas releases independientes, equipos autónomos, distintos scaling profiles, aislamiento de fallos o stacks tecnológicos distintos. Pero el precio: network calls, observability, distributed transactions, overhead de DevOps, versionado, security entre servicios.

Un distributed monolith es lo peor de los dos mundos

Es como vivir en apartamentos separados, pero ir al de al lado por cada cuchara.

Un distributed monolith parece microservicios, pero los servicios no son autónomos: database schema compartida, cadenas síncronas de llamadas, releases que sólo salen juntos, cambios que obligan a tocar a todos. El equipo paga el costo de la distribución sin recibir la independencia.

El Strangler Fig pattern permite migrar con cuidado: envolvemos el sistema viejo, extraemos capabilities de a poco, cortamos por boundaries de negocio reales, no por tablas.

§ 12

Sync acopla a los sistemas en el tiempo. Async rompe ese acople, pero trae demoras, duplicados y complejidad de orden.

Una llamada telefónica requiere que los dos estén libres ahora. Una carta se puede leer después — pero puede perderse, llegar tarde o exigir respuesta.

Un request síncrono es fácil de razonar: mandas, recibes la respuesta. Pero si el receptor está lento o caído, el que manda sufre. La asincronía vía queue o pub/sub te deja sobrevivir a fallos y picos de carga, pero exige otro modelo mental.

Una queue normalmente reparte trabajo entre consumers. Pub/sub transmite un evento a muchos suscriptores. Kafka, RabbitMQ, SQS, Redis Streams — herramientas distintas con modelos distintos de ordering, durability, replay y operations.

Exactly-once casi siempre es marketing

Si la carta se mandó dos veces, una contabilidad decente no debería pagar dos veces el sueldo.

En la práctica diseñas para at-least-once delivery más un consumer idempotente. El mensaje puede llegar dos veces; el handler tiene que sobrevivirlo. La dead letter queue es para mensajes que no se pudieron procesar después de un número razonable de intentos.

Backpressure es la señal "el receptor no llega". Sin ella, el sistema acepta todo con elegancia y después se muere por dentro.

§ 13

"Que sea rápido" no es un requisito. Un requisito suena como latency, throughput, percentiles y un perfil de carga.

El tiempo de respuesta promedio casi siempre miente

Si nueve personas recibieron su comida en un minuto y la décima esperó una hora, el promedio se ve tolerable. La décima no está de acuerdo.

Latency es la demora de una operación. Throughput es cuántas operaciones hace el sistema por unidad de tiempo. Los percentiles muestran la distribución: p50 es la mediana, p95 significa que el 95% de los requests son más rápidos que ese valor, p99 es la cola.

El usuario no siente el promedio — siente la cola. La tail latency importa especialmente en sistemas donde una pantalla depende de varias llamadas a backend: la probabilidad de una respuesta lenta se acumula.

Perfilar antes de optimizar

Arreglar performance sin un profile es como tratar a un paciente desde la foto de sus zapatos.

Primero medir, después optimizar. N+1 queries, round trips de más, un mal índice, serialización, lock contention, GC pause, cache frío — todos se ven como "lento", pero se curan distinto.

La Amdahl's Law te recuerda: la aceleración está acotada por la parte del sistema que realmente optimizas. La Little's Law ayuda a pensar en colas: más latency con el mismo throughput significa más work-in-progress sentado adentro del sistema.

§ 14

La escalabilidad es la capacidad de crecer en carga y en funciones sin reconstruir el sistema desde cero.

Vertical y horizontal scaling compran cosas distintas

Puedes comprar un camión grande. Puedes comprar diez chicos. El primero es más simple, los segundos son más flexibles — pero requieren un despachador.

Vertical scaling es hacer una máquina más fuerte. Simple, mientras haya techo. Horizontal scaling es sumar más instancias. Más flexible, pero requiere un application layer stateless, load balancing, una estrategia de shared state y observability.

Las bases escalan más difícil que las aplicaciones. Las read replicas ayudan a las lecturas, no a las escrituras. El sharding parte los datos pero te obliga a elegir un shard key. Un mal shard key convierte el escalado en un desbalance de carga.

Escalar funciones importa tanto como escalar carga

Una ciudad no crece sólo en población. Crece en escuelas, hospitales, calles y reglas.

El sistema tiene que absorber no sólo más traffic, sino más product surface. Si cada nueva feature requiere reescribir un God-service compartido, el sistema no escala organizacionalmente.

El scaling cube es un modelo útil: eje X es clonación, eje Y es partir por función, eje Z es partitioning por datos o por tenants.

§ 15

Un sistema fiable no es uno donde no se rompe nada. Un sistema fiable sabe qué hacer cuando algo se rompe.

Un retry sin estrategia es un ataque a ti mismo

Si la puerta no se abre, golpear una vez es razonable. Golpear mil veces por segundo ya es un problema para la puerta y para los vecinos.

El retry es para transient failures. Pero los retries necesitan un límite, un timeout, exponential backoff y jitter. Si no, un fallo parcial se transforma en un retry storm.

Un circuit breaker corta temporalmente las llamadas a una dependency atascada. El bulkhead pattern aísla recursos: si un downstream se muere, no se lleva con él todos los worker threads y todos los connection pools.

Los SLO convierten la fiabilidad en un contrato

"Vamos a hacer lo posible" no es un horario de trenes. El horario dice qué cuenta como normal y qué cuenta como fallo.

El SLI es lo que mides: success rate, latency, frescura. El SLO es el objetivo: 99,9% de requests exitosos en 30 días. El SLA es una promesa al cliente con consecuencias atadas.

El error budget te dice cuánta no-fiabilidad puedes gastar. Si el budget se quemó, el equipo deja de perseguir features y arregla la fiabilidad. Es la versión en lenguaje de negocio de la calidad de ingeniería.

§ 16

La seguridad no se puede agregar antes del release. Tiene que estar metida en el modelo de acceso, en los datos, en la infraestructura y en los procesos.

Authentication y authorization son cosas distintas

El pasaporte demuestra quién eres. El boleto demuestra dónde puedes entrar. Uno no reemplaza al otro.

Authentication responde a "¿quién es esto?". Authorization responde a "¿qué se le permite hacer?". Confundirlos es peligroso: un usuario puede estar bien logueado y aun así no tener derecho a leer el invoice de otro.

RBAC otorga permisos a través de roles. ABAC considera atributos: dueño del recurso, tenant, región, estado del objeto. La auth basada en sesión es más fácil de revocar; el JWT es más fácil de verificar sin base de datos, pero más difícil de revocar. La elección depende de las amenazas y del lifecycle.

El threat modeling es paranoia profesional

Un buen arquitecto piensa como un atacante no porque desconfíe de las personas, sino porque confía en la realidad.

STRIDE te ayuda a buscar amenazas: spoofing, tampering, repudiation, information disclosure, denial of service, elevation of privilege. Defense in depth significa varias capas de protección: input validation, authz, encryption, audit log, rate limiting, least privilege.

Secrets management no es "meter la key en el env y olvidarse". Hay que entender rotation, accesos, audit, blast radius y qué pasa cuando hay una filtración.

§ 17

No se puede arreglar lo que no se ve. El sistema tiene que explicar su propio estado sin que haya que hacer arqueología en el código.

Monitoring te dice qué está mal. Observability te ayuda a entender por qué

La luz de "check engine" es útil, pero el mecánico igual necesita sensores, historia y herramientas de diagnóstico.

Los tres pilares de la observability: logs, metrics, traces. El structured logging hace los logs queryable. Las metrics muestran agregados. El distributed tracing sigue el camino de un request a través de los servicios.

Un correlation ID es una cosita chica que salva noches: un mismo request id atraviesa el gateway, el service, la queue, el worker y el downstream.

Hay que alertar sobre síntomas

Al usuario le da igual que la CPU esté al 92%. Le importa que el checkout no funciona.

Una buena alerta habla de dolor del usuario: error rate, latency, failed payments, stale data. Una mala alerta habla de una causa que puede ser perfectamente normal. Si las alertas hacen ruido, el equipo deja de creerles.

Un runbook responde a "qué hacer a las 03:00". Un post-mortem responde a "cómo hacemos para que esto no se repita". Sin culpar; el objetivo es mejorar el sistema, no encontrar al culpable.

§ 18

Una decisión arquitectónica que no se escribió desaparece junto con el contexto de su autor.

Un ADR le gana a la memoria

Un acuerdo verbal funciona hasta las primeras vacaciones, la primera renuncia o la primera discusión seis meses después.

Un Architecture Decision Record registra contexto, decisión, alternativas y consecuencias. Un ADR no tiene que ser una novela. Un buen ADR responde: qué problema estábamos resolviendo, qué elegimos, por qué no elegimos lo otro, cuándo lo revisamos.

La documentación no está para el audit — está para el próximo cambio. Un ingeniero nuevo tiene que entender no sólo "cómo", sino también "por qué".

Un diagrama es una herramienta de trabajo, no un adorno

El mapa del metro no muestra los cables ni los tornillos. Muestra las líneas y los trasbordos. Con eso alcanza para no perderse.

El C4 model te da cuatro niveles: Context, Container, Component, Code. Con los primeros tres normalmente alcanza. Un sequence diagram sirve cuando importa el orden de la interacción. UML entera rara vez se necesita; diagramas sueltos, sí.

La living documentation vive al lado del código, se actualiza en el PR y pasa por review. Un documento en una wiki abandonada se convierte rápido en ficción histórica.

§ 19

El arquitecto habla con ingenieros, producto, negocio, seguridad y legal. Cada audiencia escucha un lenguaje distinto.

Traducir el riesgo al lenguaje de la audiencia

El médico no le habla al paciente sólo en latín. Le explica qué va a doler, cuánto dura el tratamiento y qué no debe hacer.

A un ingeniero le puedes decir: "no tenemos idempotency en el payment callback". Al negocio hay que decirle: "si el webhook se repite, podemos cobrar dos veces o enviar el producto dos veces; es un riesgo financiero y reputacional".

El stakeholder mapping te ayuda a ver a quién le importa qué: a producto le importa time-to-market, a seguridad la reducción de riesgo, a finanzas costos predecibles, a soporte un comportamiento entendible, a ingeniería la maintainability.

Un RFC baja la temperatura de una discusión

Una discusión frente al pizarrón suele ganarla el más fuerte. Una propuesta escrita obliga a que los argumentos se sostengan separados de la voz.

Un RFC describe el problema, las restricciones, las opciones, la solución elegida, los riesgos y el plan de rollout. Un buen RFC invita a la crítica antes de que la decisión se convierta en política.

Disagree and commit funciona sólo después de una discusión honesta. Si al equipo no lo escucharon, eso no es commit — es supresión.

§ 20

El arquitecto suele seguir siendo un individual contributor. Su poder viene de la claridad de pensamiento, la confianza y la capacidad de hacer al equipo más fuerte.

Influence without authority

El director de orquesta no toca cada instrumento, pero sin él la orquesta se transforma rápido en un grupo de gente talentosa tocando obras distintas.

El arquitecto no debería volverse un bottleneck en cada decisión. Su tarea es fijar principios, explicar boundaries, hacer crecer a la gente e intervenir donde el costo del error es alto.

El mentoring del arquitecto no es "haz como yo". Es enseñar las preguntas: qué alternativas viste, qué resignaste, cómo testeas el riesgo, dónde termina la responsabilidad.

Delegar no significa soltar la responsabilidad

El capitán puede entregar el timón, pero no puede decir que el rumbo del barco ya no es problema suyo.

Parte de las decisiones arquitectónicas tienen que tomarlas los equipos. Si no, el arquitecto se convierte en una cola. Pero tiene que haber guardrails: principios, review, ADRs, platform constraints, quality gates.

El arquitecto interviene cuando la decisión es irreversible, rompe invariantes del sistema, crea un security risk o afecta a varios equipos.

§ 21

La arquitectura sólo tiene sentido en el contexto de un objetivo de negocio. Si no, es estética de ingeniería cara.

Los requisitos no funcionales también son requisitos de negocio

Para una tienda, "el checkout funciona en Black Friday" no es un detalle técnico — es plata.

Performance, availability, security, compliance, operability — no son "caprichos técnicos". Son propiedades del producto. El arquitecto los traduce a business impact: ingresos perdidos, riesgo regulatorio, costo de soporte, velocidad para abrir mercados.

El cost of delay ayuda a discutir no sólo el costo de hacer el trabajo, sino el costo de esperar. A veces una inversión arquitectónica sin ROI inmediato es necesaria, porque sin ella las próximas features empiezan a salir más caras.

Build vs. buy no es una cuestión de orgullo

No toda empresa tiene que construir su propia central eléctrica para encender la luz.

Construir te da control y diferenciación. Comprar te da velocidad y baja la carga operativa. El vendor lock-in es un riesgo real, pero por sí solo no es un argumento contra comprar. La pregunta es: ¿qué tan caro es salir si el proveedor cambia el precio, la API o la calidad?

El arquitecto ayuda a producto a ver el capability map: qué capacidades son el núcleo del negocio y cuáles conviene comprar.

§ 22

Cuando el código lo escriben agentes, el valor del arquitecto se desplaza hacia la especificación, el pensamiento arquitectónico y el control de calidad.

La calidad del spec se vuelve el bottleneck

Si la cuadrilla de obra se vuelve diez veces más rápida, el cuello de botella deja de ser la velocidad de los ladrillos. Pasa a ser la calidad de los planos.

Los agentes de AI aceleran la implementación, pero no eliminan la arquitectura. Una tarea mal planteada simplemente se convierte en código malo más rápido. Specification-driven development significa que el artefacto principal es la especificación del comportamiento, los boundaries, los invariantes, los tests y los acceptance criteria.

En un proceso AI-native, el arquitecto escribe menos código de bajo nivel y más prosa precisa. Hace review del diff, de los tests, de los boundaries arquitectónicos y del alineamiento con la spec.

El output del agente merece la misma disciplina que el PR de un humano

Un junior rápido que escribe mil líneas por hora igual necesita review. La velocidad no hace que el código sea correcto.

No puedes aceptar el código del agente sólo porque compila. Necesitas tests, evals, import boundaries, type checks, security review. Importan especialmente las scenario evaluations: el sistema tiene que pasar casos reales, no sólo el happy path.

Una organización AI-native gana no donde "todos vibe-codean", sino donde hay specs fuertes, iteraciones chicas, chequeos automáticos y ownership arquitectónico.

§ 23

El arquitecto puede ser peligroso justamente porque suena convincente. Conocer las trampas ahorra años.

Ivory tower architect

Alguien dibuja una ciudad perfecta en lo alto del cerro, pero nunca baja a mirar por dónde camina realmente la gente.

El ivory tower architect toma decisiones lejos del código, de las operaciones y del equipo. Sus diagramas son hermosos, pero la implementación sufre. La cura es simple: leer PRs, mirar incidentes, hablar con los ingenieros, recorrer uno mismo el camino del cambio.

Resume-driven development y cargo cult

Comprar un camión de bomberos porque impresiona a los vecinos es raro si no tienes ni agua ni bomberos.

El resume-driven development elige tecnologías por una línea en el CV. El cargo cult engineering copia la forma de una decisión ajena sin la razón. El NIH syndrome te obliga a escribir tu propio invento donde una herramienta externa madura sería mejor.

Otra trampa es el technical perfectionism. Una arquitectura perfecta que nunca llegó al usuario pierde contra un sistema lo bastante bueno que sale al mundo y puede evolucionar.

§ 24

La arquitectura es un juego infinito. Las tecnologías cambian, pero la capacidad de hacer las preguntas correctas sólo se fortalece.

Hay que aprender por sistemas, no por hype

Un cocinero no crece mirando publicidades de cuchillos, sino entendiendo los ingredientes, el calor, el tiempo y el sabor.

Las tecnologías nuevas vale la pena estudiarlas a través de preguntas: qué problema resuelven, qué precio introducen, dónde ya fracasaron, qué alternativas hay, qué tiene que ser verdad para que sean útiles.

Los T-shaped skills te dan profundidad en un área y amplitud en las vecinas. Los M-shaped skills aparecen en un arquitecto maduro: varios pilares profundos — datos, distribución, seguridad, producto, herramientas de AI.

Learning in public acelera la madurez

Cuando explicas una decisión por escrito, los agujeros del razonamiento se ven antes que los encuentre producción.

Escribe ADRs, RFCs, engineering notes, post-mortems, análisis cortos de decisiones. Aprende de arquitectos más fuertes que tú: no sólo qué eligieron, sino cómo razonaron.

El arquitecto al que la gente imita no suele ser el que más términos conoce. Es la persona al lado de la cual el equipo empieza a hacer mejores preguntas.

Autoevaluación final
  • Puedo nombrar los trade-offs de una decisión sin defender el ego. - Entiendo dónde vive el source of truth en el sistema. - Distingo decisiones reversibles de irreversibles. - Puedo explicar la arquitectura a ingeniería, producto y negocio con palabras distintas. - Escribo las decisiones para que se las pueda entender dentro de un año. - No escondo la complejidad detrás de las palabras "best practice".

Un arquitecto es un ingeniero que aprendió a ver las consecuencias antes de que se conviertan en un incidente.

Fin del curso · 24 módulos · de aquí en adelante empieza la práctica.

Relee este curso no como una referencia, sino como un conjunto de preguntas. La arquitectura empieza donde te detienes delante de una decisión y nombras con honestidad el precio de cada opción.