Registros de Decisiones para el Desarrollo de Software Impulsado por IA

Mantén la intención cerca del código.

Índice

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 esa distinción se vuelve crítica cuando las herramientas de IA están escribiendo su código.

Decision records — ADR, PDR, DDR — connecting intent to code

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é el equipo eligió PostgreSQL en lugar de DynamoDB? ¿Por qué el producto requiere 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 elección importante, el contexto detrás de ella, 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 codificación 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 futuras herramientas de IA 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, estructurado 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, 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 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 del usuario. Esa 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 dan 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 vale 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
  • Utilizar la renderización del lado del servidor para la aplicación web
  • Requerir 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 pueden redescubrir los mismos compromisos, reabrir debates antiguos o anular accidentalmente restricciones importantes.

En la programación impulsada por IA, los ADR tienen aún más peso. Las herramientas de IA a menudo son hábiles en la optimización local, y pueden proponer un cambio técnicamente plausible que viola 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 estar formado 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 se dispersan frecuentemente en tickets, herramientas de ruta crítica, hilos de chat, notas de reuniones y memorias de las personas, lo que las hace fáciles de olvidar para los humanos y casi imposibles de inferir de manera confiable 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 de equipos 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 se debe aplicar un principio de diseño en el trabajo futuro.

Los ejemplos de decisiones de diseño que vale la pena registrar incluyen:

  • Utilizar 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
  • Utilizar la revelación progresiva para configuraciones avanzadas
  • Requerir confirmación antes de acciones destructivas
  • Utilizar “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 funciona técnicamente pero rompe el modelo de interacción previsto. Por ejemplo, un DDR podría registrar: “Mostramos sugerencias de escritura de IA junto al documento, no dentro de él, porque los usuarios necesitan comparar el texto generado con su propio borrador antes de aceptar cambios”. Ese registro da a los contribuyentes futuros un principio que preservar, no solo un diseño para 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 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

Un refactor generado 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 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 que no coinciden con la decisión real. Esta es la razón por la que la revisión humana es innegociable: 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 encuentra en la intersección de la gobernanza arquitectónica ligera, documentación como código, flujos de trabajo de gestión del conocimiento aumentados por IA, descubrimiento de producto, razonamiento de diseño, gobernanza de IA y 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 impulsados por IA se centran estrechamente en el ciclo generar-revisar-confirmar:

flowchart LR A[Prompt] --> B[Generate code] B --> C[Test] C --> D[Commit]

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í utilizan Mermaid, un formato ligero que funciona bien dentro de los registros de decisiones en Markdown también:

flowchart TB subgraph top[" "] direction LR A[Frame the problem] --> B[Identify existing decisions] --> C[Explore options and tradeoffs] --> D[Record the selected decision] end subgraph bottom[" "] direction LR E[Generate or modify code] --> F[Review code vs decisions] --> G[Merge implementation and memory] --> H[Use record to guide future work] end D --> E

Este proceso convierte el 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 documentación como código

Los registros de decisiones funcionan mejor cuando siguen los principios de documentación 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 relacionados, y ser buscables tanto por humanos como por herramientas de IA. Esto es mucho más confiable que almacenar decisiones importantes en chats, páginas de wiki, presentaciones o notas de reuniones; esas herramientas aún pueden ser útiles para la discusión, pero la decisión aceptada siempre debe vivir cerca del código. Mantener las especificaciones, pruebas y código sincronizados en el desarrollo de IA extiende este mismo hábito de “vincularlo de vuelta al registro” a un modelo de trazabilidad completo que vincula las identificaciones de decisiones de requisitos y diseño con pruebas y solicitudes de extracción.

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 los equipos de Go, esta estructura docs/decisions/ encaja naturalmente junto al diseño cmd/, internal/ y api/ descrito en Estructura de Proyectos 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 la gente realmente la use. Aquí hay una plantilla de Markdown práctica que incluye una sección de orientación para IA opcional pero valiosa:

# Decision: Short title

Status: Proposed | Accepted | Superseded | Deprecated
Date: YYYY-MM-DD
Type: Architecture | Product | Design
Owners: Team or names

## Context

Describe the problem, constraints, goals, user needs, technical facts,
and business factors that led to this decision.

## Decision

State the decision clearly.

## Alternatives considered

### Option 1

Pros:
- ...

Cons:
- ...

## Consequences

