El código dice qué; nadie dice por qué
Cualquiera puede leer en la configuración que la base de datos es relacional, que la cola es gestionada o que el servicio corre en contenedores. Lo que no se puede leer es por qué: qué problema resolvía, qué otras opciones se miraron, qué se sacrificó al elegir esa.
Sin ese porqué, cada persona nueva tiene dos opciones malas: no tocar nada por miedo o cambiarlo todo por desconocimiento.
El registro de decisión
Un registro de decisión de arquitectura (ADR por sus siglas en inglés, una práctica popularizada por Michael Nygard) es un documento corto, uno por decisión, que se guarda junto al código y no se borra nunca.
Sus partes:
- Título y estado. Qué se decidió y en qué situación está: propuesta, aceptada, sustituida por otra.
- Contexto. Qué problema había y qué restricciones existían en ese momento. Es lo que más se olvida y lo que más importa.
- Opciones consideradas. Al menos dos, con sus ventajas e inconvenientes. Si solo hubo una opción, no fue una decisión.
- Decisión. Qué se eligió, en una o dos frases.
- Consecuencias. Qué se gana, qué se pierde y qué obliga a hacer después.
- Costo estimado. Cuánto cuesta operar lo que se eligió. Es la parte que casi nadie escribe y la que más se agradece después.
Cuándo escribir uno
No toda elección merece un registro. La regla práctica: se escribe cuando la decisión es cara de revertir o la va a heredar otra persona. Elegir el motor de base de datos, sí. Elegir el nombre de una variable, no.
Cómo evitar la burocracia
- Una página como máximo. Si no cabe, son dos decisiones.
- Se escribe en el momento, no después. Diez minutos el día de la decisión.
- No se edita: se sustituye. Si una decisión cambia, se escribe una nueva que cita a la anterior. Así queda la historia completa.
- Vive con el código, en el mismo repositorio, para que se revise y se versione igual.
Un conjunto de registros de decisión es la memoria del sistema. Es lo que permite que alguien que llega dentro de un año entienda en una tarde lo que costó meses decidir.
Cómo lo aplicamos: Arquitectura Cloud.