Redactor de ADR

Documenta decisiones de arquitectura con contexto claro, alternativas y consecuencias. Escribe en español.

Plantilla de ADR

# ADR-[Número]: [Título corto de la decisión]

**Estado:** [Propuesto | Aceptado | Obsoleto | Sustituido por ADR-XXX]  
**Fecha:** [AAAA-MM-DD]  
**Autor:** [Nombre/Usuario]

## 1. Contexto

¿Qué problema estamos resolviendo? ¿Qué factores lo afectan (objetivos de negocio, deuda técnica, presupuesto)?
**Restricciones:**

- [Restricción 1]
- [Restricción 2]

## 2. Decisión

Una declaración breve de la decisión. La tesis principal.

## 3. Detalles técnicos y mecanismos

_Sección de formato libre. Describe detalles de implementación, estructuras de datos, detalles de protocolo o características clave del framework._

- [Listas, descripciones de API, esquemas de datos]
- [Visualización Mermaid (recomendada para interacciones complejas)]

## 4. Alternativas consideradas

### 4.1. [Opción 1]

- **Pros:** ...
- **Contras:** ...
- **Decisión:** [Rechazada/Considerada] (razón breve).

## 5. Consecuencias y riesgos

### Positivas (Pros)

- ¿Cómo ayuda esto al sistema/equipo?

### Negativas / Riesgos (Contras/Riesgos)

- ¿Qué desventajas aceptamos? ¿Cuáles son las amenazas?
- **Mitigación:** ¿Cómo manejaremos los riesgos?

## 6. Historial de revisiones

- **[Fecha]**: [Descripción del cambio] ([Autor])
- **[Fecha]**: [Ej.: Estado cambiado a Aceptado] ([Autor])

Numeración de ADR

ADR-001: Arquitectura inicial del sistema
ADR-002: Selección de base de datos para análisis
ADR-003: Estrategia de autenticación
...

Flujo de estados

Propuesto → Aceptado → Implementado
    ↓
Rechazado

Aceptado → Obsoleto → Sustituido por ADR-XXX

Mejores prácticas

Escribe ADR para decisiones significativas: No toda elección necesita un ADR
Documenta alternativas: Muestra que consideraste opciones
Sé honesto sobre las ventajas y desventajas: Toda decisión tiene inconvenientes
Mantenlo conciso: Máximo 1-2 páginas
Actualiza el estado: Marca ADR obsoletos/sustituidos
Enlaza ADR relacionados: Crea rastros de decisiones
Incluye seguimientos: Elementos de acción con propietarios
Visualiza: Usa diagramas Mermaid para mostrar arquitectura y flujos
Escribe para futuros lectores que carecen del contexto actual
Sé honesto sobre las ventajas y desventajas (toda elección tiene inconvenientes)

Patrones comunes

Para selección de tecnología:

Enfócate en capacidades técnicas frente a requisitos
Incluye puntos de referencia de rendimiento si están disponibles
Documenta el nivel de experiencia del equipo
Considera la complejidad operativa

Para cambios arquitectónicos:

Incluye la estrategia de migración en las consecuencias
Documenta el impacto en la compatibilidad hacia atrás
Considera el impacto en la velocidad del equipo durante la transición
Nota planes de monitoreo y reversión

Para estándares y convenciones:

Incluye ejemplos del estándar en la práctica
Documenta excepciones o vías de escape
Considera mecanismos de cumplimiento
Nota implicaciones educativas/de incorporación

Para obsolecencias:

Establece el estado en "Obsoleto" o "Sustituido"
Enlaza al ADR que lo sustituye
Documenta el cronograma de descontinuación
Incluye una guía de migración

Antipatrones

❌ Demasiado detallado: ADR de 10 páginas que nadie lee ❌ Sin alternativas: Parece que la decisión estaba predeterminada ❌ Faltan consecuencias: Ignorar desventajas ❌ Sin propietario: Nadie responsable ❌ Estado desactualizado: ADR antiguos marcados como "Propuesto"

Lista de verificación de revisión

Declaración clara del problema en Contexto
Decisión establecida explícitamente
2 o más alternativas consideradas
Ventajas y desventajas evaluadas honestamente
Consecuencias (positivas y negativas) documentadas
Riesgos identificados con mitigaciones
Propietario de la decisión asignado
Acciones de seguimiento con fechas límite
El estado está actualizado

rbikbov/frontend-starter

¿Qué es frontend-starter?

Preguntar en tu IA favorita

Documentación