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

# Decisiones arquitectónicas y ADR

> Referencia especializada del skill `rdx-solid`. Consulta [arquitectura.md](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](arquitectura-shared.md).

### Legacy

Contrasta modernización gradual y sustitución; incluye paridad funcional, datos y reversión. Consulta [arquitectura-legacy.md](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

```markdown
# 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

```markdown
# 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.