¿Qué hace Registros de Decisiones de Arquitectura?
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, este skill 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, librería, 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 ADRs existentes)
- Durante fases de planificación donde se discuten compensaciones arquitectónicas
Formato ADR
Utiliza 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 proponemos y/o estamos haciendo?
[1-3 oraciones que establezcan la decisión claramente]
## Alternativas Consideradas
### Alternativa 1: [Nombre]
- **Ventajas**: [beneficios]
- **Desventajas**: [inconvenientes]
- **Por qué no**: [razón específica por la que fue rechazada]
### Alternativa 2: [Nombre]
- **Ventajas**: [beneficios]
- **Desventajas**: [inconvenientes]
- **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, preguntar al usuario confirmación antes de crear el directorio, unREADME.mdcon el encabezado de la tabla de índice (ver Formato del Índice ADR más abajo) y unatemplate.mden blanco para uso manual. No crear archivos sin consentimiento explícito. - Identificar la decisión — extraer la elección arquitectónica central que se está tomando
- Recopilar contexto — ¿qué problema la provocó? ¿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/más difícil?
- Asignar un número — escanear los ADRs 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 — agregar al final de
docs/adr/README.md
Leer ADRs Existentes
Cuando un usuario pregunta "¿por qué elegimos X?":
- Verificar si
docs/adr/existe — si no, responder: "No se encontraron ADRs en este proyecto. ¿Te gustaría 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. ¿Te gustaría registrar uno ahora?"
Estructura del Directorio ADR
docs/
└── adr/
├── README.md ← índice de todos los ADRs
├── 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 de Arquitectura
| 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 como almacén 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
Observa 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 fundamentos explícitos
- Elegir entre patrones arquitectónicos (monolito vs microservicios, REST vs GraphQL)
- Decidir sobre 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é — los fundamentos importan más que el qué
- Incluir alternativas rechazadas — los futuros desarrolladores necesitan saber qué se consideró
- Declarar consecuencias honestamente — toda decisión tiene compensaciones
- Mantenerlo corto — un ADR debe poderse leer en 2 minutos
- Usar tiempo presente — "Usamos X" no "Usaremos X"
No Hacer
- Registrar decisiones triviales — nombres de variables o elecciones de formato no necesitan ADRs
- Escribir ensayos — si la sección de contexto supera las 10 líneas, es demasiado larga
- Omitir alternativas — "simplemente lo elegimos" no es un fundamento válido
- Retroceder sin marcarlo — si se registra una decisión pasada, anotar la fecha original
- Dejar que los ADRs 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 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 cloud |
| Patrones arquitectónicos | Monolito vs microservicios, orientado a 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 lanzamiento |
Integración con Otros Skills
- 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