Describe what becomes easier, what becomes harder, and what risks
or follow-up work this creates.

## AI guidance

When an AI assistant works in this area, it should:
- Preserve ...
- Avoid ...
- Prefer ...
- Ask for review when ...

## Links

- Related issues:
- Related pull requests:
- Related files:
- Supersedes:
- Superseded by:

La sección de “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 futuros agentes 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 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 cometer errores plausiblemente
  • Los contribuyentes futuros podrían sentirse tentados a revertir casualmente

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 directa: si revertir la decisión requeriría 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 se ha aceptado. Utilice esto 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 orientar 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 vincule 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 a 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 se vea más limpio.

Cómo la IA debe 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 al 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:

Draft an Architecture Decision Record for the decision in this pull request.
Include context, alternatives, consequences, and AI guidance.
Save it as Markdown under docs/decisions/architecture.

Para el trabajo de producto:

Draft a Product Decision Record explaining why AI-generated messages
must remain drafts until reviewed by the user.
Include user impact, out-of-scope behavior, tradeoffs, and AI guidance.

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 una justificación, 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 dueña de la decisión.

Cómo la IA debe 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:

Before modifying this feature, read docs/decisions.
Identify any Architecture, Product, or Design Decision Records that apply.
Follow accepted decisions. If your proposed change conflicts with a decision
record, explain the conflict before changing code.

Para tareas más grandes, refuerce el papel de los registros como memoria del proyecto:

Use the decision records as project memory.
Do not reverse accepted decisions without proposing a new superseding decision.
When you generate code, explain which decision records influenced the implementation.

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 confiabilidad 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:

## Decision record checklist

- [ ] This PR does not introduce a significant architecture, product, or design decision.
- [ ] This PR introduces a significant decision and includes a new decision record.
- [ ] This PR changes a previous decision and includes a superseding record.
- [ ] Relevant existing decision records were considered.
- [ ] AI-generated code follows the accepted decision records.
- [ ] AI-generated decision records were reviewed by a human.

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 central, documentos grandes previos 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 un rastro de decisiones que pueden ser revisadas, referenciadas y construidas 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 revisitar decisiones antiguas sin tener que redescubrir por qué se tomaron, lo cual 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 productos

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 ruta crítica dice qué podría pasar. Un ticket dice qué construir a continuación. Las analíticas 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 revisión y seguridad 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 de esta manera?”. 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 de esa manera. 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 salte la confirmación porque parece más eficiente. Con el DDR, el agente puede reconocer que preservar la propiedad de seguridad es intencional y innegociable.

Cómo los registros de decisiones apoyan el desarrollo guiado por especificaciones

El desarrollo guiado 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 se ponderó más que la velocidad del flujo de trabajo. Una especificación de arquitectura 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, 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. Cuando adopte una cadena de herramientas guiada por especificaciones, compare cómo cada opción muestra ese contexto; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows desglosa la portabilidad, las puertas de revisión y el anclaje del repositorio en las principales configuraciones. Para el proceso neutral de herramientas de cinco fases que implementan esas herramientas, consulte Flujo de Trabajo de Desarrollo Guiado por Especificaciones Desde Requisitos hasta Código.

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 qué caminos plausibles ya han sido explorados, evaluados y rechazados, reduciendo la agitación 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 en el código

Los comentarios en el 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 pueden simplificarse. 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 son 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 la gente realmente lo lea. Prefiera la claridad sobre la exhaustividad: un registro conciso que se lee es mucho más valioso que uno completo que se salta.

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 arriesgado 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. Las bases de conocimiento compiladas enfrentan el problema idéntico bajo un nombre diferente; Mantenimiento de Wiki LLM: Deriva, Contradicciones y Revisión lo llama deriva de decisiones y aplica la misma regla de sustituir en lugar de sobrescribir a las páginas de wiki.

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 un wiki o sistema de documentación separado, es menos probable que se actualicen junto con los cambios de código y mucho menos probable que sean leídos por 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 de equipo práctico que agrega una sobrecarga mínima se ve así:

  1. Durante la planificación o implementación, identifique si se está tomando una decisión significativa.
  2. Pregunte a un asistente de IA que redacte un ADR, PDR o DDR basado en la discusión.
  3. Revise el borrador como equipo, verificando el contexto, las alternativas y las consecuencias.
  4. Confirme el registro como Markdown en el repositorio.
  5. Vincúlelo desde el problema o la solicitud de extracción relacionada.
  6. Instruya a las herramientas de codificación de IA para que lean los registros relevantes antes de realizar cambios futuros en el área.
  7. 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

