La documentación ahora es contexto ejecutable
La documentación era para humanos que nunca la leían. Ahora tu IA lee cada palabra. Eso invierte la economía de documentar: una página que nadie abrió el año pasado hoy se inyecta en el contexto de un agente en cada tarea que toca tu código. Documentar dejó de ser una tarea pendiente para humanos del futuro y se convirtió en contexto ejecutable — texto que dirige directamente lo que tu agente de código construye después.
El código muestra el qué. Nunca el porqué
Un agente (o un compañero nuevo) puede leer tu código y reconstruir qué se construyó. Lo que el código nunca muestra es el porqué: qué restricción forzó el diseño, qué tres alternativas evaluaste y por qué las rechazaste. Sin eso, un agente al que le pides "mejorar" un módulo va a reabrir con gusto una pregunta ya resuelta — cambiando la cola que elegiste deliberadamente por la opción brillante que ya habías descartado.
La solución es una práctica de hace 15 años con un apalancamiento nuevo: el Architecture Decision Record (ADR), introducido por Michael Nygard en 2011. Un archivo corto por cada decisión significativa, guardado en el repositorio junto al código que gobierna. El Technology Radar de Thoughtworks mantiene los "lightweight architecture decision records" en su anillo Adopt desde 2018 — y recomienda específicamente guardarlos en control de versiones, no en una wiki, para que viajen con el código. Y el control de versiones es exactamente donde leen los agentes de código.
El registro de 10 minutos
La plantilla de Nygard ocupa una o dos páginas, cinco secciones. La versión ligera que la mayoría de los equipos usa hoy necesita cuatro:
| Sección | Pregunta que responde | Ejemplo en una línea |
|---|---|---|
| Contexto | ¿Qué fuerzas estaban en juego? | "Ráfagas de 10k trabajos/min; el equipo ya opera Postgres, sin presupuesto de ops para infraestructura nueva." |
| Decisión | ¿Qué elegimos? Voz activa: "Vamos a…" | "Vamos a usar Postgres SKIP LOCKED como cola de trabajos." |
| Alternativas | ¿Qué consideramos y rechazamos, y por qué? | "Redis (otro servicio que operar), SQS (dependencia de proveedor para un producto portable)." |
| Consecuencias | ¿Qué se vuelve más fácil y qué más difícil? | "Cero infraestructura nueva; el throughput lo limita la base de datos — revisar si pasamos de 50k trabajos/min." |
Numera los archivos y nunca borres uno. Una decisión reemplazada recibe status: superseded by ADR-0012 — la historia de los cambios de opinión también es contexto. Si quieres un formato mantenido y amigable para máquinas con front matter YAML, usa MADR (Markdown Any Decision Records); agrega secciones opcionales como Decision Drivers y Pros/Cons of the Options.
# ADR-0007: Postgres SKIP LOCKED as the job queue
Status: accepted
Context: 10k jobs/min bursts; team runs Postgres; no ops budget.
Decision: We will use Postgres SKIP LOCKED. No new broker.
Alternatives: Redis Streams (new service), SQS (vendor lock-in).
Consequences: zero new infra; revisit if we exceed 50k jobs/min.Diez minutos de escritura. Paga dos veces: tu agente deja de re-decidir la pregunta, y los humanos dejan de re-debatirla seis meses después.
Trucos avanzados
- Apunta a tu agente a la carpeta. Agrega una línea a tu archivo de instrucciones del agente (
CLAUDE.md,AGENTS.mdo equivalente): "Antes de proponer cambios de arquitectura, leedocs/decisions/y trata los ADRs aceptados como restricciones." Ahora cada registro que escribes se aplica automáticamente. - Que el agente escriba el primer borrador. Después de una discusión de diseño en una sesión con el agente, cierra con: "Escribe un ADR de lo que acabamos de decidir — contexto, decisión, alternativas rechazadas, consecuencias." Tú editas; el agente redacta. Los 10 minutos bajan a 3.
- Condiciona los PRs a las decisiones. Un PR que cambia una base de datos, un framework o una API pública sin tocar
docs/decisions/debería disparar una pregunta en el review. Algunos equipos lo codifican como regla de lint o ítem del checklist de PR. - Escribe el rechazo, no solo al ganador. La línea de mayor valor para un agente es la alternativa que rechazaste y por qué — es lo único que evita la regresión confiada a la opción obvia pero equivocada.
Recursos
- Documenting Architecture Decisions — Michael Nygard (2011) — la plantilla ADR original: título, contexto, decisión, estado, consecuencias.
- Organización ADR en GitHub — definiciones, contexto histórico y el hub de plantillas y herramientas.
- MADR — Markdown Any Decision Records — plantilla ligera mantenida, con front matter YAML.
- Lightweight Architecture Decision Records — Thoughtworks Technology Radar — anillo Adopt; guarda los registros en control de versiones.
- architecture-decision-record — plantillas y ejemplos reales — Nygard, MADR, arc42 y más, con ejemplos trabajados.
¿Construyendo una funcionalidad con IA? Yeda AI diseña, audita y entrega sistemas LLM de producción.