16. Registro de decisiones de arquitectura y decisiones técnicas
16.1 Introducción
En todo proyecto de software se toman decisiones técnicas: qué arquitectura usar, cómo organizar módulos, qué base de datos elegir, cómo autenticar usuarios, qué estrategia de despliegue aplicar o cómo manejar integraciones externas. Algunas decisiones son menores y pueden entenderse desde el código. Otras condicionan el futuro del sistema y deben registrarse.
El registro de decisiones permite conservar el razonamiento detrás de una elección. No solo documenta qué se decidió, sino también por qué, en qué contexto, qué alternativas se evaluaron y qué consecuencias se aceptaron.
Sin este registro, el equipo puede repetir discusiones, olvidar restricciones, revertir decisiones sin entenderlas o mantener soluciones que ya no tienen sentido porque cambió el contexto.
16.2 Qué es una decisión técnica
Una decisión técnica es una elección que afecta la construcción, operación, mantenimiento o evolución del software. Puede estar relacionada con arquitectura, diseño, herramientas, infraestructura, seguridad, datos, integración, pruebas o procesos de desarrollo.
No todas las decisiones necesitan documentación formal. Cambiar el nombre de una variable no requiere un registro especial. Elegir un modelo de datos, adoptar un proveedor externo o dividir el sistema en servicios sí puede requerirlo.
16.3 Decisiones registradas y trazables
La imagen muestra una decisión técnica documentada: contexto, problema, alternativas, decisión tomada, consecuencias y revisión futura. También muestra cómo esa decisión se conecta con arquitectura, código, pruebas, despliegue y mantenimiento.
16.4 Por qué registrar decisiones
Registrar decisiones evita pérdida de conocimiento. Muchas decisiones parecen obvias cuando se toman, pero meses después pueden resultar extrañas si no se conserva el contexto. Un equipo nuevo puede ver una solución y no saber si fue elegida por rendimiento, costo, compatibilidad, restricciones del cliente o falta de tiempo.
El registro también ayuda a mantener coherencia. Si se decidió que todas las integraciones externas pasen por adaptadores, esa decisión puede guiar nuevas funcionalidades. Si se decidió usar una base de datos relacional por necesidades transaccionales, futuras propuestas deben considerar ese criterio.
16.5 Decisiones de arquitectura
Las decisiones de arquitectura afectan la estructura principal del sistema. Pueden incluir estilos arquitectónicos, separación de componentes, comunicación entre servicios, persistencia, seguridad, escalabilidad, observabilidad o despliegue.
Estas decisiones suelen tener impacto amplio. Por ejemplo, elegir una arquitectura monolítica modular o una arquitectura basada en microservicios influye en despliegue, pruebas, coordinación de equipos, operación y mantenimiento.
Por eso, las decisiones arquitectónicas deben documentarse con especial cuidado y relacionarse con la documentación de arquitectura.
16.6 Decisiones de diseño e implementación
También existen decisiones técnicas de menor alcance, pero igualmente importantes. Por ejemplo, usar una librería específica para validación, aplicar una estrategia de caché, definir un patrón para manejo de errores o establecer una convención para módulos.
Estas decisiones pueden registrarse si afectan varias partes del sistema o si podrían generar dudas. No se trata de documentar cada detalle, sino de conservar elecciones que explican cómo debe trabajarse en el proyecto.
16.7 Formato ADR
Un formato conocido para registrar decisiones es el ADR, por sus siglas en inglés: Architecture Decision Record. Un ADR es un documento breve que describe una decisión arquitectónica o técnica importante.
Un ADR suele incluir título, estado, contexto, decisión, consecuencias y, a veces, alternativas consideradas. Su valor está en ser breve, específico y fácil de revisar.
No es obligatorio usar ese nombre, pero el enfoque es útil: cada decisión importante queda registrada como una pieza documental independiente.
16.8 Estructura recomendada
Un registro de decisión puede tener esta estructura:
- Título: identifica la decisión de manera clara.
- Estado: propuesto, aceptado, reemplazado o descartado.
- Contexto: explica la situación y restricciones.
- Problema: define qué se necesitaba resolver.
- Alternativas: resume opciones evaluadas.
- Decisión: indica la opción elegida.
- Consecuencias: describe beneficios, costos y riesgos.
- Fecha y responsables: ayudan a ubicar la decisión en el tiempo.
16.9 Contexto
El contexto explica por qué la decisión era necesaria. Debe incluir restricciones, necesidades, riesgos, antecedentes y condiciones del proyecto. Sin contexto, una decisión puede parecer arbitraria.
Por ejemplo, una decisión de usar una base de datos relacional puede deberse a necesidad de transacciones, conocimientos del equipo, integración con reportes existentes y restricciones de infraestructura. Si solo se documenta "se usará PostgreSQL", se pierde la parte más valiosa.
16.10 Alternativas consideradas
Registrar alternativas evita repetir análisis. No es necesario escribir un estudio extenso, pero sí indicar qué opciones se evaluaron y por qué fueron descartadas.
Por ejemplo, al elegir un mecanismo de notificaciones, se pudo evaluar correo electrónico directo, servicio externo, cola de mensajes o procesamiento síncrono. Documentar alternativas permite entender compromisos y revisar la decisión si cambian las condiciones.
16.11 Consecuencias
Toda decisión tiene consecuencias positivas y negativas. Documentarlas es fundamental. Una elección puede simplificar desarrollo, pero aumentar dependencia de un proveedor. Puede mejorar rendimiento, pero agregar complejidad operativa. Puede reducir costo inicial, pero limitar escalabilidad futura.
Un registro honesto no solo enumera beneficios. También describe riesgos, costos, tareas pendientes y condiciones bajo las cuales la decisión debería revisarse.
16.12 Estados de una decisión
Las decisiones pueden cambiar con el tiempo. Por eso conviene manejar estados. Una decisión puede estar propuesta, aceptada, rechazada, reemplazada o deprecada. Esto permite conservar historial sin borrar el pasado.
Si una decisión es reemplazada, el documento anterior puede enlazar al nuevo. Así se mantiene trazabilidad y se entiende la evolución del sistema.
16.13 Tabla de ejemplo
| Título | Usar cola de mensajes para notificaciones |
|---|---|
| Contexto | El envío de notificaciones no debe bloquear la reserva de turnos. |
| Alternativas | Envío síncrono, tarea programada, cola de mensajes. |
| Decisión | Publicar eventos en una cola y procesar notificaciones de forma asíncrona. |
| Consecuencias | Mejora la respuesta al usuario, pero requiere monitoreo de cola y reintentos. |
16.14 Relación con requisitos y arquitectura
Una decisión técnica debería poder relacionarse con requisitos, restricciones o atributos de calidad. Por ejemplo, una decisión sobre autenticación puede responder a requisitos de seguridad. Una decisión sobre caché puede responder a rendimiento. Una decisión sobre despliegue puede responder a disponibilidad.
También debe relacionarse con la arquitectura. Si un documento de arquitectura muestra un componente, las decisiones que lo justifican deberían estar enlazadas o mencionadas.
16.15 Dónde guardar los registros
Los registros de decisiones pueden guardarse en el repositorio, en una wiki o en una herramienta documental. Para decisiones muy ligadas al código, el repositorio suele ser una buena opción porque permite versionado y revisión junto con cambios técnicos.
La ubicación debe ser conocida y fácil de consultar. Si los registros están ocultos o dispersos, pierden valor. También conviene usar nombres consistentes, como ADR-001-usar-postgresql.html o una sección ordenada por fecha.
16.16 Errores frecuentes
Al registrar decisiones técnicas suelen aparecer estos errores:
- Registrar solo la decisión sin contexto ni motivo.
- No mencionar alternativas descartadas.
- Ocultar consecuencias negativas o riesgos.
- Documentar demasiadas decisiones menores y volver pesado el proceso.
- No actualizar el estado cuando una decisión se reemplaza.
- Guardar registros en lugares que el equipo no consulta.
- No relacionar decisiones con requisitos, arquitectura o mantenimiento.
16.17 Qué debes recordar de este tema
- Las decisiones técnicas importantes deben conservar contexto, alternativas y consecuencias.
- No todas las decisiones necesitan registro formal.
- Conviene registrar decisiones costosas de cambiar o difíciles de entender después.
- Un ADR es una forma breve y útil de documentar decisiones arquitectónicas.
- Las consecuencias deben incluir beneficios, costos y riesgos.
- Las decisiones pueden cambiar; por eso conviene manejar estados e historial.
- Los registros deben estar ubicados donde el equipo pueda consultarlos y mantenerlos.
16.18 Conclusión
Registrar decisiones de arquitectura y decisiones técnicas permite conservar el razonamiento que da forma al sistema. Esto mejora la comunicación, facilita el mantenimiento y evita repetir discusiones sin contexto.
En el próximo tema estudiaremos la documentación del diseño detallado: módulos, clases, contratos y dependencias.