Decisión Arquitectónica
Convierte una pregunta arquitectónica en una decisión específica, justificada y verificable.
Esta habilidad es dueña del método de decisión, el ciclo de vida del registro y el entregable. engineering-philosophy es dueña de los principios compartidos de diseño y escritura. El agente activo y la tarea son dueños de los permisos, la delegación y la intención de salida.
1. Establecer la Decisión
Indica la pregunta, el sistema afectado, el resultado requerido y las exclusiones de alcance.
Una decisión merece un ADR cuando afecta materialmente contratos entre componentes, requisitos de calidad, propiedad, confianza, operaciones, dependencias o el costo de cambios futuros.
No requieras un ADR para diseño local rutinario. Devuelve no-adr-needed con la respuesta y una breve justificación a menos que el solicitante pida explícitamente un registro formal.
Identifica decisiones relacionadas. Separa elecciones independientemente reversibles en registros separados, pero no fragmentes una decisión coherente en un ADR por cada paso de implementación.
Para un ADR existente, establece si la tarea es aclaración, reevaluación o reemplazo. No conviertas silenciosamente una explicación histórica en una nueva recomendación.
2. Establecer Contexto y Motivadores
Lee las instrucciones aplicables, las decisiones aceptadas relevantes y suficiente evidencia de implementación para entender los límites afectados.
Establece lo que existe antes de describir lo que debería existir. Para trabajo desde cero, usa los requisitos proporcionados y etiqueta la ausencia de evidencia de implementación.
Separa:
- Restricciones duras: contratos requeridos, políticas, compatibilidad, reglas de datos o límites explícitos.
- Motivadores de decisión: las cualidades y compensaciones que distinguen las opciones viables.
- Suposiciones: condiciones no verificadas de las que depende la recomendación.
Determina qué motivadores importan más. Infiere una prioridad provisional solo cuando sea defendible, y etiquétala. Pide autoridad cuando una prioridad no resuelta cambiaría materialmente el comportamiento del producto, el costo o la aceptación del riesgo.
Haz concretas las metas vagas. Para requisitos de rendimiento o confiabilidad, identifica la carga de trabajo, el escenario de falla, el resultado observable y el umbral cuando se conozcan. Etiqueta un umbral inventado para discusión como propuesto, nunca como un requisito.
No fabriques tráfico, objetivos de nivel de servicio, plazos, capacidad del equipo, costos o requisitos futuros para justificar un diseño.
3. Resolver Incógnitas que Cambian la Decisión
Investiga incertidumbres que podrían cambiar la viabilidad, clasificación, seguridad o alcance de la implementación.
Prefiere evidencia local para el sistema actual. Usa documentación primaria para el comportamiento externo y verifica la versión y el entorno relevantes.
Distingue observación directa, evidencia proporcionada, inferencia e hipótesis no probada. La capacidad de un proveedor no establece que la configuración local la habilite.
Detén la investigación cuando la evidencia respalde la decisión o sea poco probable que una lectura adicional la cambie.
Cuando sea necesaria la medición, define un experimento acotado: pregunta, carga de trabajo representativa, línea base de comparación, resultado observable, criterio de aprobación/falla y cómo el resultado cambiaría la elección.
No afirmes que el experimento se ejecutó. Devuelve la solicitud de evidencia específica cuando la ejecución o el acceso a la fuente estén fuera de los permisos del agente activo.
4. Comparar Opciones Creíbles
Considera retener el diseño actual y el cambio más pequeño suficiente. Explica cuándo alguno de ellos falla una restricción dura.
Compara solo alternativas plausibles. No inventes candidatos débiles para hacer ganar a un favorito, no requieras un número fijo de opciones ni investigues cada producto en una categoría.
Evalúa las opciones con los mismos motivadores de decisión. Incluye el esfuerzo de migración relevante, la propiedad operativa, el manejo de fallas, el costo recurrente, el acoplamiento y la reversibilidad.
Rechaza explícitamente las violaciones de restricciones duras. No las promedies con una puntuación ponderada.
Prefiere comparaciones cualitativas con razones concretas. Usa puntuación numérica solo cuando sus entradas y ponderaciones sean defendibles; expón la sensibilidad a entradas inciertas.
La popularidad de una tecnología, un patrón arquitectónico nombrado o la escalabilidad reclamada no es un beneficio específico del proyecto por sí mismo.
5. Desafiar la Opción Preferida
Traza la ruta de éxito importante y la ruta de falla más consecuente y creíble a través de los límites propuestos.
Considera solo preocupaciones relevantes:
- Propiedad y contratos: estado autoritativo, dependencias permitidas, compatibilidad, transacciones y propiedad del ciclo de vida.
- Falla y recuperación: finalización parcial, entrega duplicada, ordenamiento, reintentos, tiempos de espera, cancelación, sobrecarga y reparación.
- Seguridad y privacidad: límites de confianza, autorización, aislamiento, datos sensibles y rutas de abuso creíbles.
- Operación y cambio: despliegue, observabilidad, límites de recursos, evidencia de capacidad, migración, soporte continuo y costo de salida.
Usa la referencia de Arquitectura para principios de diseño en lugar de reproducir sus leyes aquí.
Indica la objeción más fuerte a la recomendación y la evidencia que podría anularla. Verifica si una opción más simple satisface las mismas restricciones.
Para transiciones riesgosas, describe la coexistencia y la recuperación. Identifica el punto más allá del cual la reversión no es segura o imposible. Usa una estrategia de avance o reparación cuando la reversión perdería datos o rompería la compatibilidad.
Describe los estados actual, transicional y objetivo solo cuando sus diferencias importen. No produzcas un diagrama meramente para decorar la decisión.
6. Decidir
Recomienda una dirección cuando la evidencia la respalde. Nombra el motivador decisivo y el costo o limitación que el equipo aceptaría.
Procede bajo suposiciones reveladas cuando no invaliden una recomendación segura. No te bloquees por incógnitas inmateriales.
Cuando una suposición material permanezca sin resolver, indica la preferencia provisional y la condición exacta que la cambiaría. No la presentes como un compromiso incondicional.
Cuando ninguna opción satisfaga las restricciones duras, dilo. Identifica el cambio de restricción o el experimento más pequeño necesario; no debilites silenciosamente los requisitos.
Usa un resultado de tarea:
| Resultado | Significado |
|---|---|
recommended | Una recomendación específica está respaldada dentro de las restricciones y suposiciones indicadas. La aprobación normal aún puede estar pendiente. |
needs-evidence | Una brecha de evidencia nombrada impide una selección confiable. Incluye la preferencia provisional y la verificación resolutiva cuando sea posible. |
needs-authority | Un requisito material, excepción o decisión de riesgo debe ser resuelto por una persona autorizada. Explica la recomendación técnica y la autoridad precisa necesaria. |
no-adr-needed | La pregunta es diseño local rutinario. Respóndela sin imponer un proceso arquitectónico formal. |
Estos resultados describen el resultado de la tarea, no la aprobación del ADR, la finalización de la implementación o los veredictos de revisión de código.
7. Registrar la Decisión
Usa la convención de ADR del repositorio cuando exista una. De lo contrario, lee la plantilla de ADR y adáptala a la decisión.
Un registro debe preservar la pregunta, el contexto, los motivadores decisivos, la dirección elegida, las alternativas creíbles, las desventajas aceptadas, la incertidumbre y las condiciones de validación. Mantenlo lo suficientemente corto como para mantenerlo.
Un registro contiene una decisión arquitectónica coherente. Vincula registros relacionados en lugar de copiar su justificación.
Si no existe una convención de almacenamiento, sugiere docs/decisions/. Inspecciona la numeración existente antes de proponer un identificador final. Una ruta sugerida no es un archivo guardado.
Ciclo de Vida y Autoridad
Por defecto, un nuevo ADR está en propuesto.
Usa aceptado solo cuando la aceptación esté evidenciada por la autoridad designada o el proyecto delegue explícitamente esa decisión al solicitante o agente activo. Registra la base de la aceptación. Una solicitud para recomendar, redactar o evaluar no es aceptación.
Una opción técnica seleccionada puede permanecer propuesta pendiente de aprobación normal. No uses needs-authority meramente porque esa aprobación aún no haya ocurrido.
Sigue los estados restantes del ciclo de vida del proyecto. Sin una convención, usa rechazado, deprecado y reemplazado según corresponda.
Preserva la justificación histórica aceptada. Una decisión materialmente cambiada obtiene un nuevo registro con una relación de reemplazo. El registro antiguo permanece disponible; un escritor autorizado actualiza su estado y el enlace de reemplazo cuando se acepta la nueva decisión.
Una implementación que contradice un ADR no lo reemplaza automáticamente. Establece si la implementación, la decisión registrada o el requisito rector necesita corrección.
La aceptación no establece implementación, verificación operativa o permiso para desplegar.
Evidencia y Confirmación
Cita afirmaciones consecuentes junto al contexto o la justificación que respaldan. Usa referencias de repositorio duraderas y fuentes externas específicas de la versión cuando estén disponibles.
No uses identificadores de sesión inaccesibles como la única evidencia en un ADR duradero. Conserva enlaces a las fuentes subyacentes o atribuye la evidencia proporcionada claramente.
Define verificaciones que confirmen tanto la conformidad arquitectónica como el resultado prometido. Conecta cada invariante importante con una verificación observable.
Usa comandos compatibles con el proyecto solo cuando se conozcan. De lo contrario, describe la prueba o inspección sin inventar instrucciones ejecutables.
Marca las verificaciones futuras como no ejecutadas. Identifica al propietario por rol establecido cuando se conozca, o deja la propiedad sin resolver. No asignes trabajo a una persona no involucrada.
Define un desencadenante concreto de revisión: una validación fallida, una restricción cambiada, un umbral medido o un cambio de dependencia relevante. "Revisar cuando sea necesario" no es útil.
Entregable
Sigue un formato explícito del solicitante. De lo contrario, comienza con un breve resumen de decisión:
- Recomendación: la dirección seleccionada y la razón decisiva, o la elección no resuelta.
- Resultado: uno de los cuatro resultados de tarea.
- Alcance: límite afectado y exclusiones importantes.
- Confianza: alta, media o baja, con la evidencia y las suposiciones que justifican la etiqueta. No presentes esto como una probabilidad medida.
Para una decisión material, devuelve el ADR completo. Cuando la selección permanezca bloqueada, mantenlo propuesto y etiqueta la elección como provisional o no resuelta.
Agrega una breve transferencia solo cuando sea necesario. Identifica restricciones vinculantes, evidencia o autoridad no resuelta, y el próximo rol responsable. Haz referencia al ADR en lugar de repetir su contenido.
No conviertas la transferencia en un plan de implementación por fases, un informe de revisión de código o un parche no solicitado.
Para no-adr-needed, devuelve la respuesta, el resultado y la justificación sin secciones de plantilla vacías a menos que el solicitante haya solicitado el registro.
Verificación Final
Confirma que el resultado responde a la decisión real, identifica una opción preferida cuando sea apoyable y explica por qué no se seleccionó la alternativa más fuerte.
Verifica restricciones duras, decisiones existentes, consecuencias operativas, afirmaciones de verificación, autoridad de aceptación y límites de alcance.
Elimina hechos inventados, puntuaciones decorativas, capas innecesarias, justificación duplicada y afirmaciones de que el trabajo no realizado está completo.