Cuando un agente de IA escribe parte del código, el diff registra el resultado, pero no conserva por sí solo el motivo de la elección. Un registro de decisiones de ingeniería debe guardar el problema, las alternativas, la evidencia comprobada, la persona que aceptó la decisión y lo que haría que el equipo la reabriera.

Eso no significa guardar toda la conversación con el agente. Significa convertir una decisión duradera en un documento breve, versionado y fácil de buscar. Un AGENTS.md ligero para agentes de código sigue siendo el lugar para las instrucciones estables. El registro de decisiones conserva la historia del porqué.

Flujo que muestra una pregunta pasando por propuesta de agente, verificación humana, registro de decisión y condición para reabrir la elección.

Respuesta breve

  • Registra decisiones que cambian la estructura, la calidad, la operación o una frontera difícil de revertir.
  • Separa la propuesta del agente, la evidencia verificada y la decisión humana aceptada.
  • Incluye alternativas rechazadas, trade-offs, confianza y la condición para reabrir el registro.
  • Guarda el archivo en el repositorio y sustituye una decisión aceptada con otro registro enlazado.
  • Usa CI para comprobar presencia y forma, no para declarar correcto el criterio técnico.

Por qué un diff no sustituye a un registro de decisiones

Un diff explica qué líneas cambiaron. No explica por qué el equipo eligió una cola en vez de una llamada síncrona, aceptó una consistencia más débil o rechazó una sugerencia del agente. Después de varias sesiones, el código conserva la elección, pero el razonamiento puede haber desaparecido del contexto disponible.

Microsoft define un architecture decision record como el registro de cómo y por qué un sistema llegó a su forma actual. Su guía recomienda incluir contexto, alternativas, justificación, consecuencias, confianza y estado, y registrar un cambio mediante un nuevo documento que sustituya al anterior (Microsoft, guía de ADR). La participación de un agente añade campos que evitan que una sugerencia parezca conocimiento comprobado.

Una discusión reciente de practicantes describe el problema directamente: las decisiones desaparecen entre sesiones largas, compactaciones y agentes distintos. En una discusión de r/ClaudeCode, participantes mencionan un DECISIONS.md corto, el motivo del rechazo y una instrucción para leer el archivo. Es una señal sobre lenguaje y modo de fallo, no una prueba de que un formato mejore las métricas de ingeniería.

Qué decisiones merecen un registro

No conviertas cada elección de sintaxis en una ADR. Registra lo que cambia el comportamiento del sistema o el trabajo de quien lo mantenga después. Un filtro útil es preguntarte si otra persona podría elegir lo contrario sin conocer un riesgo que el equipo ya discutió.

Regístrala cuando la elección... Ejemplo con un agente Evidencia que cabe en el registro
cambia la estructura del sistema mueve el procesamiento a un worker y una cola diagrama, prueba de contrato o restricción operativa
cambia un atributo de calidad acepta consistencia eventual para reducir acoplamiento requisito, medición disponible o límite declarado
es difícil de revertir elige un formato de eventos o una base de datos alternativas, coste de migración y dependencias
fija un límite del agente permite lecturas, pero exige aprobación antes de escribir política, prueba de permisos y responsable
rechaza una hipótesis importante evita una tool o un modelo para una tarea motivo del rechazo y condición que lo cambiaría

El Engineering Playbook de Microsoft recomienda un decision log porque las decisiones y sus consecuencias se pierden dentro de documentos grandes. El registro puede ser breve. Lo importante es que el contexto y la consecuencia no dependan de la memoria de una sesión.

No confundas esta historia con el registro de una ejecución. La guía de observabilidad de agentes de código en CI explica qué ocurrió durante una ejecución. El registro de decisiones explica por qué el sistema debe seguir ese camino.

Qué campos añadir cuando participa un agente de IA

Una ADR tradicional necesita un problema, opciones, decisión, trade-offs y estado. Un flujo con agentes debe añadir la procedencia de la propuesta y el estado de la evidencia. Registra qué sugirió el agente, qué comprobó una persona y quién aceptó el riesgo.

Usa docs/decisions/ o el directorio equivalente:

---
status: accepted
date: 2026-11-15
owner: nombre-o-equipo
confidence: medium
validUntil: 2027-11-15
supersedes: null
---

# Usar una clave idempotente en la entrada de pedidos

## Context
El worker puede recibir el mismo mensaje después de un timeout.

## Options considered
- Aceptar la última escritura y reconciliar después.
- Rechazar duplicados con una clave idempotente.

## Decision
Comprobaremos la clave idempotente antes de la mutación.

## Evidence
- Test: `npm test -- idempotency`
- Todavía no existe una medición de carga distribuida.

## AI participation
El agente propuso las dos opciones y generó una primera prueba.
Una persona revisó el caso de retry, ejecutó la suite y aceptó el trade-off.

## Consequences
Ganamos una barrera contra duplicados, pero debemos expirar las claves.

## Reopen when
Cambia el contrato de entrega o la expiración causa colisiones.

Los campos importantes son contexto, alternativas rechazadas, decisión y consecuencias, evidencia, AI participation, owner, confidence, validez y condición para reabrir. La guía de ADR de Microsoft recomienda registrar la confianza incluso cuando es baja. Un position paper sobre estado epistémico y validez temporal defiende una idea relacionada, pero no es un estándar adoptado ni una validación de este template.

Cómo separar una propuesta del agente de una decisión humana

