Registros de Decisiones Arquitectónicas (ADR)

¿Qué hace Registros de Decisiones Arquitectónicas (ADR)?

Captura decisiones arquitectónicas a medida que ocurren durante las sesiones de codificación. En lugar de que las decisiones vivan solo en hilos de Slack, comentarios de PR o la memoria de alguien, esta habilidad produce documentos ADR estructurados que viven junto al código.

Cuándo activarla

• El usuario dice explícitamente "registremos esta decisión" o "ADR esto"
• El usuario elige entre alternativas significativas (framework, librería, patrón, base de datos, diseño de API)
• El usuario dice "decidimos..." o "la razón por la que hacemos X en lugar de Y es..."
• El usuario pregunta "¿por qué elegimos X?" (leer ADR existentes)
• Durante fases de planificación cuando se discuten compensaciones arquitectónicas

Formato ADR

Usa el formato ADR ligero propuesto por Michael Nygard, adaptado para desarrollo asistido por IA:

# ADR-NNNN: [Título de la Decisión]

**Fecha**: YYYY-MM-DD
**Estado**: propuesto | aceptado | obsoleto | reemplazado por ADR-NNNN
**Decisores**: [quiénes participaron]

## Contexto

¿Cuál es el problema que estamos viendo que motiva esta decisión o cambio?

[2-5 oraciones describiendo la situación, restricciones y fuerzas en juego]

## Decisión

¿Cuál es el cambio que estamos proponiendo y/o realizando?

[1-3 oraciones que expresen claramente la decisión]

## Alternativas Consideradas

### Alternativa 1: [Nombre]
- **Pros**: [beneficios]
- **Contras**: [desventajas]
- **Por qué no**: [razón específica por la que fue rechazada]

### Alternativa 2: [Nombre]
- **Pros**: [beneficios]
- **Contras**: [desventajas]
- **Por qué no**: [razón específica por la que fue rechazada]

## Consecuencias

¿Qué se vuelve más fácil o más difícil de hacer debido a este cambio?

### Positivas
- [beneficio 1]
- [beneficio 2]

### Negativas
- [compensación 1]
- [compensación 2]

### Riesgos
- [riesgo y mitigación]

Flujo de trabajo

Capturar un nuevo ADR

Cuando se detecta un momento de decisión:

1. Inicializar (solo la primera vez) — si docs/adr/ no existe, pide confirmación al usuario antes de crear el directorio, un README.md con el encabezado de la tabla de índice (ver Formato del Índice ADR más abajo) y un template.md en blanco para uso manual. No crees archivos sin consentimiento explícito.
2. Identificar la decisión — extrae la elección arquitectónica central que se está tomando
3. Recopilar contexto — ¿qué problema provocó esto? ¿Qué restricciones existen?
4. Documentar alternativas — ¿qué otras opciones se consideraron? ¿Por qué fueron rechazadas?
5. Declarar consecuencias — ¿cuáles son las compensaciones? ¿Qué se vuelve más fácil/más difícil?
6. Asignar un número — escanea los ADR existentes en docs/adr/ e incrementa
7. Confirmar y escribir — presenta el borrador del ADR al usuario para revisión. Solo escribe en docs/adr/NNNN-decision-title.md después de la aprobación explícita. Si el usuario declina, descarta el borrador sin escribir ningún archivo.
8. Actualizar el índice — agrega al final de docs/adr/README.md

Leer ADR existentes

Cuando un usuario pregunta "¿por qué elegimos X?":

1. Verifica si docs/adr/ existe — si no, responde: "No se encontraron ADR en este proyecto. ¿Te gustaría empezar a registrar decisiones arquitectónicas?"
2. Si existe, escanea el índice docs/adr/README.md en busca de entradas relevantes
3. Lee los archivos ADR coincidentes y presenta las secciones de Contexto y Decisión
4. Si no se encuentra ninguna coincidencia, responde: "No se encontró ningún ADR para esa decisión. ¿Te gustaría registrar uno ahora?"

Estructura del directorio ADR

docs/
└── adr/
    ├── README.md              ← índice de todos los ADR
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← plantilla en blanco para uso manual

Formato del Índice ADR

# Registros de Decisiones Arquitectónicas

| ADR | Título | Estado | Fecha |
|-----|--------|--------|-------|
| [0001](0001-use-nextjs.md) | Usar Next.js como framework frontend | aceptado | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL sobre MongoDB como almacén de datos principal | aceptado | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | API REST sobre GraphQL | aceptado | 2026-02-01 |

Señales de detección de decisiones

Vigila estos patrones en la conversación que indican una decisión arquitectónica:

Señales explícitas

• "Vamos con X"
• "Deberíamos usar X en lugar de Y"
• "La compensación vale la pena porque..."
• "Registra esto como un ADR"

Señales implícitas (sugerir registrar un ADR — no crear automáticamente sin confirmación del usuario)

• Comparar dos frameworks o librerías y llegar a una conclusión
• Tomar una decisión de diseño de esquema de base de datos con una justificación explícita
• Elegir entre patrones arquitectónicos (monolito vs microservicios, REST vs GraphQL)
• Decidir sobre una estrategia de autenticación/autorización
• Seleccionar infraestructura de despliegue después de evaluar alternativas

Qué hace un buen ADR

Haz

• Sé específico — "Usar Prisma ORM" no "usar un ORM"
• Registra el porqué — la justificación importa más que el qué
• Incluye alternativas rechazadas — los desarrolladores futuros necesitan saber qué se consideró
• Declara las consecuencias honestamente — cada decisión tiene compensaciones
• Mantenlo breve — un ADR debe poder leerse en 2 minutos
• Usa tiempo presente — "Usamos X" no "Usaremos X"

No hagas

• Registrar decisiones triviales — las decisiones sobre nombres de variables o formato no necesitan ADR
• Escribir ensayos — si la sección de contexto supera las 10 líneas, es demasiado larga
• Omitir alternativas — "simplemente lo elegimos" no es una justificación válida
• Rellenar sin marcarlo — si registras una decisión pasada, indica la fecha original
• Dejar que los ADR se vuelvan obsoletos — las decisiones reemplazadas deben referenciar su reemplazo

Ciclo de vida del ADR

propuesto → aceptado → [obsoleto | reemplazado por ADR-NNNN]

• propuesto: la decisión está en discusión, aún no está comprometida
• aceptado: la decisión está en vigor y se está siguiendo
• obsoleto: la decisión ya no es relevante (por ejemplo, funcionalidad eliminada)
• reemplazado: un ADR más nuevo reemplaza a este (siempre enlaza al reemplazo)

Categorías de decisiones que vale la pena registrar

Categoría	Ejemplos
Elecciones tecnológicas	Framework, lenguaje, base de datos, proveedor de nube
Patrones arquitectónicos	Monolito vs microservicios, basado en eventos, CQRS
Diseño de API	REST vs GraphQL, estrategia de versionado, mecanismo de autenticación
Modelado de datos	Diseño de esquema, decisiones de normalización, estrategia de caché
Infraestructura	Modelo de despliegue, pipeline CI/CD, stack de monitoreo
Seguridad	Estrategia de autenticación, enfoque de cifrado, gestión de secretos
Pruebas	Framework de pruebas, objetivos de cobertura, equilibrio E2E vs integración
Proceso	Estrategia de ramificación, proceso de revisión, cadencia de lanzamiento

Integración con otras habilidades

• Agente planificador: cuando el planificador proponga cambios arquitectónicos, sugiere crear un ADR
• Agente revisor de código: marca los PR que introduzcan cambios arquitectónicos sin un ADR correspondiente