Registros de Decisiones para el Desarrollo de Software Impulsado por IA
Mantén la intención cerca del código.
Los registros de decisiones son la capa de memoria faltante en el desarrollo de software asistido por IA. Capturan no solo qué se construyó, sino por qué; y esta distinción se vuelve crítica cuando las herramientas de IA están escribiendo su código.
Los registros de decisiones son la capa de memoria faltante
La programación impulsada por IA cambia la economía del desarrollo de software al hacer que el código sea más barato de generar, más fácil de refactorizar y más rápido de desechar. Eso es útil. También es peligroso, porque cuando el código se vuelve más fácil de producir, el recurso escaso ya no es la escritura; el recurso escaso es el juicio.
¿Por qué eligió el equipo PostgreSQL en lugar de DynamoDB? ¿Por qué el producto requiere una revisión humana antes de enviar correos electrónicos generados por IA? ¿Por qué la interfaz muestra sugerencias en un panel lateral en lugar de aplicarlas directamente? ¿Por qué se rechazó un enfoque más simple hace seis meses? El código puede mostrar lo que existe, pero rara vez explica por qué existe.
Los registros de decisiones resuelven este problema proporcionando un documento corto, controlado por versiones, que captura una decisión importante, el contexto detrás de la misma, las alternativas consideradas y las consecuencias que el equipo aceptó. En una base de código asistida por IA, estos registros se convierten en algo más que documentación: se convierten en una memoria de proyecto duradera que tanto humanos como agentes de código de IA pueden leer antes de realizar cambios futuros. La regla operativa práctica es simple: mantenga los registros de decisiones como archivos Markdown en el repositorio, revíselos como código y permita que las herramientas de IA futuras los lean antes de proponer o implementar cambios.
¿Qué son los registros de decisiones?
Un registro de decisiones es un registro escrito de una decisión significativa, estructurada para responder cuatro preguntas básicas: ¿qué decidimos?, ¿por qué lo decidimos?, ¿qué alternativas consideramos? y ¿qué consecuencias aceptamos? La forma más común es el Registro de Decisiones Arquitectónicas (Architecture Decision Record, abreviado como ADR). Los ADR se utilizan ampliamente para documentar decisiones técnicas, y el mismo patrón puede extenderse más allá de la arquitectura hacia el trabajo de producto y diseño.
Para la programación impulsada por IA, tres tipos son especialmente útiles:
| Tipo de registro | Captura | Ejemplo |
|---|---|---|
| ADR | Decisiones arquitectónicas y técnicas | Usar PostgreSQL como base de datos principal |
| PDR | Decisiones de comportamiento y alcance del producto | Los correos electrónicos generados por IA deben permanecer como borradores |
| DDR | Decisiones de diseño e interacción | Mostrar sugerencias de IA en un panel lateral |
Juntos, los ADR, PDR y DDR describen no solo la estructura del sistema, sino también la intención del producto y el razonamiento detrás de la experiencia de usuario. Esta combinación es importante porque los agentes de IA pueden leer código, pero el código por sí solo no contiene suficiente contexto para tomar buenas decisiones. Los registros de decisiones ofrecen a los sistemas de IA una fuente revisada, duradera y aprobada por humanos de la intención del proyecto.
Registros de Decisiones Arquitectónicas
Los Registros de Decisiones Arquitectónicas capturan decisiones técnicas y estructurales. Utilice un ADR cuando una decisión afecte la forma del sistema: sus límites, dependencias, modelo operativo o mantenibilidad a largo plazo.
Los ejemplos de decisiones que valen la pena registrar como ADR incluyen:
- Elegir PostgreSQL como base de datos principal
- Utilizar una arquitectura impulsada por eventos para el procesamiento en segundo plano
- Mantener la aplicación como un monolito modular
- Introducir una cola de mensajes
- Elegir REST en lugar de GraphQL
- Usar renderizado del lado del servidor para la aplicación web
- Exigir que todas las tareas en segundo plano sean idempotentes
- Adoptar un modelo específico de autenticación y autorización
Un ADR no es un documento de arquitectura completo; es intencionalmente pequeño, registrando una decisión importante en un momento específico. Un buen ADR previene la amnesia arquitectónica: sin él, los contribuyentes futuros podrían redescubrir los mismos compromisos, reabrir debates antiguos o desactivar accidentalmente restricciones importantes.
En la programación impulsada por IA, los ADR tienen aún más peso. Las herramientas de IA suelen ser hábiles en la optimización local y pueden proponer un cambio técnicamente plausible que viole una restricción arquitectónica más amplia. Un ADR le da a la IA un límite claro: “Así es como se supone que debe formarse este sistema”.
Registros de Decisiones de Producto
Los Registros de Decisiones de Producto capturan el comportamiento del producto, el alcance y la intención orientada al usuario. Esto es menos común que los ADR, pero a menudo es igual de valioso: las decisiones de producto suelen estar dispersas en tickets, herramientas de hoja de ruta, hilos de chat, notas de reuniones y en la memoria de las personas, lo que las hace fáciles de olvidar para los humanos y casi imposibles de inferir de manera fiable para las herramientas de IA.
Utilice un PDR cuando una decisión afecte qué hace el producto, a quién sirve, qué está intencionalmente fuera del alcance o cómo debería comportarse una función orientada al usuario. Los ejemplos incluyen:
- Los mensajes generados por IA deben permanecer como borradores hasta que sean revisados por un humano
- Los usuarios de la capa gratuita pueden crear hasta tres proyectos
- Los espacios de trabajo eliminados son recuperables durante 30 días
- La facturación por equipo está fuera del alcance para la versión 1
- Los usuarios pueden exportar sus datos sin contactar al soporte
- Los resúmenes de IA con baja confianza muestran una advertencia en lugar de ocultarse
Un PDR es especialmente útil cuando una elección de producto parece arbitraria desde el código. El código podría contener un límite de tres proyectos para usuarios gratuitos, y sin un PDR, una herramienta de IA podría tratar ese número como una constante mágica y sugerir cambiarlo. Con un PDR, la IA puede ver que el límite está vinculado a la estrategia de precios, al costo de incorporación o a la carga de soporte; y que cambiarlo requiere una decisión de producto deliberada, no una edición rápida.
Registros de Decisiones de Diseño
Los Registros de Decisiones de Diseño capturan decisiones de experiencia de usuario, interacción, diseño visual y de contenido. Utilice un DDR cuando una decisión afecte cómo los usuarios interactúan con el producto, cómo se presenta la información o cómo debe aplicarse un principio de diseño en el trabajo futuro.
Los ejemplos de decisiones de diseño que valen la pena registrar incluyen:
- Usar validación en línea en lugar de validación solo al enviar
- Colocar las sugerencias de IA en un panel lateral en lugar de directamente en el editor
- Usar revelación progresiva para configuraciones avanzadas
- Exigir confirmación antes de acciones destructivas
- Usar “Borrador” y “Publicado” en lugar de “Inactivo” y “Activo”
- Mantener las acciones principales visibles en pantallas móviles
La intención de diseño es fácil de perder durante la implementación. Un desarrollador puede simplificar un flujo, o un agente de IA puede generar un componente que técnicamente funcione pero rompa el modelo de interacción previsto. Por ejemplo, un DDR podría registrar: “Mostramos las sugerencias de escritura de IA al lado del documento, no dentro de él, porque los usuarios necesitan comparar el texto generado con su propio borrador antes de aceptar los cambios”. Ese registro les da a los contribuyentes futuros un principio a preservar, no solo un diseño a copiar.
Por qué los registros de decisiones importan más con la IA
Las herramientas de codificación de IA son poderosas, pero a menudo son sin estado o solo parcialmente conscientes del historial del proyecto. Pueden inspeccionar archivos, inferir patrones y generar cambios; pero no saben automáticamente qué decisiones son intencionales, cuáles son accidentales y cuáles ya fueron debatidas y resueltas. Esto crea varios riesgos distintos.
La IA puede reabrir debates ya resueltos
Si el equipo ya decidió usar un monolito modular, un agente de IA aún podría proponer extraer un servicio porque eso parece limpio en aislamiento. Sin un ADR, la IA no tiene una manera duradera de saber que el equipo ya consideró y rechazó ese camino, y el resultado es esfuerzo desperdiciado o una regresión sutil en la coherencia del sistema.
La IA puede optimizar localmente y dañar globalmente
Una refactorización generada puede hacer que un archivo sea más limpio mientras viola los límites del sistema. Un cambio de UI puede reducir la complejidad del componente mientras debilita la experiencia de usuario prevista. Un cambio de producto puede simplificar la implementación mientras rompe los supuestos de precios o cumplimiento. Los registros de decisiones dan a la IA un marco de referencia más amplio antes de actuar sobre señales de alcance estrecho.
La IA puede preservar el código pero perder la intención
Un modelo puede seguir los patrones existentes en la base de código, pero los patrones no son lo mismo que los principios. A veces, el código existente es un compromiso. A veces es transitorio. A veces existe debido a una restricción externa que no es visible en el archivo. Los registros de decisiones explican la diferencia entre “así es como funciona” y “así es como se construyó de esta manera”.
La IA puede generar una justificación plausible pero incorrecta
La IA puede redactar registros de decisiones, pero también puede inventar explicaciones que suenan seguras pero que no coinciden con la decisión real. Por eso es innegociable la revisión humana: la IA puede generar el primer borrador de un registro, pero un humano debe verificar que describa con precisión la decisión real, las alternativas y las consecuencias antes de que el registro se fusione.
Los registros de decisiones como parte de una metodología más amplia
Los registros de decisiones no son solo documentación; son parte de una manera más amplia de trabajar que se sitúa en la intersección de la gobernanza arquitectónica ligera, los documentos como código, flujos de trabajo de gestión del conocimiento aumentados por IA, la descubrimiento de producto, la justificación de diseño, la gobernanza de IA y la revisión de código. Una manera útil de describir el proceso más amplio es el Desarrollo Orientado a Decisiones.
La mayoría de los flujos de trabajo de programación impulsada por IA se centran estrechamente en el ciclo generar-revisar-confirmar:
Ese ciclo es demasiado delgado para un trabajo de sistemas serio. Un flujo de trabajo más fuerte trata el repositorio como un almacén tanto de código como de intención; los diagramas aquí usan Mermaid, un formato ligero que funciona bien dentro de los registros de decisiones Markdown también:
Este proceso convierte al repositorio en algo más que un almacén de código. Se convierte en la fuente de verdad para la implementación, la intención y el razonamiento; un artefacto duradero que acumula valor con cada decisión tomada.
Registros de decisiones y documentos como código
Los registros de decisiones funcionan mejor cuando siguen los principios de documentos como código, lo que significa que deben almacenarse en el mismo repositorio que el código, escribirse en Markdown plano, revisarse en solicitudes de extracción (pull requests), versionarse con Git, vincularse a problemas y solicitudes de extracción relacionadas y ser buscables tanto por humanos como por herramientas de IA. Esto es mucho más fiable que almacenar decisiones importantes en chat, páginas de wiki, presentaciones de diapositivas o notas de reunión; esas herramientas pueden seguir siendo útiles para la discusión, pero la decisión aceptada siempre debe vivir cerca del código.
Una estructura de repositorio bien organizada para registros de decisiones podría verse así:
docs/
decisions/
architecture/
0001-use-postgresql-for-primary-storage.md
0002-keep-billing-inside-the-core-app.md
product/
0001-ai-generated-email-requires-human-review.md
0002-free-tier-project-limit.md
design/
0001-use-inline-validation.md
0002-place-ai-suggestions-in-side-panel.md
Para proyectos más pequeños, una estructura más plana funciona igual de bien. La organización exacta de carpetas importa menos que la consistencia; los registros deben ser fáciles de encontrar, fáciles de revisar y fáciles para que las herramientas de IA los carguen como contexto antes de actuar sobre la base de código. Para equipos de Go, esta estructura docs/decisions/ encaja naturalmente junto con el diseño cmd/, internal/ y api/ descrito en Estructura de proyectos de Go: Prácticas y Patrones, que recomienda docs/ como el hogar para decisiones de arquitectura y referencias de API.
Una plantilla práctica para registros de decisiones
Una plantilla de registro de decisiones útil debe ser lo suficientemente corta para que las personas realmente la usen. Aquí hay una plantilla práctica en Markdown que incluye una sección opcional pero valiosa de orientación para IA:
# Decisión: Título corto
Estado: Propuesto | Aceptado | Sustituido | Obsoleto
Fecha: AAAA-MM-DD
Tipo: Arquitectura | Producto | Diseño
Propietarios: Equipo o nombres
## Contexto
Describa el problema, las restricciones, los objetivos, las necesidades del usuario,
los hechos técnicos y los factores comerciales que llevaron a esta decisión.
## Decisión
Enuncie la decisión claramente.
## Alternativas consideradas
### Opción 1
Pros:
- ...
Contras:
- ...
## Consecuencias
Describa qué se vuelve más fácil, qué se vuelve más difícil y qué riesgos
o trabajo de seguimiento esto crea.
## Orientación para IA
Cuando un asistente de IA trabaje en esta área, debería:
- Preservar ...
- Evitar ...
- Preferir ...
- Pedir revisión cuando ...
## Enlaces
- Problemas relacionados:
- Solicitudes de extracción relacionadas:
- Archivos relacionados:
- Sustituye a:
- Sustituido por:
La sección “Orientación para IA” es opcional, pero para la programación impulsada por IA es extremadamente valiosa; convierte el registro de decisiones en una instrucción duradera para los agentes futuros que trabajan en la misma área de la base de código.
¿Qué pertenece en un registro de decisiones?
No cada elección merece un registro, y si cada pequeño detalle de implementación se convierte en un registro de decisiones, el proceso colapsa en ruido. Cree un registro de decisiones cuando una elección sea significativa y probablemente importe más tarde.
Los buenos candidatos son decisiones que:
- Afectan a múltiples partes del sistema
- Codifican una promesa de producto
- Resuelven un debate real
- Introducen un compromiso a largo plazo
- Dependen de restricciones comerciales, de cumplimiento o operativas
- Serían costosas de redescubrir más tarde
- Las herramientas de IA futuras podrían equivocarse plausiblemente
- Los contribuyentes futuros podrían sentirse tentados a revertir a la ligera
Los malos candidatos incluyen pequeñas elecciones de refactorización, correcciones de errores obvias, experimentos temporales, decisiones de nomenclatura local y detalles de implementación sin consecuencias duraderas. Una buena regla general es sencilla: si revertir la decisión requiere discusión, registre la decisión.
Valores de estado y ciclo de vida
Los registros de decisiones deben tener un ciclo de vida para señalar su estado actual. Los valores de estado más simples son suficientes.
Propuesto — La decisión se está considerando pero aún no ha sido aceptada. Úselo cuando el equipo quiera discutir una decisión en una solicitud de extracción antes de comprometerse con ella.
Aceptado — La decisión está activa y debe guiar el trabajo futuro. La mayoría de los registros de decisiones útiles pasarán la mayor parte de su vida en este estado.
Sustituido — La decisión ha sido reemplazada por un registro más nuevo. No elimine los registros antiguos; manténgalos para el historial y vincúlelos a la decisión más nueva para que la evolución del pensamiento permanezca visible.
Obsoleto — La decisión ya no se recomienda pero aún puede describir partes existentes del sistema. Esto es particularmente útil durante las migraciones, cuando los patrones antiguos existen en la base de código junto con enfoques más nuevos.
El principio importante es que los registros de decisiones deben ser amigables con las adiciones. Cuando el equipo cambia de dirección, cree un nuevo registro y vincule el antiguo en lugar de reescribir el historial para que el pasado parezca más limpio.
Cómo la IA debería generar registros de decisiones
La IA puede ayudar a crear registros de decisiones, y este es uno de los mejores usos de la IA en el desarrollo de software; es rápida para redactar documentos estructurados a partir del contexto. Después de una discusión, revisión de arquitectura o solicitud de extracción, puede pedir a un asistente de IA que redacte un registro:
Redacte un Registro de Decisiones Arquitectónicas para la decisión en esta solicitud de extracción.
Incluya contexto, alternativas, consecuencias y orientación para IA.
Guárdelo como Markdown bajo docs/decisions/architecture.
Para el trabajo de producto:
Redacte un Registro de Decisiones de Producto explicando por qué los mensajes
generados por IA deben permanecer como borradores hasta que sean revisados por el usuario.
Incluya el impacto en el usuario, el comportamiento fuera del alcance, los compromisos y la orientación para IA.
Sin embargo, el registro generado por IA no debe confiarse automáticamente. La revisión humana debe verificar que el contexto sea preciso, que la IA no haya inventado justificaciones, que las alternativas listadas sean reales, que las consecuencias sean honestas y que la orientación para IA coincida con la intención real del equipo. La IA es un asistente de redacción; no es la propietaria de la decisión.
Cómo la IA debería leer los registros de decisiones
La otra mitad de la práctica es instruir a la IA para que lea los registros antes de actuar. Antes de pedir a un asistente de IA que implemente un cambio, incluya una instrucción como esta:
Antes de modificar esta función, lea docs/decisions.
Identifique cualquier Registro de Decisiones Arquitectónicas, de Producto o de Diseño que se aplique.
Siga las decisiones aceptadas. Si su cambio propuesto entra en conflicto con un registro
de decisiones, explique el conflicto antes de cambiar el código.
Para tareas más grandes, refuerce el papel de los registros como memoria del proyecto:
Use los registros de decisiones como memoria del proyecto.
No revierta decisiones aceptadas sin proponer una nueva decisión sustitutoria.
Cuando genere código, explique qué registros de decisiones influyeron en la implementación.
Esto cambia el papel de la IA de “predecir código plausible” a “operar dentro de un sistema documentado de restricciones”; una mejora significativa en la fiabilidad para proyectos complejos o de larga duración.
Registros de decisiones en solicitudes de extracción
Los registros de decisiones deben ser parte de la revisión normal de solicitudes de extracción en lugar de un proceso separado. Una entrada simple en la lista de verificación de la PR hace que el hábito sea visible:
## Lista de verificación de registros de decisiones
- [ ] Esta PR no introduce una decisión arquitectónica, de producto o de diseño significativa.
- [ ] Esta PR introduce una decisión significativa e incluye un nuevo registro de decisiones.
- [ ] Esta PR cambia una decisión anterior e incluye un registro sustitutorio.
- [ ] Se consideraron los registros de decisiones existentes relevantes.
- [ ] El código generado por IA sigue los registros de decisiones aceptados.
- [ ] Los registros de decisiones generados por IA fueron revisados por un humano.
Esta lista de verificación es simple, pero cambia el comportamiento al recordar al equipo que el código no es el único artefacto que importa en una solicitud de extracción. También hace natural detectar cuando un cambio generado por IA viola silenciosamente una decisión anterior.
Registros de decisiones y gobernanza arquitectónica
La gobernanza arquitectónica tradicional a menudo falla porque es demasiado pesada, demasiado lenta o demasiado desconectada de la implementación; juntas de aprobación centralizadas, documentos extensos iniciales y procesos de control que bloquean en lugar de guiar. Los registros de decisiones ofrecen una alternativa más ligera que se integra directamente en el flujo de trabajo de desarrollo.
No requieren una junta de arquitectura central para cada cambio, ni bloquean a los equipos de aprender y adaptarse. En cambio, crean una estela de decisiones que puede ser revisada, referenciada y construida con el tiempo. Esto apoya la arquitectura evolutiva: la arquitectura puede cambiar, pero cambia con memoria y no a pesar de ella. El equipo puede revisar decisiones antiguas sin tener que redescubrir por qué se tomaron, lo que es una forma más saludable y honesta de gobernanza:
- Registros pequeños en lugar de documentos gigantes
- Revisión cerca del código en lugar de teatro de aprobación separado
- Contexto histórico en lugar de conocimiento tribal
- Compromisos explícitos en lugar de suposiciones ocultas
Registros de decisiones y gestión de producto
El trabajo de producto también necesita memoria de decisiones, y esta es un área donde el valor de los registros de decisiones a menudo se subestima. Una hoja de ruta dice qué podría suceder. Un ticket dice qué construir a continuación. Los análisis dicen qué hicieron los usuarios. Ninguno de esos explica completamente por qué existe un comportamiento de producto.
Los Registros de Decisiones de Producto llenan ese vacío y son especialmente útiles para decisiones de precios y empaquetado, modelos de permisos, límites y cuotas, flujos de seguridad y revisión de IA, elecciones de incorporación, definiciones de roles de usuario, reglas de colaboración, políticas de retención de datos y límites de alcance de funciones. Una vez implementadas, las decisiones de producto se vuelven invisibles en el código; más tarde, alguien ve solo el código y pregunta: “¿Por qué funciona así?”. Un PDR da la respuesta en una forma que tanto humanos como herramientas de IA pueden encontrar y usar.
Registros de decisiones y sistemas de diseño
Los sistemas de diseño a menudo documentan componentes, tokens y reglas de uso, pero rara vez documentan por qué el sistema funciona así. Los Registros de Decisiones de Diseño llenan este vacío. Una biblioteca de componentes podría decir “use el diálogo de confirmación para acciones destructivas”, mientras que un DDR explica la justificación: “Requerimos confirmación para acciones destructivas porque los usuarios a menudo trabajan con datos compartidos del equipo, y la eliminación accidental tiene un alto costo de recuperación”.
Esa justificación importa más allá del componente específico. Ayuda a diseñadores, desarrolladores y herramientas de IA futuros a aplicar el principio correctamente en nuevas situaciones. Sin el DDR, un agente de IA puede generar una interacción más rápida que omita la confirmación porque parece más eficiente. Con el DDR, el agente puede reconocer que preservar la propiedad de seguridad es intencional y no negociable.
Cómo los registros de decisiones apoyan el desarrollo impulsado por especificaciones
El desarrollo impulsado por especificaciones explica qué debe hacer el sistema. Los registros de decisiones explican por qué el equipo eligió esa dirección, y la distinción importa significativamente para el trabajo asistido por IA.
Una especificación de función puede decir que los correos electrónicos generados por IA deben guardarse como borradores. Un Registro de Decisiones de Producto explica por qué se rechazó el envío automático, qué riesgos se consideraron y qué cambios futuros requerirían una nueva decisión. Una especificación de diseño puede describir una interacción de panel lateral, mientras que el DDR correspondiente explica por qué se rechazaron explícitamente las ediciones de IA en línea y por qué preservar el control del usuario tuvo más peso que la velocidad del flujo de trabajo. Una especificación arquitectónica puede definir un límite de servicio, y su ADR explica por qué el equipo eligió ese límite sobre una alternativa más simple o más distribuida.
La especificación guía la implementación. El registro de decisiones preserva el juicio. Juntos, les dan a los agentes de codificación de IA tanto instrucciones como contexto; el “qué” y el “por qué”; lo que hace que la combinación sea tan efectiva para sistemas complejos y de larga duración.
Los registros de decisiones no son especificaciones
Los registros de decisiones están relacionados con las especificaciones, pero sirven un propósito diferente. Una especificación dice “el sistema hará X”, mientras que un registro de decisiones dice “elegimos X en lugar de Y debido a estas restricciones y compromisos”. Ese “en lugar de Y” es la parte valiosa. Las herramientas de IA a menudo generan soluciones encontrando un camino plausible hacia el resultado solicitado, pero los registros de decisiones les dicen cuáles caminos plausibles ya se han explorado, evaluado y rechazado; reduciendo el churn y mejorando la calidad del trabajo asistido por IA.
Los registros de decisiones no son un reemplazo para las pruebas
Las pruebas verifican el comportamiento; los registros de decisiones explican la intención. Ambos son necesarios y trabajan juntos. Una prueba puede hacer cumplir que los correos electrónicos generados por IA deben guardarse como borradores, mientras que un Registro de Decisiones de Producto explica que esto es necesario porque los usuarios deben revisar la comunicación generada por IA antes de que salga del sistema. La prueba protege el comportamiento. El registro de decisiones protege el significado. Juntos, hacen que los cambios futuros sean más seguros y predecibles.
Los registros de decisiones no son un reemplazo para los comentarios del código
Los comentarios del código explican detalles de implementación locales, mientras que los registros de decisiones explican decisiones más amplias. Use comentarios para líneas sorprendentes, casos extremos, soluciones alternativas y funciones que no se pueden simplificar. Use registros de decisiones para explicar por qué existe una arquitectura, por qué existe un comportamiento de producto, por qué existe un patrón de interacción y por qué el equipo eligió una dirección sobre otra. Si la explicación afecta solo unas pocas líneas, un comentario es la herramienta correcta. Si afecta la dirección del sistema, un registro de decisiones es la herramienta correcta.
Errores comunes
Escribir registros demasiado tarde
Un registro de decisiones debe escribirse cuando se toma la decisión, no meses después cuando todos han olvidado los compromisos. Está bien redactar uno durante una solicitud de extracción. Es aún mejor redactarlo antes de la implementación, mientras la decisión aún se está discutiendo activamente y las alternativas están frescas.
Hacer registros demasiado largos
Un registro de decisiones no es un ensayo. Debe ser lo suficientemente detallado para preservar el juicio pero lo suficientemente corto para que las personas realmente lo lean. Prefiera la claridad sobre la exhaustividad; un registro conciso que se lee es mucho más valioso que uno exhaustivo que se omite.
Registrar decisiones sin consecuencias
La sección de consecuencias es el corazón del registro. Una decisión sin consecuencias declaradas a menudo es solo una preferencia en lugar de una decisión real. Los buenos registros admiten los compromisos honestamente, incluyendo qué se vuelve más difícil o riesgoso como resultado de la elección.
Editar registros antiguos como si el historial hubiera cambiado
Cuando una decisión cambia, cree un nuevo registro y marque el antiguo como sustituido. Reescribir silenciosamente una decisión antigua para que coincida con el estado actual destruye el contexto histórico que hace valiosos a los registros de decisiones. El historial es útil precisamente porque muestra cómo evolucionó el pensamiento.
Permitir que los registros generados por IA se fusionen sin revisión
La IA puede producir un registro pulido y bien estructurado que está sutilmente equivocado. Trate los registros de decisiones generados por IA exactamente como el código generado por IA; revíselos cuidadosamente, verifique que la justificación sea precisa y asegúrese de que la sección de consecuencias refleje lo que el equipo realmente aceptó.
Ocultar registros fuera del repositorio
Si los registros de decisiones viven en una wiki separada o sistema de documentación, es menos probable que se actualicen junto con los cambios de código y mucho menos probable que sean leídos por las herramientas de codificación de IA que cargan contexto para una tarea. Mantenerlos en el repositorio no es solo una conveniencia; es lo que hace que la práctica funcione para el desarrollo asistido por IA.
Un modelo operativo ligero
Un proceso práctico de equipo que añade una sobrecarga mínima se ve así:
- Durante la planificación o implementación, identifique si se está tomando una decisión significativa.
- Pida a un asistente de IA que redacte un ADR, PDR o DDR basado en la discusión.
- Revise el borrador como equipo, verificando el contexto, las alternativas y las consecuencias.
- Confirme el registro como Markdown en el repositorio.
- Vincúlelo desde el problema o la solicitud de extracción relacionada.
- Instruya a las herramientas de codificación de IA para que lean los registros relevantes antes de hacer cambios futuros en el área.
- Sustituya los registros cuando las decisiones cambien, preservando el registro antiguo para el historial.
Esto no requiere una nueva burocracia ni un rol de documentación dedicado. Requiere un pequeño hábito: preservar el juicio importante en el momento en que se crea, cerca del código donde se necesitará.
Ejemplo de ADR
# Decisión: Usar PostgreSQL para el almacenamiento principal de la aplicación
Estado: Aceptado
Fecha: 2026-06-25
Tipo: Arquitectura
Propietarios: Equipo de plataforma
## Contexto
La aplicación necesita almacenamiento relacional durable para cuentas, proyectos,
permisos y eventos de auditoría. El equipo espera consultas de informes frecuentes
y requisitos de consistencia fuerte para las comprobaciones de permisos.
## Decisión
Usaremos PostgreSQL como base de datos principal de la aplicación.
## Alternativas consideradas
### DynamoDB
Pros:
- Escalabilidad operativa
- Buen ajuste para patrones de acceso clave-valor predecibles
Contras:
- Más complejo para consultas relacionales
- Más difícil para informes ad hoc
- Menos familiar para el equipo actual
### MySQL
Pros:
- Base de datos relacional madura
- Modelo operativo familiar
Contras:
- PostgreSQL coincide mejor con las necesidades del equipo para soporte JSON,
opciones de indexación y experiencia existente
## Consecuencias
PostgreSQL se convierte en una dependencia operativa central. El equipo debe gestionar
las migraciones cuidadosamente y monitorear el rendimiento de las consultas. A cambio, la
aplicación obtiene modelado relacional fuerte, indexación madura y
soporte de informes flexible.
## Orientación para IA
Al modificar el código de persistencia, prefiera el modelado relacional en PostgreSQL.
No introduzca una segunda base de datos principal sin un ADR sustitutorio.
Ejemplo de PDR
# Decisión: Los correos electrónicos generados por IA deben permanecer como borradores
Estado: Aceptado
Fecha: 2026-06-25
Tipo: Producto
Propietarios: Equipo de producto
## Contexto
El producto puede generar respuestas de correo electrónico usando IA. Enviar correo electrónico es una
acción de alta confianza porque los errores pueden llegar a clientes, socios o
equipos internos.
## Decisión
Los correos electrónicos generados por IA deben crearse como borradores. Un usuario humano debe
revisarlos y enviarlos.
## Alternativas consideradas
### Enviar automáticamente
Pros:
- Flujo de trabajo más rápido
- Menos esfuerzo del usuario
Contras:
- Mayor riesgo de mensajes incorrectos o inapropiados
- Menor confianza del usuario
- Más difícil recuperarse de los errores
### Pedir confirmación solo después de la generación
Pros:
- Mantiene el flujo de trabajo simple
- Proporciona algo de control al usuario
Contras:
- Sigue fomentando una revisión superficial
- No se ajusta tan bien al comportamiento existente del cliente de correo electrónico como los borradores
## Consecuencias
El flujo de trabajo es ligeramente más lento, pero más seguro y fiable.
La automatización futura puede mejorar la velocidad de revisión, pero no debe omitir
la aprobación humana sin un PDR sustitutorio.
## Orientación para IA
Al construir funciones de generación de correo electrónico, cree borradores por defecto.
No agregue envío automático a menos que un nuevo PDR aceptado lo permita explícitamente.
Ejemplo de DDR
# Decisión: Mostrar sugerencias de escritura de IA en un panel lateral
Estado: Aceptado
Fecha: 2026-06-25
Tipo: Diseño
Propietarios: Equipo de diseño
## Contexto
Los usuarios necesitan ayuda para mejorar el contenido escrito, pero también necesitan permanecer
en control del texto final. Las ediciones de IA en línea pueden dificultar
distinguir el contenido escrito por el usuario de las sugerencias generadas.
## Decisión
Las sugerencias de escritura de IA aparecerán en un panel lateral. Los usuarios pueden aceptar,
rechazar o copiar sugerencias en el editor principal.
## Alternativas consideradas
### Aplicar sugerencias en línea
Pros:
- Rápido
- Se siente integrado
Contras:
- Enfría la autoría
- Hace la revisión más difícil
- Puede sorprender a los usuarios
### Mostrar sugerencias en un modal
Pros:
- Experiencia enfocada
- Fácil de implementar
Contras:
- Interrumpe el flujo de escritura
- Más difícil comparar la sugerencia y el texto original
## Consecuencias
El panel lateral ocupa más espacio en la pantalla, especialmente en pantallas pequeñas.
Sin embargo, preserva el control del usuario y hace la revisión más clara.
## Orientación para IA
Al agregar funciones de asistencia de escritura, preserve la separación entre
el texto del usuario y las sugerencias de IA. No aplique texto generado directamente
en el documento sin una acción explícita del usuario.
Biblioteca de prompts sugerida
Use estos prompts para hacer que los registros de decisiones sean parte del desarrollo diario asistido por IA.
Encontrar registros relevantes antes de trabajar en una función:
Lea docs/decisions e identifique cualquier registro de decisiones aceptado que se aplique
a esta tarea. Resuma las restricciones antes de proponer cambios de código.
Redactar un nuevo ADR:
Redacte un Registro de Decisiones Arquitectónicas para esta decisión técnica.
Incluya contexto, decisión, alternativas, consecuencias y orientación para IA.
Manténgalo conciso y específico.
Redactar un nuevo PDR:
Redacte un Registro de Decisiones de Producto para este comportamiento de producto.
Incluya el impacto en el usuario, el alcance, las alternativas, las consecuencias y la orientación para IA.
Redactar un nuevo DDR:
Redacte un Registro de Decisiones de Diseño para este patrón de interacción.
Incluya el problema del usuario, las alternativas, los compromisos, las consecuencias y la orientación para IA.
Revisar una solicitud de extracción contra las decisiones existentes:
Revise esta solicitud de extracción contra los registros de decisiones aceptados en docs/decisions.
Identifique cualquier conflicto, registros de decisiones faltantes o decisiones que deberían
ser sustituidas.
Sustituir una decisión:
Cree un nuevo registro de decisiones que sustituya al existente.
Preserve la justificación histórica, explique qué cambió y vincule ambos registros.
Lectura relacionada
- El formato original de ADR de Michael Nygard — la publicación fundacional que inició el movimiento ADR
- Organización de GitHub de ADR — herramientas, plantillas y recursos comunitarios para gestionar registros de decisiones
- ¿Qué es el Desarrollo Impulsado por Especificaciones? La especificación como fuente de verdad — la definición canónica de SDD que explica cómo las especificaciones de función complementan los registros de decisiones: ambos hacen que la intención sea duradera, a diferentes niveles del sistema
- Desarrollo Impulsado por Especificaciones vs Vibe Coding: ¿Cascada? — cuándo usar SDD y cuándo mantenerse con flujos de trabajo más rápidos y flexibles
- Arquitectura de aplicaciones en producción: Patrones de integración, diseño de código y acceso a datos — el hogar del clúster que cubre integración, pruebas, acceso a datos y patrones de documentación de software
- IA para la gestión del conocimiento: flujos de trabajo reales que resisten — flujos de trabajo de conocimiento aumentados por IA prácticos que complementan la práctica de los registros de decisiones
