Arquitectura evolutiva: decisiones registradas, funciones de aptitud y pruebas de contrato
La arquitectura no se decide una vez y se documenta en un diagrama. Se decide continuamente y se erosiona en silencio. Tres prácticas la mantienen viva: registrar decisiones, automatizar sus criterios y verificar los contratos entre equipos.
En la mayoría de las organizaciones, la arquitectura de un sistema existe en tres lugares simultáneos y contradictorios: un diagrama hecho hace dos años que ya no refleja la realidad, la cabeza de dos o tres personas que estuvieron en las decisiones originales, y el código, que es la única versión verdadera y la más difícil de leer.
Esa situación produce un costo específico y recurrente. Cada vez que alguien nuevo tiene que tomar una decisión técnica, no sabe qué restricciones existen ni por qué. Entonces decide desde cero, con criterio razonable, y a veces contradice una decisión anterior que existía por un motivo que nadie le contó. La arquitectura se erosiona sin que nadie la haya decidido erosionar.
Tres prácticas atacan ese problema desde ángulos distintos.
Registros de decisión de arquitectura
Un registro de decisión de arquitectura —ADR, por su sigla en inglés— es un documento corto que captura una decisión técnica significativa en el momento en que se toma. Su estructura mínima es de cuatro secciones.
Contexto. Qué situación motivó la decisión. Qué restricciones existían.
Decisión. Qué se decidió, en términos concretos.
Alternativas consideradas. Qué más se evaluó y por qué se descartó. Esta sección es la que más valor tiene meses después, y la que más se omite.
Consecuencias. Qué se gana, qué se pierde, qué queda condicionado.
Un ADR bien escrito ocupa una página y se escribe en veinte minutos. Vive en el repositorio, junto al código que afecta, numerado y con fecha. No se edita cuando la decisión cambia: se escribe un ADR nuevo que supersede al anterior, dejando el historial intacto.
El valor aparece en tres momentos. Cuando alguien nuevo pregunta por qué el sistema es así. Cuando alguien propone cambiar algo y hay que saber qué se rompería. Y cuando una decisión que parecía correcta resultó mala, y conviene entender qué información faltaba entonces —lo cual es aprendizaje organizacional en su forma más concreta.
Funciones de aptitud
Un ADR registra la intención. Nada garantiza que la realidad la respete.
Una función de aptitud es una verificación automatizada de una propiedad arquitectónica. Si la decisión fue que el módulo de facturación no puede acceder directamente a la base de datos de clientes, la función de aptitud es una prueba que falla si alguien escribe ese acceso.
Convierte una regla que vivía en la memoria de alguien en una restricción que el sistema aplica solo. Y con eso cambia el modo de falla: en vez de descubrir la violación seis meses después en una revisión de arquitectura, se descubre en el momento en que se escribe, cuando corregirla cuesta minutos.
Las propiedades que más se benefician de esto son las que se degradan lento y en silencio: límites entre módulos, dependencias permitidas, tiempos de respuesta, tamaño de artefactos, cobertura de pruebas en zonas críticas, ausencia de dependencias con vulnerabilidades conocidas.
La regla práctica es simple: si una decisión de arquitectura importa lo suficiente como para escribir un ADR, vale la pena preguntarse si se puede verificar automáticamente. No todas se pueden. Las que sí, deberían.
Pruebas de contrato
La tercera práctica ataca el punto donde más duele la erosión en organizaciones con muchos equipos: las interfaces entre ellos.
Cuando un equipo consume el servicio de otro, existe un contrato implícito: estos campos, con estos tipos, con este comportamiento. El equipo proveedor evoluciona su servicio y, sin querer, rompe una suposición del consumidor. El error aparece en integración, o peor, en producción.
Una prueba de contrato formaliza ese acuerdo y lo verifica automáticamente en ambos lados. El consumidor declara qué espera; el proveedor ejecuta esa expectativa contra su implementación en cada cambio. Si algo se rompe, se rompe en el momento del cambio y en el lado que lo causó.
El efecto organizacional es mayor que el técnico. Convierte una dependencia que requería coordinación —“avísanos antes de cambiar algo”— en una dependencia verificada por máquina. El equipo proveedor puede evolucionar con confianza; el consumidor no necesita vigilancia. Eso es exactamente lo que permite que veinte equipos avancen en paralelo sin una reunión de sincronización semanal.
Cómo se combinan
Las tres prácticas cubren momentos distintos del ciclo de vida de una decisión.
| Práctica | Qué resuelve | Cuándo actúa |
|---|---|---|
| ADR | Por qué el sistema es así | Al decidir |
| Función de aptitud | Que la decisión se respete | En cada cambio |
| Prueba de contrato | Que las interfaces no se rompan | En cada integración |
Sin ADRs, las otras dos verifican reglas cuyo origen nadie recuerda, lo que produce restricciones de culto. Sin funciones de aptitud, los ADRs son literatura. Sin pruebas de contrato, cada cambio en un servicio compartido es una apuesta.
Cómo se escribe un ADR que sirva
La estructura de cuatro secciones es fácil de copiar y fácil de llenar mal. Estas son las diferencias entre un ADR útil y uno que nadie va a consultar.
El contexto describe restricciones, no antecedentes. Un contexto útil dice qué limitaba la decisión en ese momento: el volumen esperado, el plazo, las capacidades del equipo, los sistemas con los que había que integrar, el presupuesto. Un contexto inútil narra la historia del proyecto. La diferencia importa porque quien lo lee dentro de dos años necesita saber si esas restricciones siguen vigentes.
Las alternativas incluyen la que casi se elige. La sección de alternativas suele escribirse como justificación de la decisión tomada, con opciones descartadas por razones evidentes. Eso no aporta. Lo que aporta es la alternativa que estuvo cerca de ganar y por qué perdió, porque es la que va a volver a proponerse.
Las consecuencias incluyen las negativas. Toda decisión de arquitectura tiene un costo. Un ADR que solo enumera beneficios está vendiendo en vez de registrando. Escribir qué se pierde tiene además un efecto práctico: cuando ese costo se materializa, el equipo sabe que era esperado y no un descubrimiento.
Se escribe cuando la decisión se toma, no después. Un ADR redactado tres meses más tarde es una reconstrucción, y las reconstrucciones son sistemáticamente más coherentes que la realidad: eliminan la incertidumbre que efectivamente había. Esa incertidumbre es información valiosa.
Hay un tipo de ADR que merece mención aparte y casi nunca se escribe: el que registra una decisión de no hacer algo. No adoptar cierta tecnología, no dividir cierto componente, no migrar cierto sistema. Esas decisiones se toman, se olvidan, y vuelven a discutirse cada dieciocho meses desde cero.
Registrarlas tiene un rendimiento desproporcionado respecto a su costo: media página evita una discusión recurrente y, cuando la propuesta vuelve, permite evaluar qué cambió desde entonces en vez de volver a empezar.
Un punto de partida realista
No hace falta adoptar las tres a la vez ni retroactivamente.
Empieza con ADRs para las decisiones futuras. No documentes las cuarenta decisiones históricas: registra la próxima. En seis meses habrá diez ADRs que cubren las decisiones vigentes más relevantes, escritos cuando el contexto estaba fresco.
Agrega una función de aptitud para la regla arquitectónica que más se viola. Toda organización tiene una: el límite que todos conocen y que se rompe cada dos meses. Automatizarla libera la energía que se gasta en vigilarla.
Y agrega pruebas de contrato en la interfaz que más incidentes de integración genera. No en todas: en esa.
Tres intervenciones pequeñas, cada una en el punto donde el dolor ya es reconocible. Eso rinde bastante más que un programa de arquitectura que empieza documentando el estado actual completo y se agota antes de llegar a producir efecto.