En cualquier sistema que dure más de unos meses surge la misma pregunta incómoda: "¿por qué hicimos esto así?". La persona que tomó la decisión ya no está, el contexto se ha perdido y el equipo actual duda entre respetar la elección o tirarla por la borda sin entenderla. La gobernanza arquitectónica existe para responder a esa pregunta y para asegurar coherencia técnica sin convertirse en un freno burocrático. Tradicionalmente, gobernanza evocaba comités pesados, documentos de cientos de páginas y un "arquitecto jefe" que aprobaba todo. Hoy buscamos lo contrario: una gobernanza ligera, distribuida y basada en decisiones documentadas de forma sencilla. La herramienta estrella de este enfoque son los Architecture Decision Records (ADR). En esta lección veremos qué es la gobernanza ligera, cómo escribir ADR con una plantilla, cómo funcionan los comités de arquitectura modernos y cómo definir estándares que ayuden en vez de estorbar.

1. Qué es la gobernanza arquitectónica
2. Gobernanza pesada vs ligera
3. Architecture Decision Records (ADR)
4. Plantilla de ADR
5. Ejemplo completo de ADR
6. Comités de arquitectura modernos
7. Estándares y guías (golden paths)
8. Errores Comunes y Consejos
9. Ejercicios
10. Conclusión

La gobernanza arquitectónica es el conjunto de prácticas que aseguran que las decisiones técnicas de una organización sean coherentes, estén alineadas con los objetivos de negocio y se mantengan en el tiempo. Cubre tres preguntas:

• ¿Quién decide? Cómo se distribuye la autoridad técnica.
• ¿Cómo se decide? El proceso para tomar y documentar decisiones.
• ¿Cómo se asegura el cumplimiento? Cómo se verifica que lo decidido se respeta.

El objetivo no es controlar a la gente, sino reducir el coste de la coherencia: que un equipo no reinvente la rueda, que las decisiones importantes no se tomen a la ligera y que el conocimiento sobreviva a la rotación de personas. Una buena gobernanza es invisible cuando funciona y dolorosa solo cuando falta.

La gobernanza ligera no significa "cada uno hace lo que quiere". Significa mover la decisión al lugar donde está el conocimiento (el equipo que construye), pero exigiendo que las decisiones relevantes se documenten y se verifiquen. El comité pasa de portero a facilitador.

Un Architecture Decision Record (registro de decisión arquitectónica), idea popularizada por Michael Nygard en 2011, es un documento corto que captura una decisión arquitectónica significativa: el contexto en que se tomó, la decisión en sí y sus consecuencias. Características clave:

• Uno por decisión. No es un documento maestro, sino una colección de fichas pequeñas.
• Inmutable. Un ADR no se edita una vez aceptado; si la decisión cambia, se escribe uno nuevo que sustituye al anterior (estado "Reemplazado por ADR-00X").
• Versionado con el código. Vive en el repositorio, normalmente en docs/adr/, para que evolucione junto al sistema y se revise en los pull requests.
• Breve. Una o dos páginas. Si necesitas más, probablemente sean varias decisiones.

¿Qué merece un ADR? Decisiones que son costosas de revertir o que afectan a muchos: elegir un estilo arquitectónico, una base de datos, un protocolo de comunicación, una política de autenticación, etc. No documentes con ADR el nombre de una variable.

Una plantilla minimalista y muy usada, en Markdown:

Repasemos cada sección y por qué importa:

• Estado: permite saber de un vistazo si la decisión sigue vigente. El flujo típico es Propuesto → Aceptado; más adelante puede pasar a Reemplazado.
• Contexto: es la parte más valiosa dentro de dos años. Explica las fuerzas que llevaron a decidir. Sin contexto, una decisión correcta parece arbitraria.
• Decisión: la afirmación concreta. En voz activa ("Decidimos usar PostgreSQL") para que no haya ambigüedad sobre qué se eligió.
• Consecuencias: la honestidad aquí es oro. Toda decisión tiene un coste; nombrarlo evita que el futuro equipo se sienta engañado.
• Alternativas consideradas: demuestra que se pensó. Evita que alguien proponga dentro de un año una opción ya descartada por buenas razones.

Observa cómo el ejemplo aplica la plantilla con datos reales: el contexto narra un problema concreto (timeouts en campaña), la decisión es inequívoca (eventos vía RabbitMQ) y las consecuencias no esconden el coste (consistencia eventual, necesidad de idempotencia). Cualquiera que lea esto dentro de dos años entenderá por qué Facturación es asíncrona y no intentará "arreglarlo" volviéndolo síncrono.

El comité de arquitectura no ha desaparecido, pero ha cambiado de papel. En el modelo moderno suele organizarse como un ART (Architecture Review Team) o, más informalmente, una guild de arquitectura:

• Composición rotatoria: no solo "arquitectos", sino ingenieros senior de varios equipos. Evita la torre de marfil y reparte el conocimiento.
• Función asesora, no de portero: revisa ADR propuestos, aporta perspectiva transversal y detecta solapes o incoherencias, pero rara vez bloquea.
• Cadencia ligera: reuniones cortas y frecuentes, idealmente sobre ADR ya escritos (se revisa un documento, no se improvisa en una pizarra).
• Decisiones por consenso informado: si no hay acuerdo, el equipo que asume el coste decide, dejándolo registrado.

