metis-desk/.agents/skills/rdx-solid/referencias/arquitectura-decisiones.md

Decisiones arquitectónicas y ADR

Referencia especializada del skill rdx-solid. Consulta arquitectura.md y las referencias del ámbito técnico afectado.

1. Propósito

Establecer un procedimiento ligero para elegir tecnologías, contratos y estructuras con criterios explícitos. No todas las decisiones requieren un ADR; las decisiones importantes deben poder explicarse y revisarse.

Objetivo: seleccionar una solución suficiente y sostenible para los requisitos reales, documentando sus compromisos sin burocracia innecesaria.

2. Cuándo realizar una evaluación formal

Considérala cuando una decisión tenga impacto significativo en:

• Compatibilidad de contratos o datos persistidos.
• Dependencias transversales y límites entre módulos.
• Seguridad, rendimiento, disponibilidad o resiliencia.
• Costes operativos o bloqueo con un proveedor.
• Despliegue y capacidad de reversión.
• Trabajo de varios equipos o evolución a medio plazo.

Para ajustes internos locales, una breve justificación técnica puede ser suficiente.

3. Proceso de decisión

1. Definir el problema: qué requisito o problema observado exige decidir.
2. Establecer restricciones: compatibilidad, seguridad, equipo, presupuesto, plazo y entorno.
3. Identificar alternativas viables: incluye mantener la solución actual cuando tenga sentido.
4. Comparar compromisos: simplicidad, riesgo, operación, flexibilidad y migración.
5. Seleccionar: justificar la opción frente a las alternativas.
6. Validar: prototipo, medición o prueba dirigida si existe incertidumbre material.
7. Documentar: registrar alcance, consecuencias y condiciones de revisión.

No simules un análisis exhaustivo si no hay datos: separa lo comprobado de lo supuesto.

4. Criterios de comparación

Criterio	Preguntas
Adecuación funcional	¿Resuelve los requisitos y restricciones reales?
Complejidad	¿Cuánto código, infraestructura y conocimiento añade?
Compatibilidad	¿Qué consumidores y formatos deben cambiar?
Seguridad	¿Qué superficie de riesgo introduce?
Operación	¿Cómo se despliega, observa y recupera?
Rendimiento	¿Existen mediciones o límites cuantificados?
Equipo	¿Se puede mantener con las capacidades disponibles?
Coste	¿Licencias, infraestructura, soporte y migración?
Reversibilidad	¿Puede sustituirse o revertirse razonablemente?

No asignes ponderaciones numéricas arbitrarias ni presentes estimaciones inciertas como medidas reales.

5. Decisiones especialmente sensibles

Arquitectura y modularidad

Antes de introducir microservicios, Clean Architecture o una nueva capa, comprueba que resuelve un problema real mejor que un monolito modular o una solución directa.

Persistencia

Evalúa integridad, transacciones, consultas reales, capacidades del equipo, migraciones, backup y recuperación. No selecciones un motor solo por tendencias.

Dependencias externas

Comprueba mantenimiento, compatibilidad, licencias, seguridad, tamaño, costes y alternativas nativas o ya instaladas. No agregues bibliotecas para operaciones triviales.

Contratos compartidos

Evalúa versionado, consumidores desplegados, migración y fuente de verdad. Consulta arquitectura-shared.md.

Legacy

Contrasta modernización gradual y sustitución; incluye paridad funcional, datos y reversión. Consulta arquitectura-legacy.md.

6. Architecture Decision Records (ADR)

Un ADR registra una decisión arquitectónica significativa y los motivos por los que se tomó. No debe convertirse en una especificación técnica interminable.

Cuándo crear un ADR

• Nuevo motor de base de datos o estrategia de persistencia.
• Cambio en límites modulares o dirección de dependencias.
• Selección de comunicación entre servicios.
• Cambio importante de autenticación o autorización.
• Decisión de migración con impacto sustancial.
• Dependencia estratégica que comprometa mantenimiento y operación.

