Todo lo que necesitas saber sobre Architecture Decision Records (ADR) y su impacto en el desarrollo asistido por IA
Esta va a ser mi primera vez escribiendo sobre IA, y por seguir con el espíritu de este blog, no me gustaría hacer el típico artículo con “los mejores 10 prompts para hacer vibe coding” o “llevas toda la vida usando mal Claude Code” o “Prompt Engineer: From Zero to Hero”.
No. En este blog siempre hemos hablado de ingeniería, y pretendo que así siga.
En esta ocasión, me gustaría hablar sobre cómo incorporar herramientas y prácticas clásicas de la ingeniería de software a nuestro flujo de desarrollo con IA. Estas prácticas, que a veces se hacen bola por el trabajo de mantenimiento que implican, viven ahora su mejor momento: nunca han sido tan útiles y fáciles de mantener como ahora.
Los que trabajamos con herramientas de desarrollo asistido por IA como Claude Code, Cursor o GitHub Copilot sabemos que el mayor desafío no es generar código, sino generar el código correcto. El que respeta las decisiones que ya se tomaron. El que no repite errores que ya descartamos. El que entiende el porqué detrás de cada elección arquitectónica.
Aquí es donde entran los Architecture Decision Records (ADRs): una herramienta de documentación que, en el contexto del desarrollo asistido por IA, se convierte en algo mucho más poderoso: memoria persistente.
¿Qué es un ADR?
Personalmente yo conocí ADR hace unos 5 años, y tras ver su potencial, no he dejado de intentar potenciar su uso en mi empresa. Y no es tarea fácil, porque requiere de leer y actualizar mucha documentación, y eso no le gusta a nadie.
Pero vamos al grano, ¿Qué es un ADR?
Un Architecture Decision Record es un documento que captura una decisión arquitectónica junto con su contexto y consecuencias. El concepto fue popularizado por Michael Nygard en 2011 y desde entonces se ha convertido en una práctica fundamental en equipos de desarrollo serios.
La idea es sencilla: cada vez que tomamos una decisión significativa sobre la arquitectura de nuestro sistema, la documentamos. No solo qué decidimos, sino por qué lo decidimos, qué alternativas consideramos, y qué consecuencias esperamos.
Un ADR responde a preguntas como:
- ¿Por qué usamos PostgreSQL en lugar de MongoDB?
- ¿Por qué elegimos una arquitectura de microservicios?
- ¿Por qué descartamos usar GraphQL?
El formato de un ADR
Existen varios templates, pero el más extendido es MADR (Markdown Architectural Decision Records). Su estructura es clara y práctica:
---
status: accepted
date: 2024–01–15
decision-makers: [Miguel Ángel Sánchez, Equipo Backend]
---
# Usar PostgreSQL como base de datos principal
## Contexto y problema
Necesitamos elegir una base de datos para nuestra aplicación de gestión
de inventario. El sistema requiere transacciones ACID, consultas complejas
con JOINs, y debe manejar ~50k operaciones diarias.
## Opciones consideradas
1. **PostgreSQL** - Base de datos relacional open-source
2. **MongoDB** - Base de datos documental NoSQL
3. **MySQL** - Base de datos relacional tradicional
## Decisión
Elegimos **PostgreSQL** porque:
- Soporte nativo para tipos JSON cuando necesitemos flexibilidad
- Mejor rendimiento en consultas complejas con JOINs
- Extensiones como PostGIS si necesitamos datos geoespaciales
- Comunidad activa y excelente documentación
## Consecuencias
### Positivas
- Transacciones ACID garantizadas
- Flexibilidad para evolucionar el esquema
- Equipo ya tiene experiencia con SQL
### Negativas
- Requiere más planificación inicial del esquema
- Escalado horizontal más complejo que con MongoDB
## Alternativas descartadas
- **MongoDB**: Descartada porque nuestro modelo de datos es altamente relacional
y las consultas con aggregation pipelines serían más complejas y menos
performantes que JOINs nativos.
- **MySQL**: Descartada por menor soporte de tipos avanzados y funcionalidades
que PostgreSQL ofrece out-of-the-box.Los campos esenciales son:
- Título: Describe la decisión en forma imperativa
- Contexto: El problema que estamos resolviendo
- Opciones: Las alternativas que evaluamos
- Decisión: Lo que elegimos y por qué
- Consecuencias: Impacto positivo y negativo
- Estado: proposed, accepted, deprecated, superseded
¿Por qué los ADRs son cruciales para el desarrollo con IA?
Aquí viene lo interesante. Cuando trabajas con Claude Code u otra herramienta de IA, esta no tiene memoria de sesiones anteriores. Cada conversación empieza de cero. La IA no sabe que hace tres meses decidiste usar Event Sourcing, ni que descartaste usar Redis como caché principal porque no encajaba con tu modelo de consistencia.
Sin esta información, la IA puede:
- Proponer soluciones ya descartadas: “¿Por qué no usamos Redis aquí?” — Porque ya lo evaluamos y no funcionaba para nuestro caso.
- Contradecir decisiones establecidas: Sugerir patrones que van en contra de tu arquitectura definida.
- Repetir errores del pasado: Implementar algo que ya probaste y falló.
Los ADRs actúan como memoria arquitectónica persistente. Le dan a la IA el contexto que necesita para tomar decisiones coherentes con la historia del proyecto.
Cómo redactar buenos ADRs (con asistencia de IA)
La buena noticia es que la propia IA puede ayudarte a documentar decisiones.
Si no sabes por dónde tirar, aquí van algunos prompts útiles:
Para crear un nuevo ADR
Estoy evaluando si usar [Tecnología A] o [Tecnología B] para [propósito].
Mi contexto es:
- [Requisitos técnicos]
- [Restricciones del equipo]
- [Consideraciones de negocio]
Ayúdame a estructurar un ADR que documente esta decisión, incluyendo:
1. Contexto claro del problema
2. Análisis de cada opción con pros/contras
3. Recomendación justificada
4. Consecuencias esperadasPara documentar una decisión ya tomada
Decidimos usar [Tecnología/Patrón] para [propósito]. Los motivos fueron:
- [Motivo 1]
- [Motivo 2]
Las alternativas que descartamos fueron [X] y [Y].
Genera un ADR en formato MADR que capture esta decisión para
documentación futura.
Para evaluar si una propuesta contradice ADRs existentes
Quiero implementar [nueva funcionalidad] usando [enfoque propuesto].
Revisa los ADRs existentes en /docs/decisions/ y dime si esta
propuesta contradice alguna decisión previa o si debería crear
un nuevo ADR que superceda alguno existente.
Organizando tus ADRs
La convención más común es almacenarlos en docs/decisions/ o docs/adr con una numeración secuencial:
docs/
└── adr/
├── 0001-usar-postgresql-como-base-de-datos.md
├── 0002-adoptar-arquitectura-hexagonal.md
├── 0003-usar-rabbitmq-para-mensajeria.md
├── 0004-descartar-graphql-usar-rest.md
└── README.md
El README.md puede incluir un índice con el estado de cada ADR (y la IA te puede ayudar a mantenerlo actualizado):
# Architecture Decision Records
| ADR | Título | Estado |
| - - -| - - - - | - - - - |
| 0001 | Usar PostgreSQL como base de datos | Accepted |
| 0002 | Adoptar arquitectura hexagonal | Accepted |
| 0003 | Usar RabbitMQ para mensajería | Superseded by 0007 |
| 0004 | Descartar GraphQL, usar REST | Accepted |
Integrando ADRs con Claude Code
Aquí es donde la magia tiene lugar. Claude Code lee automáticamente el archivo CLAUDE.md de tu proyecto al inicio de cada sesión. Este archivo es el lugar perfecto para conectar tus ADRs con la IA.
Aunque yo me voy a centrar en Claude Code, porque es lo que yo uso, estas prácticas son extrapolables a otras herramientas, como OpenCode, Cursor, Antigravity, Codex… y un largo etcetera.
Configuración en CLAUDE.md
# Proyecto: Sistema de Gestión de Inventario
## Arquitectura
Este proyecto sigue Arquitectura Hexagonal. Antes de proponer
cambios arquitectónicos, consulta los ADRs en `docs/decisions/`.
## Decisiones arquitectónicas clave
Antes de implementar nuevas funcionalidades, ten en cuenta:
- **Base de datos**: PostgreSQL (ver ADR-0001)
- **Arquitectura**: Hexagonal con puertos y adaptadores (ver ADR-0002)
- **Mensajería**: RabbitMQ para eventos de dominio (ver ADR-0003)
- **API**: REST, no GraphQL (ver ADR-0004)
## Instrucciones para Claude
1. Antes de proponer soluciones que involucren tecnologías no mencionadas,
verifica si existe un ADR que la haya evaluado previamente.
2. Si detectas que una implementación podría contradecir un ADR existente,
advierte antes de proceder.
3. Cuando se tome una nueva decisión arquitectónica significativa,
sugiere crear un nuevo ADR.Creando un comando personalizado para ADRs
Claude Code permite crear comandos personalizados. Puedes crear uno específico para trabajar con ADRs:
Crea el archivo .claude/commands/new-adr.md :
# Crear nuevo ADR
Analiza el contexto de la decisión que el usuario quiere documentar
y genera un ADR completo en formato MADR.
## Instrucciones
1. Lee los ADRs existentes en `docs/decisions/` para determinar
el siguiente número disponible
2. Pregunta al usuario por:
- El problema o contexto
- Las opciones que se evaluaron
- La decisión tomada y sus motivos
- Las consecuencias esperadas
3. Genera el archivo ADR con el formato correcto
4. Actualiza el README.md con la nueva entrada
## Formato de salida
El archivo debe seguir el template MADR y guardarse en
`docs/decisions/NNNN-titulo-con-guiones.md`Ahora puedes ejecutar /new-adr directamente en Claude Code para crear ADRs de forma guiada.
Comando para revisar coherencia arquitectónica
Crea .claude/commands/check-adr.md:
# Verificar coherencia con ADRs
Antes de implementar cambios significativos, verifica que no
contradigan decisiones arquitectónicas existentes.
## Instrucciones
1. Lee todos los ADRs en `docs/decisions/`
2. Analiza el cambio propuesto por el usuario
3. Identifica si hay conflictos con decisiones existentes
4. Si hay conflictos, explica cuáles y sugiere alternativas
5. Si la propuesta requiere superceder un ADR, indica cuál y por qué
## Output esperado
- Lista de ADRs relevantes revisados
- Conflictos encontrados (si los hay)
- Recomendación sobre cómo procederEjemplo práctico: flujo de trabajo con ADRs
Veamos un flujo completo de cómo trabajar con ADRs en Claude Code:
1. El desarrollador quiere añadir caché
> Necesito añadir una capa de caché para mejorar el rendimiento
de las consultas más frecuentes. ¿Qué opciones tengo?2. Claude Code consulta los ADRs existentes
Claude lee los ADRs y puede responder algo como:
He revisado los ADRs existentes. En ADR-0006 se evaluó usar Redis
como caché pero se descartó porque contradecía el modelo de
consistencia fuerte requerido por el sistema (ADR-0001 establece
que todas las operaciones deben ser ACID).
Las opciones compatibles con tu arquitectura serían:
1. Caché en memoria a nivel de aplicación (ej: Caffeine en Java)
2. Caché de segundo nivel de Hibernate con EhCache
3. Materialized views en PostgreSQL
¿Quieres que analicemos estas opciones y creemos un nuevo ADR?3. Se documenta la nueva decisión
> Vamos con materialized views. Documéntalo como ADR.Claude genera el ADR correspondiente, lo guarda en docs/decisions/0008-usar-materialized-views-para-cache.md, y actualiza el índice.
Beneficios a largo plazo
Mantener ADRs actualizados cuando trabajas con IA tiene beneficios compuestos:
- Onboarding acelerado: Nuevos desarrolladores (y nuevas sesiones de IA) entienden el contexto inmediatamente.
- Decisiones consistentes: La IA no propondrá soluciones que contradigan el historial del proyecto.
- Reducción de errores: No repetirás aproximaciones que ya fallaron.
- Documentación viva: Los ADRs crecen orgánicamente con el proyecto.
- Mejor colaboración: El equipo tiene un registro claro de por qué las cosas son como son.
Conclusión
Los ADRs no son solo documentación: son contexto para el futuro. En un mundo donde cada vez más desarrollamos asistidos por IA, ese contexto se vuelve crítico. La IA es tan buena como la información que le proporcionamos, y los ADRs son una de las formas más efectivas de transmitir el conocimiento arquitectónico acumulado.
La próxima vez que tomes una decisión arquitectónica significativa, no la dejes solo en tu cabeza o en un hilo de Slack que nadie encontrará. Documéntala como ADR. Tu yo del futuro (y tu asistente de IA) te lo agradecerán.
Recursos adicionales y lecturas recomendadas de ADR
- Repositorio con ejemplos de ADR y templates
- Microsoft Azure — Buenas prácticas de ADR
- Estudio sobre LLMs y generación de ADRs
- Artículo sobre acelerar ADRs con IA generativa
Si estás trabajando con Claude Code y quieres sacarle más partido en tu día a día, te recomendamos leer también nuestro artículo sobre cómo estructurar mejor tus conversaciones con la herramienta y evitar resultados incoherentes:
Spanish 
English 