¿Qué hace Registros de Decisiones Arquitectónicas (ADR)?
Capture las decisiones arquitectónicas a medida que ocurren durante las sesiones de codificación. En lugar de que las decisiones queden 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 activar
- El usuario dice explícitamente "registremos esta decisión" o "ADR esto"
- El usuario elige entre alternativas significativas (framework, biblioteca, patrón, base de datos, diseño de API)
- El usuario dice "decidimos que..." 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
Utilice el formato ADR ligero propuesto por Michael Nygard, adaptado para el 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 expongan 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:
- Inicializar (solo la primera vez) — si
docs/adr/no existe, pregunte al usuario confirmación antes de crear el directorio, unREADME.mdcon el encabezado de la tabla de índice (consulte Formato de Índice ADR más abajo) y unatemplate.mden blanco para uso manual. No cree archivos sin consentimiento explícito. - Identificar la decisión — extraer la elección arquitectónica central que se está tomando
- Recopilar contexto — ¿qué problema motivó esto? ¿Qué restricciones existen?
- Documentar alternativas — ¿qué otras opciones se consideraron? ¿Por qué fueron rechazadas?
- Declarar consecuencias — ¿cuáles son las compensaciones? ¿Qué se vuelve más fácil o más difícil?
- Asignar un número — escanear ADR existentes en
docs/adr/e incrementar - Confirmar y escribir — presentar el borrador del ADR al usuario para revisión. Solo escribir en
docs/adr/NNNN-titulo-decision.mddespués de la aprobación explícita. Si el usuario rechaza, descartar el borrador sin escribir ningún archivo. - Actualizar el índice — añadir al final de
docs/adr/README.md
Leer ADR Existentes
Cuando un usuario pregunta "¿por qué elegimos X?":
- Verificar si
docs/adr/existe — si no, responder: "No se encontraron ADR en este proyecto. ¿Desea comenzar a registrar decisiones arquitectónicas?" - Si existe, escanear el índice
docs/adr/README.mden busca de entradas relevantes - Leer los archivos ADR coincidentes y presentar las secciones de Contexto y Decisión
- Si no se encuentra coincidencia, responder: "No se encontró un ADR para esa decisión. ¿Desea registrar uno ahora?"
Estructura del Directorio de ADR
docs/
└── adr/
├── README.md ← índice de todos los ADR
├── 0001-usar-nextjs.md
├── 0002-postgres-sobre-mongo.md
├── 0003-rest-sobre-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-usar-nextjs.md) | Usar Next.js como framework frontend | aceptado | 2026-01-15 |
| [0002](0002-postgres-sobre-mongo.md) | PostgreSQL sobre MongoDB para almacén de datos principal | aceptado | 2026-01-20 |
| [0003](0003-rest-sobre-graphql.md) | API REST sobre GraphQL | aceptado | 2026-02-01 |
Señales de Detección de Decisiones
Esté atento a 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 bibliotecas y llegar a una conclusión
- Tomar una decisión de diseño de esquema de base de datos con fundamentos declarados
- 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
Hacer
- Ser específico — "Usar Prisma ORM" no "usar un ORM"
- Registrar el porqué — la justificación importa más que el qué
- Incluir alternativas rechazadas — los futuros desarrolladores necesitan saber qué se consideró
- Declarar las consecuencias honestamente — cada decisión tiene compensaciones
- Mantenerlo breve — un ADR debe ser legible en 2 minutos
- Usar tiempo presente — "Usamos X" no "Usaremos X"
No Hacer
- Registrar decisiones triviales — elecciones de nombres de variables o formato no necesitan ADR
- Escribir ensayos — si la sección de contexto supera 10 líneas, es demasiado larga
- Omitir alternativas — "simplemente lo elegimos" no es una justificación válida
- Retroceder sin marcarlo — si se registra una decisión pasada, anotar la fecha original
- Dejar que los ADR se vuelvan obsoletos — las decisiones reemplazadas deben hacer referencia a 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 comprometida
- aceptado: la decisión está en vigor y se está siguiendo
- obsoleto: la decisión ya no es relevante (ej., funcionalidad eliminada)
- reemplazado: un ADR más nuevo reemplaza a este (siempre enlazar el 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, balance E2E vs integración |
| Proceso | Estrategia de ramificación, proceso de revisión, cadencia de lanzamientos |
Integración con Otras Habilidades
- Agente planificador: cuando el planificador propone cambios de arquitectura, sugerir crear un ADR
- Agente revisor de código: marcar PRs que introduzcan cambios arquitectónicos sin un ADR correspondiente