No crees ADR para cambios de nombres, pequeñas funciones o refactorizaciones locales sin impacto arquitectónico.

Plantilla sugerida

# ADR 001: Título descriptivo

## Estado
Propuesta | Aceptada | Sustituida | Descartada

## Contexto
Problema, requisitos y restricciones relevantes.

## Alternativas consideradas
- Alternativa A: ventajas y costes.
- Alternativa B: ventajas y costes.
- Mantener situación actual, si es viable.

## Decisión
Opción elegida y razones verificables.

## Consecuencias
Beneficios, riesgos, migración, operación y costes.

## Verificación y revisión
Cómo se comprobará y qué condiciones obligarían a revisarla.

Ejemplo breve

# ADR 002: PostgreSQL para persistencia transaccional

## Estado
Aceptada

## Contexto
Se requieren transacciones, integridad relacional y consultas conocidas.

## Alternativas consideradas
PostgreSQL, MySQL y mantener el motor actual.

## Decisión
Adoptar PostgreSQL debido a requisitos concretos y experiencia del equipo.

## Consecuencias
Migraciones, operación, copias de seguridad y adaptación de repositorios.

## Verificación y revisión
Pruebas de integración, carga representativa y procedimiento de recuperación.

No afirmes que una tecnología es superior sin evidencia contextual suficiente.

7. Cómo organizar ADR

• Guarda las decisiones donde indique el proyecto; si no existe convención, considera docs/adr/.
• Utiliza nombres claros y estables, por ejemplo 001-persistencia-postgresql.md.
• Conserva los ADR históricos y marca los sustituidos en vez de reescribir el historial sin explicarlo.
• Enlaza decisiones relacionadas y responsables cuando el proceso del proyecto lo requiera.
• No dupliques documentación técnica extensa que ya existe en otros documentos.

8. Experimentos y mediciones

Para decisiones con incertidumbre material:

• Formula una hipótesis comprobable.
• Define criterios de aceptación y escenarios representativos.
• Mide antes de concluir sobre rendimiento o coste.
• Diferencia datos reales de estimaciones.
• Limita prototipos a aquello que deba validarse.
• No conviertas el prototipo en implementación de producción sin revisar seguridad, errores y operación.

9. Evolución y reversión

• Identifica consumidores, contratos y datos afectados.
• Planifica migración y coexistencia de versiones cuando corresponda.
• Establece condiciones de reversión si el riesgo lo exige.
• Prevé pruebas y observabilidad para comprobar el resultado.
• Revisa decisiones cuando cambien requisitos o aparezca evidencia relevante.

No cambies una decisión vigente únicamente porque otra solución sea más moderna.

10. Conducta del agente de programación

• No inventes requisitos ni datos técnicos no comprobados.
• Expón supuestos materiales si la tarea debe continuar sin aclaración.
• Distingue propuesta, decisión aprobada e implementación realizada.
• No modifiques grandes áreas del sistema para aplicar unilateralmente una preferencia arquitectónica.
• Respeta AGENTS.md, contratos y restricciones específicas del proyecto.
• Comunica alternativas y riesgos de forma proporcional a la importancia de la decisión.
• Nunca declares verificados resultados de pruebas o benchmarks que no se hayan ejecutado.

11. Lista de comprobación

• ¿El problema y las restricciones están claramente definidos?
• ¿Se consideró mantener la solución actual?
• ¿Las alternativas son viables en este proyecto?
• ¿Se compararon costes, riesgos y mantenibilidad?
• ¿Se ha diferenciado evidencia de hipótesis?
• ¿La decisión preserva contratos y requisitos relevantes?
• ¿Necesita ADR o basta una justificación breve?
• ¿Se definieron verificación y revisión cuando correspondía?

Principio final: una buena decisión arquitectónica es explícita, contextual, verificable y proporcional al problema que resuelve.