2369. Identidad de la lección
2370. Objetivo de aprendizaje
Después de esta lección, podrás redactar un registro de decisión arquitectónica que compare opciones acotadas, declare el camino elegido, identifique sus riesgos, defina la evidencia necesaria para reconsiderarlo y registre un punto de control recuperable.
2371. Por qué importa
La dirección técnica no consiste en escoger la arquitectura más sofisticada. En un proyecto de juego, cada sistema adicional aumenta el coste de implementación, pruebas, depuración y cambios posteriores. La IA puede producir diseños plausibles con rapidez, pero la plausibilidad no demuestra que un diseño encaje en el proyecto. Un registro breve hace visible el razonamiento y permite cambiar de rumbo cuando aparece nueva evidencia.
2372. Conocimientos previos
Debes poder:
- distinguir un requisito del jugador de una preferencia de implementación;
- identificar riesgos y priorizar la intervención más segura, como se practicó en 5.13 L2 — Prioritize the safest intervention;
- describir una funcionalidad acotada y sus evidencias de aceptación;
- comparar opciones usando restricciones en lugar de novedad.
No se requiere un motor, framework o código concreto para este estudio de caso.
2373. Concepto central
Elige la opción menos compleja que satisfaga el requisito actual y conserve un camino deliberado para aprender o cambiar después. La decisión también debe nombrar las herramientas usadas para registrarla, evaluarla y revisarla —por ejemplo, el gestor de tareas del proyecto, el documento ADR, la herramienta de pruebas o perfilado y la interfaz de control de versiones—. La elección de herramientas forma parte de la dirección técnica: una opción que no puede inspeccionarse con los medios disponibles para el equipo no es suficiente en términos operativos.
Una decisión técnica no es solo una elección. Es una afirmación:
Dados estos requisitos, restricciones y evidencias actuales, esta opción es suficiente y sus riesgos son aceptables.
Un buen registro deja explícitos cuatro aspectos:
- Compensaciones: qué mejora la opción y a qué se renuncia.
- Riesgo: qué puede fallar y cuánto costaría ese fallo.
- Reversibilidad: qué tan difícil sería sustituir la elección más adelante.
- Evidencia: qué observación confirmaría, cuestionaría o reabriría la decisión.
2374. Modelo mental
La prueba del camino suficiente
| Pregunta | Prueba de decisión |
|---|---|
| ¿Satisface el requisito? | Descarta opciones que no puedan cumplir la necesidad declarada. |
| ¿Qué cuesta ahora? | Incluye implementación, pruebas, depuración y carga cognitiva. |
| ¿Qué riesgo introduce? | Nombra el modo de fallo en lugar de usar preocupaciones vagas. |
| ¿Se puede revertir? | Cuando la evidencia es débil, prefiere un límite contenido. |
| ¿Qué evidencia cambiaría la decisión? | Define una señal observable para revisarla. |
Un registro útil tiene esta estructura:
Título
Estado: propuesto / aceptado / sustituido
Contexto y restricciones
Decisión
Opciones consideradas
Compensaciones y riesgos
Límite de reversibilidad
Evidencia y condición de revisión
Consecuencias
No ordenes las opciones por prestigio. Ordénalas por su ajuste al alcance actual y por el coste de equivocarse.
2375. Ejemplo concreto
Este caso hipotético está deliberadamente acotado.
Un prototipo pequeño necesita recordar tres ajustes entre sesiones: volumen de audio, modo de pantalla y una preferencia de controles. El equipo tiene dos semanas para hacer que la funcionalidad sea fiable. No existe un requisito actual de sincronización en la nube, uso en varios dispositivos ni cuentas de usuario.
| Opción | Beneficio inmediato | Coste o riesgo | Reversibilidad |
|---|---|---|---|
| Guardar un registro local de ajustes con versión | Superficie de implementación pequeña; fácil de probar sin conexión | Requiere una ruta de migración si cambian los campos | Alta si el acceso queda aislado detrás de una interfaz de ajustes |
| Añadir un servicio remoto de ajustes vinculado a cuentas | Permite sincronización futura | Añade autenticación, fallos de red, seguridad y pruebas del servicio | Baja o media en este prototipo porque muchos sistemas dependerían de él |
Para el alcance indicado, una decisión suficiente es usar el registro local, siempre que el acceso quede aislado y el registro tenga una versión. La decisión no afirma que la sincronización remota nunca sea útil. Afirma que el requisito actual no justifica su coste y riesgo.
La condición de revisión podría ser: “Reabrir esta decisión si la sincronización de ajustes entre dispositivos se convierte en un requisito aprobado”. Esto es más sólido que “usar una solución mejor después”, porque nombra una evidencia observable.
2376. Flujo de trabajo con IA
Usa la IA como herramienta de comparación y crítica, no como autoridad que selecciona la arquitectura.
- Redacta tú los requisitos, las restricciones y las dos opciones.
- Pide a la IA que identifique supuestos ocultos, modos de fallo probables y evidencias faltantes. No le pidas que elija primero.
- Compara su análisis con las restricciones del proyecto. Marca cada sugerencia como aceptada, rechazada o requiere evidencia.
- Pide a la IA que cuestione tu opción preferida mediante un escenario de fallo.
- Redacta el registro final con tus propias palabras.
Un prompt útil es:
Actúa como un revisor técnico escéptico. Dado este requisito, estas restricciones y estas dos opciones, enumera las compensaciones, los modos de fallo, las preocupaciones de reversibilidad y la evidencia que justificaría reabrir la decisión. No elijas una opción por mí ni inventes requisitos del proyecto.
El estudiante sigue siendo responsable del requisito, la decisión y el umbral de evidencia.
2377. Error común
El error común es elegir una arquitectura porque parece preparada para el futuro. Una posibilidad futura no es automáticamente un requisito presente. Construir de más puede reducir la reversibilidad al repartir una sola decisión entre autenticación, datos, pruebas, despliegue y depuración. Una opción sencilla tampoco es automáticamente correcta: debe satisfacer el requisito y ofrecer un límite seguro para cambios posteriores.
2378. Práctica guiada
Redacta un registro de decisión arquitectónica para este caso hipotético:
Un prototipo de juego de dos semanas necesita mostrar un resumen al terminar cada sesión. El resumen debe incluir la puntuación, el tiempo transcurrido y las cantidades de tres objetos recogidos. No necesita compartirse en línea, conservarse entre dispositivos ni consultarse desde herramientas externas. El equipo puede (A) pasar un objeto inmutable de resumen directamente desde el sistema de partida hasta la pantalla de resultados, lo que minimiza la infraestructura nueva pero acopla esa transferencia a ambos sistemas, o (B) guardar el último resumen en un pequeño repositorio que consulte la pantalla de resultados, lo que añade riesgos de ciclo de vida y datos obsoletos, pero proporciona un límite estable si se confirma que otra pantalla del prototipo necesita los mismos datos.
Completa estos pasos:
- Declara el requisito y al menos tres restricciones.
- Compara A y B según coste inmediato, riesgo de fallo y reversibilidad.
- Elige una opción, explica por qué es suficiente ahora, presenta el argumento más sólido a favor de la alternativa e indica qué evidencia sobre la reutilización o el riesgo del ciclo de vida respaldaría tu elección o te haría cambiarla.
- Nombra un límite que facilite sustituirla más adelante.
- Define una condición observable para revisarla.
- Registra una consecuencia que el equipo acepta.
- Crea un punto de control de decisión revisable que contenga el ADR, su estado y la opción elegida. Usa el flujo de trabajo de Git del proyecto para realizar un commit significativo cuyo mensaje identifique la decisión y su alcance. Solo si Git no está realmente disponible, documenta en el ADR una excepción equivalente y justificada que indique por qué no puede usarse Git, la ubicación exacta de la instantánea versionada o del punto de revisión y quién la verificó.
- Documenta una ruta de recuperación: indica qué punto de control se restauraría, qué evidencia justificaría revertir o sustituir la decisión y qué debe revisarse antes de continuar. No implementes la arquitectura ni realices trabajo específico del motor.
Tu registro debe ser lo bastante específico para que otro desarrollador pueda discrepar por una razón concreta, no solo porque prefiera otro estilo.
2379. Validación / evidencia
Tu trabajo supera esta lección cuando el ADR contiene todo lo siguiente:
- un requisito acotado, no una ambición técnica amplia;
- restricciones explícitas, incluida al menos una de tiempo o alcance;
- al menos dos opciones consideradas;
- una opción elegida por su ajuste, no por su novedad, junto con el argumento más sólido a favor de la alternativa;
- la evidencia que respalda la elección y la que justificaría cambiarla;
- un riesgo nombrado y su consecuencia probable;
- un límite de reversibilidad;
- una condición observable que reabra la decisión;
- consecuencias que el equipo acepta;
- un punto de control de decisión revisable, representado por un commit significativo de Git; solo se admite un punto de revisión versionado equivalente mediante una excepción documentada y justificada que indique la limitación, su ubicación exacta y quién la verificó;
- una ruta de recuperación documentada que identifique el punto de control que se restauraría o sustituiría y la evidencia necesaria para hacerlo.
El punto de control debe permitir que otra persona inspeccione la decisión sin reconstruir el razonamiento a partir de cambios no relacionados. La ruta de recuperación debe explicar cómo volver a la última decisión aceptada o sustituirla formalmente; no debe depender de recuerdos no registrados.
Si el registro solo dice “la opción A es más sencilla”, revísalo. La sencillez solo es útil cuando se relaciona con el alcance, el riesgo, la evidencia y un punto de revisión recuperable.
2380. Puntos clave
- La dirección técnica es una decisión bajo restricciones, no una búsqueda de la arquitectura más impresionante.
- Evalúa las opciones por ajuste al requisito, coste presente, riesgo y reversibilidad.
- Un registro de decisión debe declarar qué evidencia provocaría una revisión.
- Un punto de control significativo y una ruta de recuperación hacen que la decisión sea revisable en la práctica.
- La IA puede revelar supuestos y modos de fallo, pero el desarrollador controla las restricciones y la decisión final.
2381. Siguiente lección
Continúa con 5.14 L2 — Definir controles técnicos para un equipo pequeño.
2382. Comprobación
Responde estas preguntas por tu cuenta antes de leer las respuestas.
¿Cuál es la razón más sólida para elegir una opción técnica más sencilla?
Mostrar respuesta y explicación
Respuesta: Satisface el requisito actual con un coste y un riesgo aceptables.
Por qué: La sencillez es valiosa cuando encaja con el requisito y mantiene el coste y el riesgo dentro de las restricciones del proyecto. No es automáticamente correcta ni está siempre preparada para el futuro.
¿Qué afirmación es la mejor condición de revisión para una decisión arquitectónica?
Mostrar respuesta y explicación
Respuesta: Revisar la decisión si se añade un requisito comprometido de sincronización entre dispositivos.
Por qué: Una buena condición de revisión es observable y está vinculada a un cambio en los requisitos o en la evidencia. Tener más tiempo, una preferencia personal o una herramienta nueva no basta por sí solo.
¿Qué debe hacer la IA en el flujo de decisión descrito en esta lección?
Mostrar respuesta y explicación
Respuesta: Exponer supuestos, modos de fallo y evidencias faltantes para que el desarrollador los evalúe.
Por qué: La IA es útil como herramienta de comparación y crítica. El desarrollador todavía debe establecer las restricciones, juzgar la evidencia y asumir la decisión final.
¿Qué elemento necesita un registro de decisión para abordar la reversibilidad?
Mostrar respuesta y explicación
Respuesta: Un límite que contenga la elección y facilite su sustitución.
Por qué: La reversibilidad mejora cuando la decisión queda aislada detrás de un límite claro, lo que reduce la cantidad de sistemas que deben cambiar si se sustituye la elección.