# Decision: Use PostgreSQL for primary application storage

Status: Accepted
Date: 2026-06-25
Type: Architecture
Owners: Platform team

## Context

The application needs durable relational storage for accounts, projects,
permissions, and audit events. The team expects frequent reporting queries
and strong consistency requirements for permission checks.

## Decision

We will use PostgreSQL as the primary application database.

## Alternatives considered

### DynamoDB

Pros:
- Operationally scalable
- Good fit for predictable key-value access patterns

Cons:
- More complex for relational queries
- Harder for ad hoc reporting
- Less familiar to the current team

### MySQL

Pros:
- Mature relational database
- Familiar operational model

Cons:
- PostgreSQL better matches the team's needs for JSON support,
  indexing options, and existing expertise

## Consequences

PostgreSQL becomes a core operational dependency. The team must manage
migrations carefully and monitor query performance. In return, the
application gets strong relational modeling, mature indexing, and
flexible reporting support.

## AI guidance

When modifying persistence code, prefer relational modeling in PostgreSQL.
Do not introduce a second primary database without a superseding ADR.

Ejemplo de PDR

# Decision: AI-generated emails must remain drafts

Status: Accepted
Date: 2026-06-25
Type: Product
Owners: Product team

## Context

The product can generate email replies using AI. Sending email is a
high-trust action because mistakes may reach customers, partners, or
internal teams.

## Decision

AI-generated emails must be created as drafts. A human user must
review and send them.

## Alternatives considered

### Send automatically

Pros:
- Faster workflow
- Less user effort

Cons:
- Higher risk of incorrect or inappropriate messages
- Lower user trust
- Harder to recover from mistakes

### Ask for confirmation only after generation

Pros:
- Keeps the workflow simple
- Provides some user control

Cons:
- Still encourages shallow review
- Does not fit existing email client behavior as well as drafts

## Consequences

The workflow is slightly slower, but safer and more trustworthy.
Future automation can improve review speed, but must not bypass
human approval without a superseding PDR.

## AI guidance

When building email-generation features, create drafts by default.
Do not add automatic sending unless a new accepted PDR explicitly allows it.

Ejemplo de DDR

# Decision: Show AI writing suggestions in a side panel

Status: Accepted
Date: 2026-06-25
Type: Design
Owners: Design team

## Context

Users need help improving written content, but they also need to stay
in control of the final text. Inline AI edits can make it hard to
distinguish user-written content from generated suggestions.

## Decision

AI writing suggestions will appear in a side panel. Users can accept,
reject, or copy suggestions into the main editor.

## Alternatives considered

### Apply suggestions inline

Pros:
- Fast
- Feels integrated

Cons:
- Blurs authorship
- Makes review harder
- Can surprise users

### Show suggestions in a modal

Pros:
- Focused experience
- Easy to implement

Cons:
- Interrupts writing flow
- Harder to compare suggestion and original text

## Consequences

The side panel takes more screen space, especially on small screens.
However, it preserves user control and makes review clearer.

## AI guidance

When adding writing-assistance features, preserve separation between
user text and AI suggestions. Do not apply generated text directly
into the document without explicit user action.

Biblioteca de prompts sugerida

Utilice 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:

Read docs/decisions and identify any accepted decision records that apply
to this task. Summarize the constraints before proposing code changes.

Redactar un nuevo ADR:

Draft an Architecture Decision Record for this technical decision.
Include context, decision, alternatives, consequences, and AI guidance.
Keep it concise and specific.

Redactar un nuevo PDR:

Draft a Product Decision Record for this product behavior.
Include user impact, scope, alternatives, consequences, and AI guidance.

Redactar un nuevo DDR:

Draft a Design Decision Record for this interaction pattern.
Include user problem, alternatives, tradeoffs, consequences, and AI guidance.

Revisar una solicitud de extracción contra las decisiones existentes:

Review this pull request against the accepted decision records in docs/decisions.
Identify any conflicts, missing decision records, or decisions that should
be superseded.

Sustituir una decisión:

Create a new decision record that supersedes the existing one.
Preserve the historical rationale, explain what changed, and link both records.

Lectura relacionada

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.