---

machine-translated to es from skills/architecture-decision-record/SKILL.md — review: pending. Native fixes welcome via PR.

name: architecture-decision-record description: "Crea un Registro de Decisión de Arquitectura (ADR) para cualquier decisión técnica. Úsalo cuando necesites documentar una decisión técnica, escribir un ADR, registrar una elección arquitectónica o capturar por qué se seleccionó una tecnología o enfoque. Produce un ADR estructurado con contexto, decisión, consecuencias e intercambios."

Habilidad de Registro de Decisión de Arquitectura (ADR)

Esta habilidad produce un Registro de Decisión de Arquitectura (ADR) completo siguiendo el formato Nygard — el estándar más ampliamente adoptado. Los ADRs documentan el razonamiento detrás de decisiones técnicas significativas para que los futuros miembros del equipo entiendan no solo qué se decidió, sino por qué.

Inputs Requeridos

Trabaja con lo que se proporciona. Si falta algo de esto, aun así produce el resultado completo: rellena cada vacío con una suposición razonable marcada como (asumido, confirmar) y lista esas suposiciones al final. Solo haz una pregunta cuando falta el tema central en sí (no hay nada sobre lo que escribir).

• Número de ADR (número secuencial en tu registro de ADR — p. ej. 012; o "siguiente disponible" si es desconocido)
• Título de la decisión (breve, p. ej. "Usar PostgreSQL como almacén de datos principal")
• Contexto (¿qué situación llevó a que esta decisión fuera necesaria?)
• Opciones consideradas (al menos 2; si solo se da 1, solicita alternativas que fueron consideradas o descartadas)
• Decisión tomada (qué opción fue elegida)
• Razón de la elección
• Estado (Propuesto / Aceptado / Deprecado / Reemplazado)
• Autor y fecha
• Contexto del equipo (opcional — tamaño del equipo, experiencia relevante, restricciones organizacionales; ayuda a calibrar la formalidad y profundidad de la sección de Contexto)

Formato de Salida

---

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

Fecha: [YYYY-MM-DD] Estado: [Propuesto / Aceptado / Deprecado / Reemplazado por ADR-NNN] Autor(es): [Nombre(s)] Responsables de la decisión: [Quién tuvo la palabra final — individuo o equipo]

---

Contexto

[3–6 oraciones. Describe la situación, restricciones y fuerzas en juego que hicieron necesaria esta decisión. Incluye: el problema a resolver, estado relevante del sistema, restricciones del equipo, presiones de cronograma o requisitos innegociables. Escribe como si explicaras a alguien que se une al equipo 18 meses después sin contexto previo.]

Restricciones clave:

• [Restricción 1: p. ej. "Debe ser desplegable on-premise para clientes empresariales"]
• [Restricción 2: p. ej. "El equipo no tiene experiencia previa con Go"]
• [Añade todas las que sean relevantes]

---

Opciones Consideradas

Para cada opción, produce:

Opción [N]: [Nombre]

Descripción: [Qué es esta opción — 1–3 oraciones]

Ventajas:

• [Ventaja 1]
• [Ventaja 2]

Desventajas:

• [Desventaja 1]
• [Desventaja 2]

Por qué fue descartada (si no fue elegida): [Razón honesta]

---

Decisión

Usaremos [opción elegida].

[2–4 oraciones explicando la decisión en lenguaje plano. Debería ser legible de forma aislada — alguien debería entender la decisión solo con este párrafo sin leer el documento completo.]

---

Consecuencias

Consecuencias Positivas

• [Qué esta decisión permite o mejora]
• [Qué riesgo mitiga]

Consecuencias Negativas / Intercambios Aceptados

• [Qué estamos abandonando o asumiendo como resultado de esta decisión]
• [Deuda técnica o limitaciones introducidas]
• [Qué debe ser verdadero para que esta decisión siga siendo válida]

Riesgos

• [Qué podría hacer que esta decisión fuera incorrecta en retrospectiva]
• [Qué nos haría reconsiderar esta decisión]

---

Notas de Implementación

[Incluye si la decisión tiene gotchas de implementación no obvios, o si hay tickets/RFCs relacionados que los implementadores necesitarán. Omite solo si la decisión es puramente selección de herramientas sin ambigüedad de implementación.]

