Cada diagrama de arquitectura que he visto en una wiki estaba equivocado. No dramáticamente equivocado. Solo silenciosa, incrementalmente equivocado. El servicio etiquetado como “Auth” se dividió en tres microservicios hace seis meses. La flecha marcada como “sync call” ahora es async via una queue. La base de datos etiquetada como “PostgreSQL” fue migrada a otra cosa durante un fire drill y nadie actualizó el recuadro.
Esto no es negligencia. Es física. El código cambia cientos de veces por semana. La documentación cambia cuando alguien se acuerda. La vida media de un diagrama de arquitectura es aproximadamente un sprint. Después de eso, se convierte en ficción.
El objetivo no es escribir docs que nunca se desvíen. El objetivo es detectar la desviación antes de que engañe al siguiente ingeniero.
Por qué los docs se descomponen más rápido que el código
El código tiene un mecanismo de corrección integrado: o compila y pasa los tests, o no. La documentación no tiene compiler, no tiene test suite, no tiene CI gate. Un diagrama equivocado se renderiza perfectamente. Un ADR desactualizado se lee con la misma convicción que uno fresco.
La divergencia también es social. Los ingenieros actualizan el código porque el build se rompe. Actualizan los docs porque se sienten culpables. La culpa es un scheduler poco confiable.
Cuando un ingeniero nuevo se une y lee la wiki, construye un mental model del sistema. Si ese modelo tiene seis meses de desfase, tomará decisiones que agravan el desorden existente. La documentación que se suponía que reduciría el onboarding friction se convierte en una fuente de subtle, expensive misdirection.
Las tres trampas de la ficción
Hay tres lugares donde la documentación de arquitectura se convierte en ficción más rápido.
El cementerio de la wiki. Los docs de arquitectura en Confluence, Notion o SharePoint viven fuera del repo. No tienen commit history correlacionado con los cambios de código. Cuando un refactor elimina un servicio, la página de la wiki sobrevive como un digital ghost town. Ningún build falla. Ninguna alert dispara.
La ficción del diagrama. Un diagrama hermoso exportado desde Lucidchart o draw.io y pegado en un README se ve autoritativo. También es una static image. El siguiente desarrollador que cambia la arquitectura tiene que abrir una design tool, encontrar el source file, actualizarlo, re-exportarlo y pegarlo de nuevo. Ese workflow tiene una tasa de supervivencia del 5%.
El README omnisciente. El README de nivel superior que intenta documentar cada servicio, cada dependencia y cada data flow en un solo archivo. Se convierte en un mega-documento que todos temen tocar. Eventualmente, un alma valiente agrega una nota: “Esta sección puede estar desactualizada.” Luego otra. Y luego todo el documento queda envuelto en scare quotes y abandonado.
Documentación viva que se mantiene honesta
La solución no es escribir más docs. Es hacer que los docs sean ineludibles.
Mueve los docs al repository. Si la documentación no está en el mismo pull request que el cambio de código, no se actualizará. Los ADRs, runbooks y decision logs deberían vivir en docs/architecture/ o docs/adr/ junto al código que describen. Cuando un reviewer ve un refactor sin actualización de docs, puede bloquear el merge.
Genera diagramas desde código. Mermaid, PlantUML y Structurizr te permiten definir diagramas en archivos de texto que viven en el repo. Un job de CI los renderiza en cada commit. Cuando la arquitectura cambia, el diagram source cambia con ella. No se requiere design tool.
<!-- docs/architecture/data-flow.md -->
## Ingestion Pipeline
```mermaid
graph LR
A[Client SDK] -->|HTTP POST| B[Ingest API]
B -->|Pub/Sub| C[Event Consumer]
C -->|Write| D[(ClickHouse)]
Este diagrama es reviewable en un diff. Cuando el pipeline gana un nuevo Kafka topic, el cambio aparece en el mismo PR que agrega el consumer.
**Separa el "qué" del "por qué."** El codebase ya describe qué hace el sistema. Los comments, function names y types codifican la estructura actual. La documentación debería enfocarse en por qué el sistema se ve como se ve. Eso es lo que se desvía silenciosamente: el razonamiento detrás de una decisión, no la decisión en sí.
Los Architecture Decision Records capturan esto. Un ADR no es un spec. Es una nota con timestamp que dice: "En esta fecha, por estas razones, elegimos esto. Estas son las constraints que aceptamos." Cuando las constraints cambian, el ADR es superseded por uno nuevo. El registry antiguo permanece como historia.
## Automatiza el "qué," escribe el "por qué"
Los docs de arquitectura más honestos son los que no escribes a mano.
Las OpenAPI specs generadas desde el controller code describen tu API surface con precisión. TypeDoc, RustDoc o Javadoc describen tus internal types. Los dependency graphs generados por `cargo tree`, `go mod graph` o `webpack-bundle-analyzer` muestran la module structure real.
Para constraints de arquitectura de más alto nivel, los automated architecture tests actúan como una red de seguridad. En Java, ArchUnit puede enforce rules como "ningún package en `domain` puede depender de `infrastructure`." En Python, `import-linter` hace lo mismo. En Go, puedes escribir un small test que recorre el AST y falla el build si aparece un forbidden import.
```java
// This test fails the build if architecture rules break.
@ArchTest
static final ArchRule domain_independence =
noClasses()
.that().resideInAPackage("..domain..")
.should().dependOnClassesThat()
.resideInAPackage("..infrastructure..");Cuando un desarrollador importa accidentalmente el package equivocado, el build se rompe inmediatamente. El architecture doc no necesita advertirle. El compiler lo hace.
Los trade-offs que nadie admite
La documentación viva no es gratis. Cuesta review time, CI minutes y la occasional argument sobre si un cambio justifica un nuevo ADR.
No todo sistema necesita un diagrama. Un monolito único con tres capas no necesita un C4 model. El esfuerzo para mantener docs generados debería ser proporcional al dolor de malinterpretar el sistema. Si el mental model equivocado te cuesta un día de debugging, invierte una hora en un diagrama. Si te cuesta cinco minutos, escribe un comment.
Los docs generados también pueden mentir. Una OpenAPI spec generada desde el código describe cada endpoint, incluidos los internal ones que olvidaste documentar. Un dependency graph muestra cada import, incluidos los que violan tu arquitectura. La verdad generada es accurate pero no siempre útil. Aún necesitas human curation para destacar lo que importa.
Los ADRs se acumulan. Después de dos años, puedes tener treinta ADRs en docs/adr/. La mayoría serán irrelevantes. La solución no es eliminarlos. Es marcarlos claramente: status: superseded con un link al reemplazo. La historia tiene valor. La confusión no.
Una configuración mínima que funciona
No necesitas una documentation platform. Necesitas tres cosas en tu repo.
docs/adr/YYYY-MM-DD-title.mdpara decisiones. Usa un template ligero:
# ADR 012: Event Storage Backend
- Status: accepted
- Date: 2026-03-15
## Context
We need durable storage for ingestion events with sub-second query latency.
## Decision
Use ClickHouse for hot storage, S3 for cold archival.
## Consequences
- Fast analytical queries on recent data.
- Complex operational footprint compared to PostgreSQL.
- Migration path defined in ADR 013.-
docs/architecture/*.mdcon diagramas Mermaid para system boundaries y data flow. Requiere una actualización de docs en el mismo PR que los cambios estructurales de código. -
Un architecture test que enforce tu invariant más costoso. Si solo tienes una regla, que sea la que previene el último painful refactor. Agrega más a medida que el sistema crece.
FAQ
¿Necesito diagramar cada microservicio?
No. Diagrama los boundaries donde los equipos se entregan trabajo, donde los datos cruzan trust zones y donde los failures cascadan. Un diagrama de tu internal CRUD service suele ser waste. Un diagrama de qué services llaman al payment gateway suele ser valioso.
¿Y si mi equipo ya usa Confluence?
Espeja los docs críticos en el repo y linkea hacia afuera. La source of truth permanece en git. La wiki se convierte en una convenience layer. Si la wiki se desvía, los ingenieros saben dónde encontrar la versión real.
¿Cuántos ADRs son demasiados?
No hay un límite superior, pero sí un readability limit. Si un ingeniero nuevo no puede escanear docs/adr/ y entender la evolución del sistema en diez minutos, agrega un index. Agrupa por subsystem. Marca los registries superseded claramente.
¿Qué pasa con las wikis para stakeholders no técnicos?
Los product managers y ejecutivos necesitan high-level summaries. Genera esos desde el ADR index. No mantengas una narrative separada. Los mismos hechos deberían fluir desde el source code, a través de los ADRs, hacia los human summaries. Una source of truth, multiple views.
Empieza con un ADR y un test
No necesitas renovar tu documentation culture esta semana. Elige la última architectural decision que causó confusión. Escribe un ADR explicando por qué elegiste lo que elegiste. Elige el invariant que desearías que se enforce automáticamente. Escribe un architecture test que falle el build cuando alguien lo viole.
Esos dos artifacts se mantendrán honestos porque viven en el repo, se revisan en PRs y o pasan CI o no se envían. Todo lo demás, las wiki pages, los slide decks, los conference posters, es secundario. Nice to have. Posiblemente útil. Probablemente equivocado.