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?
A 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]
---
# Use PostgreSQL like base from datos principal
## Contexto y problem
Necesitamos elegir una base from datos for nuestra application from gestión
from inventario. The sistema requiere transacciones ACID, consultas complejas
con JOINs, y debe manejar ~50k operaciones diarias.
## Opciones consideradas
1. **PostgreSQL** - Base from datos relacional open-source
2. **MongoDB** - Base from datos documental NoSQL
3. **MySQL** - Base from datos relacional tradicional
## Decisión
Elegimos **PostgreSQL** porque:
- Soporte nativo for tipos JSON when necesitemos flexibilidad
- Mejor rendimiento at consultas complejas con JOINs
- Extensiones like PostGIS si necesitamos datos geoespaciales
- Comunidad activa y excelente documentación
## Consecuencias
### Positivas
- Transactions ACID garantizadas
- Flexibility for evolucionar the esquema
- Equipo ya tiene experiencia con SQL
### Negativas
- Requiere más planificación initial from esquema
- Escalado horizontal más complejo que con MongoDB
## Alternativas descartadas
- **MongoDB**: Descartada porque our modelo from datos is altamente relacional
y las consultas con aggregation pipelines serían más complejas y menos
performantes que JOINs nativos.
- **MySQL**: Descartada por menor soporte from 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 [Technology A] o [Technology B] for [propósito].
Mi contexto is:
- [Requirements técnicos]
- [Restricciones from equipo]
- [Consideraciones from negocio]
Ayúdame a estructurar un ADR que documente esta decisión, incluyendo:
1. Contexto of course from problem
2. Analysis from cada opción con pros/contras
3. Recomendación justificada
4. Consecuencias esperadasPara documentar una decisión ya tomada
Decidimos usar [Technology/Patrón] for [propósito]. The motivos fueron:
- [Motivo 1]
- [Motivo 2]
The alternativas que descartamos fueron [X] y [Y].
Genera un ADR at formato MADR que capture esta decisión for
documentación futura.
Para evaluar si una propuesta contradice ADRs existentes
Quiero implementar [nueva funcionalidad] usando [enfoque propuesto].
Revisa los ADRs existentes at /docs/decisions/ y dime si esta
propuesta contradice alguna decisión previa o si debería crear
un new 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-like-base-from-datos.md
├── 0002-adoptar-arquitectura-hexagonal.md
├── 0003-usar-rabbitmq-for-mensajeria.md
├── 0004-descartar-graphql-usar-rest.md
└── README.md
The 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 | Use PostgreSQL like base from datos | Accepted |
| 0002 | Adoptar arquitectura hexagonal | Accepted |
| 0003 | Use RabbitMQ for 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 from Gestión from Inventario
## Arquitectura
Este proyecto sigue Arquitectura Hexagonal. Antes from proponer
cambios arquitectónicos, consulta los ADRs at `docs/decisions/`.
## Decisiones arquitectónicas clave
Antes from implementar nuevas funcionalidades, ten at cuenta:
- **Base from datos**: PostgreSQL (ver ADR-0001)
- **Arquitectura**: Hexagonal con puertos y adaptadores (ver ADR-0002)
- **Mensajería**: RabbitMQ for events from domain (ver ADR-0003)
- **API**: REST, no GraphQL (ver ADR-0004)
## Instrucciones for Claude
1. Antes from 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 from proceder.
3. Cuando se tome una nueva decisión arquitectónica significativa,
sugiere crear un new 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 new ADR
Analiza the contexto from la decisión que the user quiere documentar
y genera un ADR completo at formato MADR.
## Instrucciones
1. Lee los ADRs existentes at `docs/decisions/` for determinar
the siguiente número disponible
2. Pregunta at user por:
- The problem o contexto
- The opciones que se evaluaron
- The decisión tomada y sus motivos
- The consecuencias esperadas
3. Genera the archivo ADR con the formato correcto
4. Actualiza the README.md con la nueva entrada
## Formato from salida
The archivo debe seguir the template MADR y guardarse at
`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 from implementar cambios significativos, verifica que no
contradigan decisiones arquitectónicas existentes.
## Instrucciones
1. Lee todos los ADRs at `docs/decisions/`
2. Analiza the cambio propuesto por the user
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 from 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 from caché for mejorar the rendimiento
from 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. At ADR-0006 se evaluó usar Redis
like caché pero se descartó porque contradecía the modelo from
consistency fuerte requerido por the sistema (ADR-0001 establece
que all las operaciones should ser ACID).
The opciones compatibles con tu arquitectura serían:
1. Caché at memoria a nivel from application (ej: Caffeine at Java)
2. Caché from segundo nivel from Hibernate con EhCache
3. Materialized views at PostgreSQL
¿Quieres que analicemos estas opciones y we believe un new ADR?3. Se documenta la nueva decisión
> Vamos con materialized views. Documéntalo like 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.
Conclusion
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 