Usa tres estados diferentes:

  1. Propuesta: el agente resumió opciones, sugirió una implementación o produjo una fixture.
  2. Verificación: una persona comprobó el contrato, ejecutó las pruebas relevantes y verificó que la evidencia responde a la pregunta.
  3. Decisión: una persona responsable aceptó el resultado, el trade-off y los límites.

Un agente puede completar un borrador. No debería asignar su propia confianza ni convertir una prueba verde en aprobación arquitectónica. Si no se ejecutó la verificación, dilo. Si solo se cubrió un escenario, nombra la brecha.

Esto también ayuda en un portafolio. El README de portafolio que demuestra criterio de ingeniería presenta una elección al lector. El registro del repositorio conserva el proceso para el equipo y las próximas sesiones. Son documentos relacionados con lectores y trabajos distintos.

Un portafolio de software engineer con IA puede enlazar estos registros como evidencia de criterio, pero una página pública no sustituye la documentación operativa del proyecto.

Cómo guardar y actualizar los registros

Empieza con un directorio versionado y un archivo por decisión:

docs/decisions/
  0001-use-idempotency-key.md
  0002-run-agent-read-only-by-default.md

Enlaza el registro desde el README, la documentación del área o el comentario de código que depende de la elección. No pegues el documento entero en AGENTS.md: las instrucciones operativas y la historia de decisiones envejecen de formas distintas.

Después de aceptar un registro, trátalo como append-only. Si cambia el contexto, crea otro archivo con status: superseded, enlaza ambos y explica qué cambió. Editar en silencio la decisión anterior borra la historia que querías conservar. No crees un registro por cada prompt. Úsalo para una elección que cambie la dirección, el riesgo o un contrato que otro agente deba respetar.

Cómo validar la forma en CI

CI puede comprobar que el registro es legible y completo. No puede demostrar que la elección sea buena. El script siguiente es ilustrativo, pero se puede ejecutar con Node.js y sin dependencias:

import { readFileSync } from "node:fs";

const file = process.argv[2];
if (!file) {
  console.error("Usage: node scripts/check-decision-record.mjs <file>");
  process.exit(2);
}

const text = readFileSync(file, "utf8");
const required = [
  "Context",
  "Options considered",
  "Decision",
  "Evidence",
  "AI participation",
  "Consequences",
  "Reopen when",
];
const missing = required.filter(
  (heading) => !new RegExp(`^## ${heading}$`, "im").test(text),
);

if (missing.length > 0) {
  console.error(`Missing sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`Decision record is structurally complete: ${file}`);

Guárdalo como scripts/check-decision-record.mjs y ejecuta node scripts/check-decision-record.mjs docs/decisions/0001-use-idempotency-key.md. Requisitos: Node.js con soporte de módulos ES y un archivo Markdown que use los títulos del ejemplo. Ejecútalo con el ejemplo completo y después elimina una sección para confirmar que CI falla. Si el repositorio usa frontmatter YAML estricto, añade un parser y comprobaciones para status, owner y confidence; este ejemplo no valida YAML, hechos, calidad de evidencia, enlaces ni autorización humana.

La prueba importante sigue fuera del script: ¿puede alguien que no participó en la conversación entender el problema, encontrar la alternativa rechazada, repetir la verificación y saber cuándo caduca la decisión? Un check verde no cierra esa brecha.

Fallos comunes y límites

Registrar solo el resultado. “Usamos una cola” no explica la restricción, el coste ni la opción rechazada.

Dejar que el agente escriba solo la decisión final. La automatización puede preparar el borrador y señalar evidencia. La aceptación necesita una persona o equipo responsable.

Convertir la confianza en una nota decorativa. high sin una prueba o argumento verificable no es evidencia.

Poner todo en un archivo de memoria. Separa instrucciones estables, decisiones aceptadas y notas de trabajo.

Editar el pasado para que la historia quede limpia. Si la elección cambia, marca la anterior como sustituida y escribe la nueva.

Suponer que el registro sustituye las pruebas. La documentación hace auditable el razonamiento. No valida seguridad ni mide carga por sí sola.

Cierre

Un registro de decisiones para código asistido por IA no es un diario del agente. Es un artefacto de responsabilidad técnica: hace visibles el problema, las alternativas, la evidencia, la participación de la herramienta, la decisión humana y la condición para reabrirla.

Empieza con docs/decisions/, un template breve y una regla de sustitución. Enlaza cada decisión con el código o el pull request que depende de ella. Si el volumen lo justifica, valida la estructura en CI. La parte que no debe automatizarse es juzgar si la evidencia realmente sostiene la elección.

Cómo se produjo este artículo

Samuel Fajreldines es el responsable de este artículo. La investigación comparó la guía actual de ADR de Microsoft, un decision log de ingeniería versionado, un position paper sobre validez de decisiones y discusiones públicas recientes sobre pérdida de contexto en coding agents. Las discusiones se usaron para lenguaje y fallos percibidos, no como prueba técnica. El diagrama es una SVG original y el validator se comprobó localmente con Node.js usando un registro ficticio, sin medir un equipo real, llamar a un modelo ni ejecutar un benchmark de producción. La asistencia de IA apoyó el descubrimiento, la organización, la redacción, la localización y la revisión de consistencia. El autor usa RemoteCode como herramienta de trabajo, pero no ejecutó pruebas de producción ni aportó experiencia operativa.

Fuentes consultadas