El flujo del diagrama integra la gobernanza en el proceso de desarrollo: el ADR se propone como un pull request, se discute como cualquier cambio de código y, al aprobarse, queda versionado. La gobernanza deja de ser un evento aparte y se vuelve parte del trabajo diario.

Para que los equipos tengan autonomía sin caos, la organización define estándares y golden paths (caminos dorados):

• Estándar: una regla que se debe cumplir ("toda API REST expone OpenAPI", "los logs salen en JSON"). Idealmente, verificable de forma automática.
• Golden path (camino dorado): la forma recomendada y soportada de hacer algo común (plantilla de microservicio, pipeline de CI/CD listo). No es obligatorio, pero es el camino fácil: quien se sale, asume el coste.
• Guía: recomendación sin obligatoriedad ("preferimos inyección por constructor").

La clave es distinguir lo que es obligatorio y automatizable de lo que es recomendado. Cuanto más se pueda verificar con herramientas (linters, fitness functions, plantillas), menos hace falta vigilar a mano. Un buen estándar no se documenta en un PDF: se codifica en una comprobación que falla el build si se incumple.

Este fragmento convierte un estándar de seguridad ("no ejecutar como root") en una comprobación que falla el build si el Dockerfile no incluye una directiva USER. Es gobernanza ejecutable: nadie tiene que recordar la regla ni revisarla a mano, porque el pipeline la impone. Veremos esta filosofía llevada al extremo en la próxima lección sobre fitness functions.

• Documentación que nadie lee ni mantiene. Un wiki gigante y obsoleto es peor que nada. Prefiere ADR cortos versionados con el código.
• Editar ADR aceptados. Rompe la trazabilidad histórica. Si la decisión cambia, escribe un ADR nuevo que reemplace al anterior.
• Comité que bloquea todo. Si cada decisión necesita aprobación previa de un órgano central, la entrega se paraliza. El comité asesora; el equipo decide y documenta.
• Documentar decisiones triviales. Reserva los ADR para decisiones caras de revertir o que afectan a muchos. No documentes el formato de una fecha con un ADR.
• Estándares solo en papel. Si un estándar no se puede verificar automáticamente, se incumplirá en silencio. Codifícalo siempre que puedas.
• Consejo: numera los ADR de forma secuencial y nunca reutilices números. El histórico completo, incluidos los rechazados y reemplazados, es parte del valor.

Ejercicio 1. Decide cuáles de estas decisiones merecen un ADR y cuáles no: (a) elegir entre REST y gRPC para la comunicación entre servicios; (b) el nombre del paquete raíz; (c) usar autenticación con JWT; (d) el orden de los imports.

Ejercicio 2. Escribe un ADR siguiendo la plantilla para esta decisión: "el equipo va a usar PostgreSQL como base de datos principal en lugar de MongoDB". Inventa un contexto razonable.

Ejercicio 3. Tu organización quiere garantizar que todos los servicios expongan un endpoint /health. ¿Lo plantearías como guía, estándar o golden path? ¿Cómo lo verificarías?

Solución 1. Merecen ADR: (a) y (c), porque son decisiones costosas de revertir y afectan a todos los equipos. No merecen ADR: (b) y (d), que son convenciones triviales; van en una guía de estilo o en el linter, no en un ADR.

Solución 2. (Ejemplo) Estado: Aceptado. Contexto: necesitamos transacciones ACID y relaciones fuertes entre pedidos, líneas y clientes; el equipo domina SQL y no prevemos datos sin esquema. Decisión: decidimos usar PostgreSQL como base de datos principal. Consecuencias: ganamos integridad referencial y transacciones; renunciamos a la flexibilidad de esquema de MongoDB y asumimos que datos muy variables requerirían columnas JSONB. Alternativas: MongoDB (descartado: no necesitamos esquema flexible y perderíamos transacciones multi-documento fáciles).

Solución 3. Lo mejor es un estándar ("todo servicio expone /health") reforzado con un golden path (la plantilla de servicio ya incluye el endpoint, así cumplirlo es gratis). La verificación se automatiza: un test de contrato en CI que arranca el servicio y comprueba que /health responde 200, fallando el build si no.

La gobernanza arquitectónica moderna apuesta por ser ligera, distribuida y ejecutable: mover las decisiones al equipo que tiene el conocimiento, documentarlas con ADR breves e inmutables versionados junto al código, y convertir el comité en un asesor en vez de un portero. Hemos visto cómo escribir ADR con una plantilla y un ejemplo completo, cómo operan las guilds de arquitectura y cómo los estándares ganan fuerza cuando se codifican en comprobaciones automáticas en lugar de quedarse en papel. Esa última idea —verificar la arquitectura automáticamente— es el puente perfecto hacia la siguiente lección: Fitness Functions y Arquitectura Evolutiva, donde aprenderemos a escribir pruebas que comprueban que la arquitectura se mantiene sana a medida que el sistema evoluciona.