En 2011, Michael Nygard escribió que «una de las cosas más difíciles de seguir durante la vida de un proyecto es la motivación detrás de ciertas decisiones». Casi quince años después, la frase describe un problema nuevo: el agente de programación que entra en tu repositorio llega sin esa motivación y no tiene a quién preguntársela.
Esta pieza defiende una tesis sencilla: cuando un agente entra en un repositorio, lo primero que hay que escribir no es un prompt mejor. Son las decisiones que no se pueden revertir sin coste, con su contexto y las alternativas descartadas, en el repositorio y donde el agente las lea.
Lo que el código no dice
El código dice qué hace el sistema. No dice por qué tiene esa forma: por qué hay una cola donde parecería bastar una llamada directa, por qué ese servicio es el único que escribe en la base de datos o por qué se descartó la opción que hoy parece obvia. Ese porqué suele vivir en la cabeza de dos o tres personas.
Un desarrollador nuevo lo recupera preguntando. Benjamin Cane, que escribe sobre arquitectura y agentes de programación, lo plantea sin rodeos en mayo de 2026: a diferencia de los ingenieros, los agentes no reciben contexto de las conversaciones de pasillo, de acompañar a otros ni del conocimiento tribal. Solo saben lo que se captura.
El dilema de Nygard, a velocidad de agente
Nygard describía lo que le pasa a quien hereda un proyecto sin conocer sus decisiones: o las acepta a ciegas, o las cambia a ciegas. Su conclusión es que conviene evitar las dos cosas. Un agente está exactamente en esa posición, con una diferencia: actúa rápido. Si acepta a ciegas, repite un patrón cuya razón ya no existe. Si cambia a ciegas, deshace una decisión que alguien tomó por un motivo.
La guía de arquitectura de Microsoft Azure lo dice de otro modo: una decisión que se toma pero nunca se registra probablemente se olvidará, lo que lleva a debates repetidos o a cambios posteriores que contradicen sin saberlo la intención original.
Un prompt mejor no sustituye al porqué. Si la razón de una decisión solo está en la cabeza del equipo, el agente tendrá que adivinarla.
Qué merece un registro, y cómo es
No todo merece un registro. Microsoft recomienda incluir solo las decisiones que afectan a la estructura del sistema, a sus atributos de calidad clave o que son difíciles de revertir, con las alternativas que se descartaron. Nygard propone un formato corto, de una o dos páginas, numerado de forma correlativa y con cinco partes:
| Parte del registro | Qué responde | Por qué la necesita el agente |
|---|---|---|
| Título | De qué decisión se trata, en una frase nominal | Para encontrarla antes de tocar esa parte del código |
| Estado | Propuesta, aceptada, obsoleta o sustituida | Para no seguir una decisión que ya se cambió |
| Contexto | Qué fuerzas y restricciones había | Para saber si siguen existiendo |
| Decisión | Qué se decidió y qué alternativas se descartaron | Para no proponer de nuevo lo que ya se descartó |
| Consecuencias | Qué se gana y qué se acepta perder | Para saber qué se rompe si se cambia |
Estructura de Michael Nygard (2011); la columna del agente es elaboración propia de onext
Un ejemplo ilustrativo, inventado y sin relación con ningún cliente:
- Título: los pedidos se escriben solo desde el servicio de pedidos.
- Estado: aceptada.
- Contexto: varios servicios escribían en la misma tabla y los datos llegaban inconsistentes.
- Decisión: un solo servicio escribe; el resto publica eventos. Se descartó una base de datos por servicio por el coste de operar tantas.
- Consecuencias: un cambio en pedidos obliga a coordinar con el servicio de pedidos. Se acepta esa fricción.
Con esto delante, un agente al que se pide «escribe el pedido desde el servicio de facturación» debería poder detectar que choca con la decisión y parar a consultar. Sin ella, no tiene forma de saberlo.
Otra regla de la guía de Microsoft ayuda al agente: los registros aceptados no se editan. Si una decisión cambia, se escribe uno nuevo que sustituye al anterior y se enlazan, de modo que queda la historia de por qué cambió el rumbo.
Dónde ponerlas para que el agente las lea
Cane recomienda guardarlas en Git, junto al código, porque así tienen versiones, revisión y validación automática. Si la arquitectura abarca varios servicios y repositorios, propone un repositorio central de arquitectura que se añade como directorio adicional al ejecutar el agente. Y si ya viven en una wiki, un servidor MCP (Model Context Protocol) puede servirlas al agente, a costa de más infraestructura.
Conviene no confundir lo que hace cada capa. Las instrucciones compartidas orientan al agente en el día a día, como vimos en instrucciones compartidas y curadas. Lo que tiene que cumplirse se impone con controles, no con un archivo, como contamos en Claude Code para equipos: contexto no es control. El registro de decisiones es la tercera capa: no ordena nada, explica por qué las cosas son así.
Hasta dónde llevarlo: reglas que la máquina comprueba
Hay quien va más lejos. En marzo de 2026, un equipo de autores publicó en InfoQ «Architectural Governance at AI Speed». Proponen convertir cada decisión en una directiva breve que persona y agente puedan interiorizar, y que el agente compruebe contra el código. Describen el registro de decisiones como una «unidad atómica de intención» y señalan que, si cada registro tiene que aprobarse antes de implementarse, las personas acaban siendo el cuello de botella.
Riesgo Convertir decisiones en reglas que se comprueban solas es una tendencia, no una garantía. Las decisiones nuevas y las excepciones siguen necesitando a una persona que decida y firme, como explicamos en specs y agentes: dónde se firma.
Por dónde empezar si el código ya tiene años
Microsoft aconseja empezar el registro también en proyectos que ya existen y, si hay datos, generarlo retroactivamente a partir de las decisiones conocidas. No hace falta documentar el sistema entero: se empieza por la parte que el agente va a tocar, como explicamos en especificar el código legacy antes de los agentes.
- Lista las decisiones de esa parte del código que serían caras de revertir.
- Pregunta a quien las tomó, mientras siga en el equipo, el contexto y las alternativas que se descartaron.
- Escribe cada una en una o dos páginas, con las cinco partes, y guárdala en el repositorio.
- Haz que el agente las lea antes de tocar esa parte del código, y que una persona revise cualquier cambio que las contradiga.
- Cuando una decisión cambie, escribe otra que la sustituya y enlázalas.
Esto se apoya en el resto del método. El umbral de qué se especifica y qué no, según el Spec-Driven Development (SDD, desarrollo guiado por especificaciones), lo tratamos en las plantillas de SDD ya son gratis, y la red de pruebas que detecta los errores, en antes del agente, la red.
Dónde encaja onext
En AI-Accelerated Development construimos con tu equipo el contexto en el que trabaja la IA y el proceso con el que trabajáis. Los dos se quedan en tu casa. Una persona decide donde hay riesgo. El primer paso es un diagnóstico gratuito, y si en el diagnóstico no vemos diferencia, no hay Quick-start. Si quieres ver antes dónde está tu equipo, el autodiagnóstico de 16 preguntas es un buen punto de partida.
Preguntas frecuentes
¿Qué es un registro de decisión de arquitectura (ADR)?
Es un documento corto que anota una decisión de arquitectura: qué se decidió, en qué contexto y con qué consecuencias. Michael Nygard lo propuso en 2011 con cinco partes: título, estado, contexto, decisión y consecuencias.
¿Por qué un agente necesita las decisiones por escrito?
Porque no tiene a quién preguntar. Benjamin Cane lo resume así: a diferencia de un ingeniero, un agente no recibe contexto de las conversaciones de pasillo, de acompañar a otros ni del conocimiento que solo está en la cabeza del equipo. Solo conoce lo que se captura.
¿Qué decisiones merecen un registro?
Las que afectan a la estructura del sistema, a sus atributos de calidad clave o que son difíciles de revertir. Microsoft aconseja incluir solo esas.
¿Se puede editar un registro ya aprobado?
No conviene. La guía de Microsoft lo trata como un registro de solo añadir: si una decisión cambia, se escribe un registro nuevo que sustituye al anterior y se enlazan, de modo que se conserva por qué cambió el rumbo.
¿Dónde se guardan para que el agente los lea?
Cane recomienda guardarlos en Git junto al código, porque así tienen versiones y revisión. Si la arquitectura abarca varios repositorios, un repositorio central de arquitectura; si viven en una wiki, un servidor MCP (Model Context Protocol), a costa de más infraestructura.
¿Pueden las máquinas hacer cumplir las decisiones sin una persona?
Es una tendencia: InfoQ propone convertir cada decisión en una directiva breve que el agente comprueba contra el código. Las decisiones nuevas, y las excepciones, siguen necesitando a una persona que decida.
Fuentes
- Michael Nygard, «Documenting Architecture Decisions», Cognitect, 15 de noviembre de 2011.
- Microsoft Learn, «Maintain an architecture decision record (ADR)», Azure Well-Architected Framework, 10 de abril de 2026.
- Benjamin Cane, «Your coding agent is missing one thing: architectural context», 28 de mayo de 2026.
- Kyle Howard, Christian Johansen, Dana Katzenelson, Brian Rhoten y Warren Gray, «Architectural Governance at AI Speed», InfoQ, 26 de marzo de 2026.
- Las citas de fuentes en inglés están traducidas por onext. El ejemplo de registro, la columna sobre el agente y la lectura son elaboración propia de onext; el ejemplo es ilustrativo, inventado y no corresponde a ningún cliente.
Bernat López es fundador y CEO de onext, boutique de IA. Acompaña a equipos de desarrollo y de producto a trabajar con IA con método —especificación antes de programar, una persona que decide donde hay riesgo y Spec-Driven Development— y aplica a su propia empresa lo que propone: onext funciona con su propio sistema agéntico.
LinkedIn →