Cómo dejar de perder decisiones arquitectónicas en el código con Log4brains

¿Alguna vez miraste un módulo que tiene un año y medio de antigüedad, viste una extraña decisión arquitectónica y genuinamente no entendiste por qué se tomó? Tus manos te pican por reescribirlo. Pero entonces descubres que este detalle fue diseñado específicamente para trabajar alrededor de un bug en una API de terceros o un requisito de seguridad particular. La persona que se le ocurrió ya se mudó a otro equipo, Confluence está vacío, y todo lo que queda en git es un commit con el lacónico fix: refactor storage.

El concepto de Architecture Decision Records (ADR) ha estado resolviendo este problema durante trece años. Pero mantener manualmente archivos markdown y mantenerlos organizados es usualmente algo con lo que todos están demasiado perezosos para hacer. El desarrollador francés Thomas Vaillant creó Log4brains, una herramienta que convierte la captura de decisiones arquitectónicas en un flujo de trabajo conveniente de docs-as-code.

Qué es esta herramienta

Log4brains toma tus ADR, almacenados en el repositorio junto con tu código fuente, los analiza y construye un sitio estático rápido con búsqueda conveniente y una línea de tiempo.

La utilidad está escrita en TypeScript y se ejecuta a través de la línea de comandos. Sin embargo, el proyecto no está atado al ecosistema JS. Puedes ejecutarlo en repositorios de Python, Go, Java o Rust a través de un paquete npm global o imagen Docker.

El punto de los ADR es que estos documentos son inmutables. Registras el problema, el contexto, la opción elegida y las consecuencias. Si una decisión queda obsoleta un año después, no editas el archivo antiguo de forma retroactiva. Creas un nuevo ADR con un estado de supersedes que referencia al anterior. El historial de pensamiento permanece intacto.

Qué puede hacer Log4brains

Bajo el capó, la utilidad esconde varias características prácticas que ahorran tiempo cuando trabajas con documentación.

Vista previa local con recarga en caliente

Cuando estás escribiendo documentación en tu IDE, no hay necesidad de reconstruir manualmente el sitio estático constantemente. El comando log4brains preview inicia un servidor local basado en Next.js con Hot Reload. Guardaste el archivo .md — el navegador se actualiza instantáneamente.

CLI interactivo sin restricciones rígidas

Muchas utilidades ADR requieren una numeración estricta de archivos como adr-0001.md, adr-0002.md. Esto se convierte en una pesadilla durante pull requests paralelos cuando dos desarrolladores crean documentos con el mismo número.

Log4brains no depende de una numeración rígida. Los metadatos (autor, fecha de creación, estado) se leen del texto y del log de git. Las plantillas pueden personalizarse según tus necesidades, aunque el formato MADR, bien probado, se usa por defecto.

Crear un nuevo registro se ve simple:

log4brains adr new

El comando preguntará interactivamente el título, creará un archivo markdown desde la plantilla y lo colocará en la estructura del proyecto.

Soporte para monorepos

Si el proyecto está dividido en múltiples paquetes, a menudo es deseable separar la documentación. Log4brains puede manejar decisiones globales de nivel superior y registros dependientes de paquetes dentro de packages/service-name/docs/adr.

Cómo comenzar

Todo comienza con un par de comandos en la terminal. Necesitarás Node.js LTS y Git:

npm install -g log4brains
log4brains init

El asistente de configuración hará algunas preguntas básicas, creará el archivo de configuración .log4brains.yml, añadirá una plantilla al proyecto y generará tu primer ADR de bienvenida.

La configuración termina siendo compacta:

project:
  name: My Service
  tz: Europe/Moscow
  adrFolder: ./docs/adr

Si tienes un monorepo, puedes expandir la estructura:

project:
  name: Core Platform
  tz: Europe/Moscow
  adrFolder: ./docs/adr
  packages:
    - name: auth-service
      path: ./packages/auth
      adrFolder: ./packages/auth/docs/adr
    - name: billing-service
      path: ./packages/billing
      adrFolder: ./packages/billing/docs/adr

Publicación en CI/CD

La parte más valiosa es desplegar la base de conocimientos externamente para que el equipo pueda buscar soluciones a través de una interfaz web. Dado que el build genera archivos estáticos limpios, es fácil empujar a GitHub Pages, GitLab Pages o S3.

Ejemplo para GitHub Actions:

name: Publish Log4brains
on:
  push:
    branches:
      - main
jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
          fetch-depth: 0 # обязательно, утилите нужна история git
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Build
        run: |
          npm install -g log4brains
          log4brains build --basePath /${GITHUB_REPOSITORY#*/}/log4brains
      - name: Deploy
        uses: JamesIves/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .log4brains/out
          TARGET_FOLDER: log4brains

Un detalle importante: presta atención a fetch-depth: 0. La utilidad absolutamente necesita el historial completo de commits para extraer las fechas reales de creación y los autores de cada documento.

Quién se beneficiará de este proyecto

Log4brains es una buena opción para equipos de 3-4 ingenieros o más, donde la gente periódicamente hace preguntas como "¿por qué elegimos esta biblioteca/base de datos/patrón".

La herramienta encaja bien en el proceso de revisión de código. Discutes la arquitectura en un pull request, mezclas el código junto con el archivo .md en el mismo commit. La documentación no vive una vida separada en páginas wiki olvidadas — se actualiza automáticamente durante el despliegue.

Si el proyecto es pequeño y estás trabajando solo, la sobrecarga de documentar decisiones podría parecer innecesaria. Pero para productos de larga vida, esta es una de las formas más painless de preservar el contexto de las decisiones.