From 4dbdc15988f61e79853e54bc685cbda851f87c46 Mon Sep 17 00:00:00 2001 From: Fernando Rivas Date: Wed, 19 Aug 2026 00:16:23 -0600 Subject: [PATCH] docs: formalizar decisiones de arquitectura (ADR) y enlazarlas desde el README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/ADR.md documenta alcance, campos, secciones y un ejemplo para docs/adr/. Deja explícito que son decisiones sobre clusterlog (la herramienta), no sobre el clúster administrado, y que no tienen equivalente en la UI ni en la CLI. --- README.md | 1 + docs/ADR.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 docs/ADR.md diff --git a/README.md b/README.md index 579b3a6..462f0e6 100644 --- a/README.md +++ b/README.md @@ -175,6 +175,7 @@ docs/ decisiones arquitectónicas y operación - [`SECURITY.md`](SECURITY.md): modelo de confianza y despliegue recomendado. - [`THEME_COMPATIBILITY.md`](THEME_COMPATIBILITY.md): estrategia para `zola.386`. - [`docs/WEEKLY_REVIEW.md`](docs/WEEKLY_REVIEW.md): guion de la reunión semanal. +- [`docs/ADR.md`](docs/ADR.md): decisiones de diseño de **clusterlog** (la herramienta), no del clúster que administra; formato, campos y ejemplo. Registros en [`docs/adr/`](docs/adr/), sin equivalente en la UI del sitio ni en la CLI. - [`VALIDATION_REPORT.md`](VALIDATION_REPORT.md): pruebas ejecutadas, límites y controles pendientes. - [`RELEASE_NOTES.md`](RELEASE_NOTES.md): alcance de la entrega 0.1.0. diff --git a/docs/ADR.md b/docs/ADR.md new file mode 100644 index 0000000..515e8f6 --- /dev/null +++ b/docs/ADR.md @@ -0,0 +1,113 @@ +# Decisiones de arquitectura (ADR) + +## Alcance + +Un ADR (*Architecture Decision Record*) documenta una decisión de diseño sobre **clusterlog**: la herramienta, su modelo de datos, su CLI, su proyección estática y su cadena de confianza. No es el lugar para decisiones operativas del clúster que administra el equipo (topología de nodos, políticas de red, capacidad, etc.); esas pertenecen a **Manuales** o **Memorias** dentro del sitio. + +Un ADR se justifica cuando la decisión: + +- es costosa o difícil de revertir; +- afecta el modelo de datos, la identidad/firma, o el contrato de la CLI; +- descarta una alternativa razonable por un motivo que no es obvio leyendo el código; +- va a ser preguntada de nuevo en el futuro ("¿por qué no usamos X?"). + +No se justifica para elección de librerías internas reversibles, estilo de código, o correcciones de bugs — eso va en el mensaje de commit o, si amerita contexto, en una memoria. + +## Dónde viven y cómo se gestionan + +- Los archivos están en [`docs/adr/`](adr/), uno por decisión. +- **No se ven en la UI del sitio ni se gestionan con la CLI de `clusterlog`.** `docs/adr/` no forma parte de `content/` (lo que Zola proyecta) y no existe ningún comando `clusterlog adr *`. Son Markdown plano, editado a mano, versionado y revisado como el resto del repositorio. +- Se crean, discuten y aprueban por revisión de código normal (pull request), igual que cualquier otro cambio al repositorio. + +## Nombre de archivo + +```text +docs/adr/NNNN-titulo-en-kebab-case.md +``` + +- `NNNN`: número secuencial de 4 dígitos, sin reutilizar ni renumerar al superar un ADR. +- El slug es una versión corta del título en minúsculas, con guiones. + +## Campos y secciones + +Cada ADR sigue esta estructura, en este orden: + +```markdown +# ADR-NNNN: Título de la decisión + +- **Estado:** propuesta | aceptada | rechazada | reemplazada por ADR-MMMM +- **Fecha:** AAAA-MM-DD + +## Contexto + +## Decisión + +## Consecuencias positivas + +## Consecuencias negativas + +## Alternativas descartadas (opcional) + +## Regla de interpretación (opcional) +``` + +| Campo/Sección | Obligatorio | Contenido | +|---|---|---| +| Título | sí | Frase corta que nombra la decisión, no el problema. | +| Estado | sí | Uno de: `propuesta`, `aceptada`, `rechazada`, `reemplazada por ADR-MMMM`. Un ADR aceptado no se borra ni se edita para invertir la decisión; se agrega uno nuevo que lo reemplaza y se actualiza el estado del anterior. | +| Fecha | sí | Fecha en que el estado actual entró en vigor. | +| Contexto | sí | La fuerza o restricción que exige decidir: qué problema, qué tensión, qué no puede seguir igual. Sin esto, la decisión no se puede evaluar más adelante. | +| Decisión | sí | Qué se decidió, en términos concretos y verificables (no aspiracionales). | +| Consecuencias positivas | sí | Efectos deseables que se aceptan a cambio. | +| Consecuencias negativas | sí | Costos, riesgos o deuda que la decisión introduce a sabiendas. Un ADR sin consecuencias negativas es sospechoso. | +| Alternativas descartadas | no | Opciones consideradas y por qué se descartaron. Útil cuando la pregunta "¿por qué no X?" es previsible. | +| Regla de interpretación | no | Aclaración normativa para evitar que la decisión se lea de forma laxa (ver ADR-0002 como ejemplo). | + +## Ejemplo + +```markdown +# ADR-0004: Límite de tamaño para eventos JSON individuales + +- **Estado:** aceptada +- **Fecha:** 2026-08-18 + +## Contexto + +Los eventos de `data/review-events/` y `data/task-events/` son archivos JSON +inmutables, uno por evento. Nada impide hoy que un evento incluya un adjunto +grande o un volcado de log completo, lo que degradaría `clusterlog sync` y +ensuciaría el historial Git con blobs pesados. + +## Decisión + +- Cada archivo de evento se limita a 64 KB. +- La CLI rechaza la escritura si el JSON serializado excede el límite, + con un mensaje que indica el tamaño real y el máximo permitido. +- El límite se valida antes de firmar o comitear, nunca después. + +## Consecuencias positivas + +- El historial Git permanece liviano y rápido de clonar. +- `clusterlog sync` tiene un tiempo de ejecución más predecible. +- Fuerza a resumir en vez de adjuntar evidencia extensa. + +## Consecuencias negativas + +- Evidencia grande (logs completos, capturas) debe vivir fuera del evento + y referenciarse por enlace o ticket. +- El límite es arbitrario y puede requerir ajuste con el uso real. + +## Alternativas descartadas + +- Sin límite: expone el repositorio a crecer sin control y a bloquear CI. +- Comprimir el evento: complica la lectura directa con herramientas + estándar de Git, que es una propiedad central de ADR-0001. +``` + +## Relación con otros tipos de contenido + +- **ADR**: por qué el software está diseñado así. Vive en `docs/adr/`, no se sincroniza al sitio. +- **Manual** (`content/manuales/`): cómo ejecutar un procedimiento repetible sobre el clúster o la bitácora. Sí se publica en el sitio. +- **Memoria**: qué se hizo, cuándo, por quién, con qué validación y reversión, en una sesión concreta. Sí se publica en el sitio. + +Si al escribir una memoria o un manual surge una decisión de diseño reutilizable que no está documentada, es señal de que falta un ADR — no de que deba explicarse de nuevo cada vez.