Come smettere di perdere le decisioni architetturali nel codice con Log4brains

Ti è mai capitato di guardare un modulo vecchio di un anno e mezzo, vedere una strana decisione architetturale e non capire davvero perché sia stata presa? Vorresti riscriverlo. Ma poi scopri che questa particolarità era specificamente progettata per gestire un bug in un'API di terze parti o un particolare requisito di sicurezza. La persona che l'ha pensata è ormai passata a un altro team, Confluence è vuoto, e tutto ciò che rimane in git è un commit con il laconico fix: refactor storage.

Il concetto di Architecture Decision Records (ADR) risolve questo problema da tredici anni. Ma mantenere manualmente i file markdown e organizzarli è qualcosa che tutti sono troppo pigri per fare. Lo sviluppatore francese Thomas Vaillant ha creato Log4brains, uno strumento che trasforma la cattura delle decisioni architetturali in un comodo workflow docs-as-code.

Cos'è questo strumento

Log4brains prende i tuoi ADR, archiviati nel repository insieme al codice sorgente, li analizza e costruisce un sito statico veloce con ricerca comoda e una timeline.

L'utilità è scritta in TypeScript e funziona tramite riga di comando. Tuttavia, il progetto non è legato all'ecosistema JS. Puoi eseguirlo in repository Python, Go, Java o Rust tramite un pacchetto npm globale o immagine Docker.

Il punto degli ADR è che questi documenti sono immutabili. Registri il problema, il contesto, l'opzione scelta e le conseguenze. Se una decisione diventa obsoleta un anno dopo, non modifichi il vecchio file retroattivamente. Crei un nuovo ADR con uno stato supersedes che fa riferimento al precedente. La cronologia dei pensieri rimane intatta.

Cosa può fare Log4brains

Sotto il cofano, l'utilità nasconde diverse funzionalità pratiche che fanno risparmiare tempo quando si lavora con la documentazione.

Anteprima locale con ricarica a caldo

Quando scrivi documentazione nel tuo IDE, non c'è bisogno di ricostruire manualmente il sito statico costantemente. Il comando log4brains preview avvia un server locale basato su Next.js con Hot Reload. Hai salvato il file .md — il browser si aggiorna istantaneamente.

CLI interattiva senza restrizioni rigide

Molti strumenti ADR richiedono una numerazione rigorosa dei file come adr-0001.md, adr-0002.md. Questo diventa un incubo durante i pull request paralleli quando due sviluppatori creano documenti con lo stesso numero.

Log4brains non si affida a una numerazione rigida. I metadati (autore, data di creazione, stato) vengono letti dal testo e dal log git. I template possono essere personalizzati secondo le tue esigenze, anche se il formato MADR collaudato viene utilizzato per impostazione predefinita.

Creare un nuovo record sembra semplice:

log4brains adr new

Il comando chiederà interattivamente il titolo, creerà un file markdown dal template e lo posizionerà nella struttura del progetto.

Supporto monorepo

Se il progetto è suddiviso in più pacchetti, spesso si desidera separare la documentazione. Log4brains può gestire decisioni globali a livello superiore e record dipendenti dal pacchetto all'interno di packages/service-name/docs/adr.

Come iniziare

Tutto inizia con un paio di comandi nel terminale. Avrai bisogno di Node.js LTS e Git:

npm install -g log4brains
log4brains init

La procedura guidata di configurazione farà alcune domande di base, creerà il file di configurazione .log4brains.yml, aggiungerà un template al progetto e genererà il tuo primo ADR di benvenuto.

La configurazione risulta essere compatta:

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

Se hai un monorepo, puoi espandere la struttura:

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

Pubblicazione in CI/CD

La parte più preziosa è distribuire la knowledge base esternamente per permettere al team di cercare soluzioni tramite un'interfaccia web. Poiché il build produce file statici puliti, è facile eseguirne il push su GitHub Pages, GitLab Pages o S3.

Esempio per 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 dettaglio importante: presta attenzione a fetch-depth: 0. L'utilità ha assolutamente bisogno della cronologia completa dei commit per estrarre le date di creazione effettive e gli autori di ciascun documento.

Chi trarrà beneficio da questo progetto

Log4brains si adatta bene a team di 3-4 ingegneri o più, dove le persone periodicamente fanno domande come "perché abbiamo scelto questa libreria/database/pattern".

Lo strumento si integra bene nel processo di code review. Discuti l'architettura in una pull request, fai il merge del codice insieme al file .md nello stesso commit. La documentazione non vive una vita separata su pagine wiki dimenticate — viene aggiornata automaticamente durante il deployment.

Se il progetto è piccolo e ci lavori da solo, il sovraccarico di documentare le decisioni potrebbe sembrare non necessario. Ma per prodotti di lunga durata, questo è uno dei modi più indolori per preservare il contesto delle decisioni.