---

Fecha de Revisión

[Incluye a menos que la decisión sea permanente o evidentemente final. Establece una condición de disparo específica — p. ej. "Revisar si el equipo crece más allá de 20 ingenieros o el tráfico supera 10M requests/día" — no solo "debería revisarse periódicamente".]

---

Materiales Más Profundos

Esta habilidad se entrega con archivos de apoyo — úsalos cuando estén disponibles:

• references/decision-scoping.md — Qué Merece un ADR (y Qué Debe Contener el "Contexto"). Aplícalo mientras produces el resultado; contiene los juicios y decisiones de calibración que el resumen del método anterior comprime.
• templates/adr.md — una versión para rellenar del entregable con los gates de calidad inline. Ofrécela cuando el usuario quiera trabajar el documento él mismo en lugar de tenerlo generado.

Rúbrica de Puntuación (0–40)

Puntúa cualquier salida de esta habilidad antes de entregarla; 32+ es de calidad para producción.

Dimensión	0	5	10
Reconstrucción del contexto	Asume que el lector ya conoce el problema y las presiones	Problema enunciado, pero faltan las fuerzas (restricciones del equipo, escala, plazo, evento que fuerza)	Un lector dos años después podría adivinar la decisión solo desde la sección de Contexto
Honestidad de opciones	Solo la opción elegida, u opciones rechazadas escritas como espantapájaros	≥2 opciones, pero las razones de rechazo son circulares ("no cumplieron los requisitos")	Cada opción rechazada tiene fortalezas genuinas y una restricción perdedora específica vinculada a una presión del contexto
Balance de consecuencias	Todas las consecuencias son positivas	Negativas simbólicas sin especificidades operacionales	Los negativos nombran deudas reales, nuevas cargas operacionales y qué debe mantenerse verdadero para que la decisión se sostenga
Disparadores de revisión	No se indican riesgos o condiciones de revisión	"Revisar periódicamente" — sin condición medible	Condiciones de disparo específicas y medibles que invalidarían la decisión, con un responsable

Verificaciones de Calidad

• El Contexto explica el por qué — no solo el qué
• Al menos 2 opciones están documentadas (incluyendo las rechazadas)
• Las opciones rechazadas incluyen razones honestas de rechazo
• Las Consecuencias incluyen consecuencias negativas — ninguna decisión está libre de consecuencias
• La Decisión está enunciada en lenguaje plano en la sección de Decisión
• La sección de Riesgos identifica qué invalidaría esta decisión
• La sección de Contexto enuncia el problema explícitamente en sus primeras 1–2 oraciones (no asume que el lector sepa qué problema estaba resolviendo el equipo)
• La explicación "Por qué fue descartada" de cada opción rechazada nombra una restricción o intercambio específico (no una declaración circular como "no cumplió nuestros requisitos")

Anti-Patrones

• No escribas un ADR después de que la decisión ya haya sido completamente implementada y el equipo haya avanzado — los ADRs escritos retrospectivamente a menudo omiten las razones reales y alternativas
• No listes solo la opción elegida — las opciones rechazadas con razones honestas son la parte más valiosa de un ADR para lectores futuros
• No escribas consecuencias que sean todas positivas — cada decisión arquitectónica implica intercambios; un ADR sin consecuencias negativas no fue escrutinizado honestamente
• No dejes el estado como "Propuesto" indefinidamente — un ADR que nadie ha aprobado no está guiando las decisiones de nadie
• No escribas contexto que asuma que el lector ya sabe qué problema se estaba resolviendo — la sección de contexto existe precisamente para lectores sin ese antecedente

Ejemplos de Uso

• "Escribe un ADR para usar [tecnología]"
• "Documenta nuestra decisión de [elección arquitectónica]"
• "Crea un registro de decisión de arquitectura para [tema]"
• "Ayúdame a redactar por qué elegimos [opción] sobre [alternativa]"

Frases de Disparo de Ejemplo

• "Documenta una decisión técnica."
• "Escribe un ADR."
• "Registra una elección arquitectónica."
• "Captura por qué una tecnología."